Учебник Remark / Rehype

Введение
- Что такое Remark и Rehype
- История создания unified экосистемы
- Философия синтаксических деревьев
- Когда использовать Remark/Rehype
- Альтернативные решения и их сравнение
Основы работы с Markdown и AST
- Структура Markdown документа
- Синтаксические деревья: понятие и назначение
- MDAST: спецификация дерева Markdown
- HAST: спецификация HTML дерева
- Унифицированный процессор: архитектура
- VFile: работа с виртуальными файлами
Установка и настройка окружения
- Установка через npm и yarn
- Минимальная конфигурация проекта
- Настройка TypeScript для работы с unified
- Интеграция с различными сборщиками
- Работа в Node.js окружении
- Использование в браузере
Remark: базовая работа
- Парсинг Markdown в MDAST
- Сериализация MDAST обратно в Markdown
- Простейший pipeline обработки
- Метаданные и frontmatter
- Работа с процессором unified
- Асинхронная и синхронная обработка
Структура MDAST
- Корневые узлы и их свойства
- Типы контентных узлов
- Блочные элементы
- Строчные элементы
- Позиционная информация
- Навигация по дереву
Плагины Remark: создание и использование
- Архитектура плагинов unified
- Написание первого плагина
- Обход дерева с unist-util-visit
- Модификация узлов
- Добавление новых узлов
- Удаление узлов из дерева
- Работа с дочерними элементами
- Контекст выполнения плагина
Популярные плагины Remark
- remark-gfm: поддержка GitHub Flavored Markdown
- remark-breaks: обработка переносов строк
- remark-frontmatter: извлечение метаданных
- remark-math: математические формулы
- remark-toc: генерация оглавления
- remark-emoji: работа с эмодзи
- remark-unwrap-images: манипуляции с изображениями
Трансформация Markdown в HTML
- Переход от Remark к Rehype
- Плагин remark-rehype: принципы работы
- Настройка опций трансформации
- Обработка неизвестных элементов
- Сохранение позиционной информации
Rehype: основы работы с HTML
- Парсинг HTML в HAST
- Сериализация HAST в HTML строку
- Pipeline для HTML обработки
- Различия в обработке HTML и Markdown
Структура HAST
- Типы узлов HAST
- Элементы и их атрибуты
- Текстовые узлы
- Комментарии и doctype
- Свойства и их нормализация
- Работа с пространствами имен
Плагины Rehype: разработка
- Специфика плагинов для HTML
- Обход HAST дерева
- Манипуляции с элементами
- Изменение атрибутов
- Работа с классами и стилями
- Внедрение скриптов и стилей
Популярные плагины Rehype
- rehype-sanitize: санитизация HTML
- rehype-highlight: подсветка синтаксиса
- rehype-raw: обработка встроенного HTML
- rehype-stringify: настройка вывода
- rehype-slug: генерация идентификаторов заголовков
- rehype-autolink-headings: автоматические ссылки
- rehype-minify: минификация HTML
Unified: продвинутые концепции
- Цепочки обработки данных
- Фазы парсинга, трансформации и сериализации
- Композиция плагинов
- Переиспользование конфигураций
- Пресеты плагинов
- Middleware паттерн в unified
Работа с VFile
- Создание виртуальных файлов
- Метаданные файлов
- Сообщения и логирование
- История изменений
- Работа с путями
- Интеграция с файловой системой
Обработка ошибок и валидация
- Типы ошибок в unified
- Обработка исключений при парсинге
- Валидация синтаксических деревьев
- Сбор и отображение warning'ов
- Отладка плагинов
- Тестирование обработки ошибок
Утилиты для работы с деревьями
- unist-util-visit: обход узлов
- unist-util-map: трансформация через map
- unist-util-filter: фильтрация узлов
- unist-util-select: CSS-подобные селекторы
- unist-util-find: поиск узлов
- unist-builder: построение деревьев
- hast-util-to-html: продвинутая сериализация
GFM: расширения GitHub Flavored Markdown
- Таблицы: парсинг и рендеринг
- Автолинки URL и email
- Зачеркнутый текст
- Task lists: чекбоксы в списках
- Конфликты спецификаций
- Кастомизация GFM поведения
Математические формулы
- Inline и block формулы
- Интеграция с KaTeX
- Интеграция с MathJax
- Обработка ошибок в формулах
- Доступность математического контента
Подсветка синтаксиса кода
- Обработка code blocks
- Интеграция с highlight.js
- Интеграция с Prism
- Определение языков программирования
- Кастомные темы подсветки
- Метаданные блоков кода
Работа с изображениями
- Парсинг изображений из Markdown
- Трансформация путей
- Оптимизация изображений в pipeline
- Добавление атрибутов к изображениям
- Lazy loading и responsive images
- Работа с внешними изображениями
Генерация оглавления
- Извлечение заголовков
- Построение иерархической структуры
- Генерация якорных ссылок
- Настройка глубины оглавления
- Позиционирование ToC в документе
- Фильтрация заголовков
Frontmatter и метаданные
- Форматы frontmatter: YAML, TOML, JSON
- Парсинг метаданных
- Типизация frontmatter в TypeScript
- Использование метаданных в плагинах
- Валидация схемы метаданных
Санитизация и безопасность
- XSS атаки и их предотвращение
- Белые списки тегов и атрибутов
- Настройка политик санитизации
- Обработка пользовательского контента
- Content Security Policy
- Санитизация URL и протоколов
Оптимизация производительности
- Профилирование pipeline
- Кэширование результатов обработки
- Ленивая загрузка плагинов
- Параллельная обработка документов
- Оптимизация обхода деревьев
- Memory leaks и их предотвращение
TypeScript интеграция
- Типизация плагинов
- Типы для MDAST и HAST узлов
- Расширение типов узлов
- Generic типы в unified
- Типобезопасные утилиты
- Declaration merging для кастомных узлов
Интеграция с фреймворками
- Next.js: MDX и Markdown обработка
- Astro: content collections
- Gatsby: трансформеры и плагины
- Vite: плагины для Markdown
- Webpack loaders для unified
- Rollup плагины
MDX: Markdown с JSX
- Основы MDX синтаксиса
- Парсинг MDX в дерево
- Компоненты в MDX
- Провайдеры компонентов
- Импорты и экспорты в MDX
- Ограничения и особенности MDX
Создание документации
- Автогенерация API документации
- Версионирование документов
- Навигация и поиск
- Темная тема и кастомизация
- SEO оптимизация документации
Статические сайт-генераторы
- Сборка статических сайтов с unified
- Маршрутизация на основе файлов
- Шаблонизация с использованием HAST
- RSS и sitemap генерация
- Инкрементальная регенерация
- Деплой и хостинг
Кастомные синтаксические расширения
- Добавление новых типов узлов
- Кастомные токенизаторы
- Расширение Markdown синтаксиса
- Directive нотация
- Парсинг кастомных блоков
- Обратная совместимость
CLI инструменты
- Создание CLI на основе unified
- Обработка файлов из командной строки
- Watch режим для разработки
- Конфигурационные файлы
- Интеграция с git hooks
- CI/CD pipeline для документации
Миграция и совместимость
- Миграция с других Markdown процессоров
- Обновление версий unified
- Breaking changes и их обработка
- Совместимость со старыми плагинами
- Миграция кастомного кода
Отладка и инструментарий
- Визуализация синтаксических деревьев
- Инспектирование промежуточных состояний
- Логирование в плагинах
- Юнит-тестирование плагинов
- Интеграционное тестирование pipeline
- Snapshot тестирование результатов
Продвинутые паттерны разработки
- Композиция сложных трансформаций
- Плагины-фабрики с опциями
- Контекст между плагинами
- Условное применение плагинов
- Рекурсивная обработка вложенных структур
- Оптимистичные трансформации
Расширяемость и экосистема
- Публикация собственных плагинов
- Соглашения по именованию
- Документирование плагинов
- Версионирование и поддержка