Vite: плагины для Markdown

Vite предоставляет гибкую систему плагинов для обработки Markdown-файлов, что позволяет интегрировать контент прямо в сборку приложения. Основные инструменты для этого — библиотеки Remark и Rehype, которые работают на основе абстрактного синтаксического дерева (AST) и дают возможность трансформировать Markdown и HTML на лету.

Подключение плагинов Remark и Rehype

Для работы с Markdown в Vite обычно используют плагин vite-plugin-md, который позволяет импортировать .md файлы как Vue-компоненты (или просто как строки) и подключать кастомные плагины Remark и Rehype. Пример базовой конфигурации:

import { defineConfig } from 'vite';
import vue from '@vitejs/plugin-vue';
import Markdown from 'vite-plugin-md';
import remarkGfm from 'remark-gfm';
import rehypeSlug from 'rehype-slug';

export default defineConfig({
  plugins: [
    vue({
      include: [/\.vue$/, /\.md$/],
    }),
    Markdown({
      remarkPlugins: [remarkGfm],
      rehypePlugins: [rehypeSlug],
    }),
  ],
});

Ключевые моменты:

  • remarkPlugins — массив плагинов для обработки Markdown на уровне AST, например, добавление поддержки таблиц (remark-gfm) или автоматической нумерации заголовков.
  • rehypePlugins — плагины для обработки HTML после трансформации Markdown, например, rehype-slug добавляет уникальные id к заголовкам.

Особенности работы с AST

Remark и Rehype используют дерево узлов для представления Markdown и HTML. Каждый узел имеет тип (type) и может содержать детей (children). Это позволяет:

  • Вставлять пользовательские элементы;
  • Модифицировать содержимое;
  • Реализовывать кастомные рендереры.

Пример плагина Remark для добавления специального класса к заголовкам:

import { visit } from 'unist-util-visit';

export default function remarkAddHeaderClass() {
  return (tree) => {
    visit(tree, 'heading', (node) => {
      node.data = node.data || {};
      node.data.hProperties = node.data.hProperties || {};
      node.data.hProperties.className = 'custom-header';
    });
  };
}

Работа с Rehype: трансформация HTML

Rehype позволяет модифицировать итоговый HTML. Например, можно автоматически оборачивать все <pre> блоки с кодом в контейнер с дополнительными атрибутами:

import { visit } from 'unist-util-visit';

export default function rehypeWrapPre() {
  return (tree) => {
    visit(tree, 'element', (node) => {
      if (node.tagName === 'pre') {
        node.tagName = 'div';
        node.properties = node.properties || {};
        node.properties.className = 'code-block';
        node.children = [{
          type: 'element',
          tagName: 'pre',
          properties: {},
          children: node.children,
        }];
      }
    });
  };
}

Настройка подсветки синтаксиса

Для подсветки кода часто используют rehype-prism-plus или rehype-highlight. В Vite это выглядит так:

import rehypePrism from 'rehype-prism-plus';

Markdown({
  remarkPlugins: [remarkGfm],
  rehypePlugins: [rehypeSlug, rehypePrism],
});

rehype-prism-plus автоматически находит блоки кода с указанием языка (```js) и добавляет необходимые CSS-классы для подсветки.

Встроенные возможности Vite и Vue

При использовании vite-plugin-md Markdown-файлы можно импортировать как Vue-компоненты. Пример:

import MarkdownContent from './guide.md';

export default {
  components: { MarkdownContent },
  template: '<MarkdownContent />',
};

Это позволяет:

  • Встраивать Vue-компоненты внутри Markdown через синтаксис <ComponentName />;
  • Использовать реактивные данные и слоты внутри документации;
  • Комбинировать статический контент и динамические компоненты.

Советы по оптимизации

  • Разделение плагинов: использовать Remark для структуры и Rehype для визуальных модификаций.
  • Кэширование AST: Vite автоматически кеширует Markdown, но при больших проектах стоит оптимизировать плагины для минимизации обходов дерева.
  • Минимизация размера сборки: отключать лишние плагины в продакшн-сборке, оставляя только необходимые преобразования.

Расширение функционала

Сочетание Remark и Rehype позволяет реализовать:

  • Автоматическую генерацию оглавлений;
  • Ссылки с якорями для заголовков;
  • Встраивание интерактивных виджетов;
  • Конвертацию Markdown в презентации или PDF через промежуточный HTML.

Каждое расширение строится на манипуляциях AST и использовании возможностей плагин-системы, что делает Vite мощной платформой для управления контентом на Markdown.

Оглавление