Перейти к основному содержимому

Введение

@powerduck/md-editor — высокопроизводительный Markdown-редактор для встраивания в браузер. Он объединяет область редактирования CodeMirror 6 с предпросмотром на основе markdown-it и поддерживает формулы KaTeX, интеллект-карты Markmap, подсветку кода, информационные блоки, настраиваемую панель инструментов, сочетания клавиш, обработчики загрузки изображений, @упоминания и вставку ссылок на документы.

  • Имя пакета: @powerduck/md-editor
  • Лицензия: MIT
  • Формат модуля: ECMAScript-модуль (type: "module") со сборками ESM (dist/index.mjs) и CJS (dist/index.cjs) и включёнными объявлениями типов (dist/index.d.ts).

Основные возможности​

Перечисленные возможности соответствуют реализованным модулям исходного кода:

  • Редактирование Markdown на базе CodeMirror 6, с подсветкой синтаксиса Markdown и светлой/тёмной темами подсветки.
  • Формулы KaTeX через самостоятельный плагин markdown-it: внутри строки $...$ и отдельным блоком $$...$$. Эвристики исключают денежные суммы вроде $5 из обработки формул.
  • Интеллект-карты Markmap из ограждённых блоков ```mindmap. markmap-lib и markmap-view импортируются динамически и не увеличивают начальный загружаемый пакет, если карт нет.
  • Подсветка кода через highlight.js, с тремя цветными точками в заголовке в стиле macOS, подписью языка и кнопкой копирования одним нажатием.
  • Информационные блоки (:::notice, :::info, :::tip, :::success, :::warning, :::danger) со значками и соответствующими цветами.
  • Предпросмотр в стиле GitHub с использованием github-markdown-css.
  • Полная панель инструментов с 22 действиями, диалогами вставки изображений, видео, YouTube и таблиц, выбором шаблонов формул и интеллект-карт и справкой по всем сочетаниям клавиш.
  • Сочетания клавиш с Mod, который соответствует Ctrl в Windows/Linux и Cmd в macOS.
  • Настраиваемая панель инструментов через массив включаемых элементов или отдельные настройки (show, label, icon).
  • Обработчик загрузки изображений (onImageUpload), вызываемый при вставке или перетаскивании изображения в редактор.
  • Раскрывающийся список @упоминаний, настраиваемый через mention; выбранные упоминания отображаются в предпросмотре как оформленные метки.
  • Вставка ссылок на документы через настройки docLink: обычные ссылки или карточки предпросмотра :::doc-link. Метаданные получает встроенный загрузчик или пользовательский обработчик; междоменные запросы подчиняются правилам CORS браузера.
  • Отображение видео: синтаксис изображения с URL, оканчивающимся на .mp4, .webm, .ogg или другое известное расширение, создаёт элемент <video controls>.
  • Отдельный рендерер (renderMarkdown(source, options)), создающий HTML с теми же плагинами и стилями, что и предпросмотр, без монтирования редактора.
  • Инкрементальный рендеринг по блокам: исходный текст разделяется по заголовкам ATX, и заново обрабатываются только изменённые блоки. Остальные повторно используют существующие DOM-узлы, включая уже инициализированные SVG интеллект-карт. Результаты кешируются по хешу содержимого.
  • Адаптивная задержка: время ожидания перед обновлением предпросмотра зависит от длины документа — от 120 до 600 мс.
  • Два режима редактирования: simple (редактор и предпросмотр без панели инструментов) и complex (панель инструментов и строка состояния), переключаемые во время работы.
  • Две темы: light и dark, применяемые через атрибут data-theme и пользовательские свойства CSS.

Обзор архитектуры​

Библиотека предоставляет два интерфейса:

  1. Класс обычного JavaScript — основной API строится вокруг MarkdownEditor, создаваемого с элементом-контейнером. Он объединяет CodeEditor (обёртку CodeMirror), Renderer (обёртку markdown-it), IncrementalRenderer для предпросмотра и, в режиме complex, Toolbar и StatusBar. Диалоги, контроллер @упоминаний и контроллер ссылок на документы — подключаемые по мере необходимости модули.

  2. Экспорт React по подпути — MarkdownEditorReact является компонентом forwardRef, экспортируемым из ./react. Он оборачивает экземпляр MarkdownEditor, поддерживает управляемое и неуправляемое использование value и предоставляет императивный MarkdownEditorHandle через ref. Отдельная точка входа React позволяет проектам без React не устанавливать react и react-dom.

Рендеринг состоит из синхронного прохода markdown-it, создающего HTML-заглушки для интеллект-карт, и асинхронной инициализации через Renderer.hydrate, превращающей их в интерактивные SVG-диаграммы. renderMarkdown возвращает синхронный HTML; для получения SVG используйте Renderer.render, вставьте HTML в DOM, затем вызовите Renderer.hydrate. Инкрементальный рендерер работает непосредственно с контейнером предпросмотра.

Поддержка браузеров​

Библиотека рассчитана на современные браузеры с DOM. CodeMirror 6, KaTeX и markmap-view — зависимости пакета, а не функции браузера; интерактивные интеллект-карты используют ResizeObserver. При наличии используется Clipboard API. Если navigator.clipboard недоступен, например вне HTTPS, для копирования блоков кода применяется document.execCommand('copy'). Модуль интеллект-карт устанавливает пустую реализацию ResizeObserver только при отсутствии глобального объекта, предотвращая соответствующую ошибку импорта; настоящих уведомлений об изменении размера она не предоставляет.

Лицензия​

@powerduck/md-editor распространяется по лицензии MIT.

Дальнейшие шаги​