Создайте плагин Markdoc менее чем за 15 строк кода

Пару недель назад мы выложили в открытый доступ Markdoc, авторский инструмент, используемый в документации Stripe. В дополнение к этому мы опубликовали в блоге статью о том, как начать использовать Markdoc с Next.js, используя плагин @markdoc/next.js.
В этой статье я покажу вам, как создать свой собственный плагин, используя в качестве примера тот, который я написал для Parcel, чтобы вы могли использовать Markdoc вместе с ним.

Прежде чем мы начнем, Parcel — это инструмент сборки с нулевой конфигурацией, который включает в себя сервер разработки, горячую перезагрузку, автоматическую оптимизацию производства и многое другое из коробки. Однако по умолчанию он не разбирает файлы Markdown, поэтому, чтобы иметь возможность использовать Markdoc с Parcel, вам нужен специальный плагин. Поскольку Markdoc является расширением Markdown, стандартного плагина Markdown будет недостаточно для правильного разбора файлов.

Если вы хотите перейти непосредственно к полному плагину, не стесняйтесь заглянуть в репозиторий.

Создание плагина

В зависимости от фреймворка или инструмента, для которого вы хотите создать плагин, они могут работать с системой плагинов немного по-разному, но код, содержащийся в плагине, должен быть относительно схожим. По сути, все, что нужно сделать, это вызвать методы Markdoc.parse() и Markdoc.transform().

В Parcel плагин, преобразующий активы, называется Transformer.

Вот как выглядит этот трансформер:

import { Transformer } from "@parcel/plugin";
import Markdoc from "@markdoc/markdoc";

export default new Transformer({
 async transform({ asset }) {
   const code = await asset.getCode();

   const ast = Markdoc.parse(code);
   const content = Markdoc.transform(ast);

   asset.type = "js";
   asset.setCode(`export default ${JSON.stringify(content)}`);

   return [asset];
 },
});
Вход в полноэкранный режим Выход из полноэкранного режима

Для начала вам нужно импортировать Transformer из Parcel и Markdoc из @markdoc/markdoc.

Затем, способ доступа к содержимому файлов в трансформере Parcel заключается в вызове asset.getCode(). Затем необходимо вызвать методы .parse() и .transform() из Markdoc для обработки необработанного содержимого Markdown.

Наконец, вам нужно вернуть преобразованное содержимое. Markdoc.transform() возвращает объект JSON, поэтому нам нужно указать, что тип содержимого теперь JavaScript, изменив свойство .type на ‘js’. Затем нужно вызвать метод setCode, чтобы заменить содержимое на вновь созданное и добавить его после export default. Эта последняя часть специфична для Parcel, однако вызов parse и transform необходим для создания плагина для любого другого инструмента.

Использование плагина

Чтобы использовать этот плагин, вам нужно начать с вставки следующих строк в файл .parcelrc в вашем приложении:

{
 "extends": "@parcel/config-default",
 "transformers": {
   "*.md": [
     "parcel-transformer-markdoc"
   ]
 }
}
Войти в полноэкранный режим Выйти из полноэкранного режима

Этот код расширяет стандартную конфигурацию Parcel для обработки файлов, заканчивающихся на *.md и применения пользовательского трансформатора к содержимому этих файлов.

Тогда, если представить себе приложение React с файлом Markdown под названием getting-started.md, код, необходимый для отображения этого содержимого, будет выглядеть примерно так:

import content from "./getting-started.md";
import Markdoc from "@markdoc/markdoc";
import React from "react";

export function App() {
 const html = Markdoc.renderers.react(content, React);
 return (
   <main>
     {html}
   </main>
 );
}
Войти в полноэкранный режим Выйти из полноэкранного режима

Вот и все! Теперь файлы Markdown будут правильно анализироваться, и вы сможете использовать все возможности Markdoc.

Другие плагины

Другие члены сообщества разработчиков также начали создавать свои собственные плагины. Не стесняйтесь, ознакомьтесь с ними:

  • Svelte-markdoc
  • Esbuild-markdoc-plugin
  • Solidjs-markdoc
  • Vue-markdoc

Если вы создадите свой собственный плагин, дайте нам знать!

📣 Следите за @StripeDev и нашей командой в Twitter
📺 Подпишитесь на наш канал Youtube
💬 Присоединяйтесь к официальному серверу Discord
📧 Подпишитесь на Dev Digest

Об авторе

Чарли Джерард — представитель разработчиков в Stripe, креативный технолог и эксперт Google Developer Expert. Она любит исследовать и экспериментировать с технологиями. Когда она не кодит, ей нравится проводить время на свежем воздухе, пробовать новые сорта пива и читать.

Оцените статью
Procodings.ru
Добавить комментарий