Web-разработка

Дуэт Markdown и JavaScript (mdjs) - залог отличной документации

06.05.2020

Каждому совместно используемому коду следует прописывать документацию, чтобы отразить его идею и назначение. Пользователи должны отчетливо понимать, что они используют, для чего и как.

В сети очень много разных способов написания документации. Однако есть один объединяющий их фактор — все они используют Markdown или его вариации.

И неудивительно, так как Markdown поддерживается практически везде (VS Code, Atom, GitHub, GitLab, Dev.to, npm и т. д.).

Использование Markdown с различными инструментами

С инструментами, не работающими в браузере

В этом случае вы чаще всего будете делиться фрагментами кода, необходимыми разработчикам для запуска своих проектов. И в подобной ситуации на помощь приходят традиционные генераторы статических сайтов Docusaurus, VuePress, Gatsby и т. д. Все они имеют полноценную поддержку Markdown и позволяют легко создавать привлекательные страницы документации с фрагментами кода, выделением информации на экране и прочим.

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

С (визуальными) компонентами, работающими в браузере

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

Vue

Например, для работы с Vue можно воспользоваться VuePress, который автоматически вносит все компоненты Vue в определенный каталог. А затем, как обычно, использовать HTML тэги, так как Markdown поддерживает HTML.

.
└─ .vuepress
  └─ components
      ├─ demo-1.vue

поддерживает компоненты Vue и содержит для них “магический” импорт;
не поддерживает обобщенный JavaScript и передачу свойств компонентам.

React

Для React есть MDX, который расширяет Markdown с поддержкой JSX. MDX можно использовать через разные инструменты, такие как Gatsby, Docz, Storybook и т. д.

поддерживает импорт / экспорт JavaScript;
передает всё через JSX;
средний рейтинг на GitHub;
требует специальных инструментов в редакторах для выделения информации на экране.

Ограничения

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

Знакомьтесь — Markdown с JavaScript (mdjs)

Главными целями являются:

минимизировать сложность;
следовать прогрессивным тенденциям в развитии;
придерживаться действующего синтаксиса Markdown;
выделять код в редакторах без помощи дополнительных инструментов;
повысить рейтинг на GitHub/GitLab и на любом другом инструменте управления исходным кодом.

Фундаментальная идея кажется слишком простой, чтобы быть правдой. Всё, что нужно сделать — расширить размеченный блок кода дополнительными метаданными js script.

```js script
import './my-component.js';
```
# This is my component
<my-component></my-component>

Вот и всё!

Что ж, от разговоров — к делу! Вы можете увидеть всё это в действии здесь.

Как работает mdjs

mdjs подключается к Remark и извлекает все блоки с тэгами js. В итоге HTML и JavaScript можно использовать по отдельности.

{
  html: '<h1>This is my component</h1><my-component></my-component>',
  jsCode: "import './my-component.js';"
}

Затем их можно объединить/обработать любым инструментом для создания фактической страницы документации.

Данный процесс выгляди так:

Извлечь js script и отделить от Markdown.
Отобразить Markdown.
Предоставить HTML и JavaScript.

Это уже позволяет нам напрямую включать JavaScript и отображать веб компоненты с атрибутами.

Расширение mdjs демо форматом

Теперь, когда мы можем выполнять JavaScript внутри Markdown, пред нами открываются горизонты больших возможностей.

Первый шаг — создание еще одного расширенного блока кода JavaScript, а именно js story. Из этого блока кода можно экспортировать функцию для выполнения по требованию:

```js script
import './my-component.js';
```
# This is my component
```js preview-story
export const demo = () => `<my-component header="from attribute"></my-component>`
```

Если есть желание добавить границы или кнопку для демонстрации или сокрытия действующего исходного кода, можете использовать js preview-story.

То, что у вас получилось, выглядит примерно так:

{
  html: '<h1>This is my component</h1><my-component></my-component>',
  jsCode: "import './my-component.js';",
  stories: [
    key: 'demo',
    name: 'demo',
    code: 'export const demo = () => `<my-component header="from attribute"></my-component>`',
  ]
}

Внутри процесса к обработке добавляется дополнительный шаг:

Извлечь js script и отделить от Markdown.
Извлечь js story и js preview-story и отделить от Markdown.
Поместить плейсхолдер <mdjs-story mdjs-story-name="demo"></mdjs-story> или mdjs-preview на его место.
Отобразить Markdown.
Предоставить HTML, JavaScript и пользовательские истории.

Это вся информация, необходимая для создания страниц с поддержкой JavaScript и демо исключительно возможностями Markdown.

По умолчанию mdjs идет дальше и поддерживает систему шаблонов lit-html.

```js script
import './demo-wc-card.js';
import { html } from 'lit-html';
```
# This is my component
```js story
export const demo = () => html`
  <demo-wc-card header="HEADER"></demo-wc-card>
`;
```

Вот еще одна площадка, имитирующая полную страницу документации.

Страница документации mdjs по умолчанию

Как только все метаданные у нас в распоряжении, можно отобразить конкретную страницу документации.

Этот процесс сводится к генерации кода, который присваивает демо функцию фактическому веб-компоненту:

const stories = [{ key: 'demo', story: demo, code: demo }];
for (const story of stories) {
  const storyEl = rootNode.querySelector(`[mdjs-story-name="${story.key}"]`);
  storyEl.story = story.story;
  storyEl.code = story.code;
}

Для вас же все это происходит, так сказать, за кадром.

Где можно использовать mdjs?

Использование mdjs локально через es-dev-server

В этом разделе вы узнаете, как создать область просмотра Markdown на подобии GitHub для всех локальных файлов Markdown, включая интерактивное демо.

Установите es-dev-server как зависимость, выполнив npm i -D es-dev-server .
Добавьте следующий скрипт в package.json:

"scripts": {
  "start": "es-dev-server",
}

Создайте es-dev-server.config.js в корне вашего репозитория.

const { mdjsTransformer } = require('@mdjs/core');

module.exports = {
  nodeResolve: true,
  open: 'README.md',
  watch: true,
  responseTransformers: [mdjsTransformer],
};

После выполнения npm run star у вас появляется возможность просматривать документацию через http://localhost:8000/README.md.

На demo-wc-card repo можно ознакомиться с примером установки.

Использование mdjs через Storybook

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

Установите зависимость npm i -D @open-wc/demoing-storybook.
Добавьте в package.json:

"scripts": {
  "storybook": "start-storybook",
}

Настройте .storybook/main.js для загрузки файлов Markdown:

module.exports = {
  stories: ['../README.md', '../docs/**/*.md'],
  esDevServer: {
    nodeResolve: true,
    watch: true,
    open: true,
  },
};

Ко всем файлам Markdown, которые должны быть в Storybook, добавьте имя через:

export default {
  title: 'My Group/My Awesome Component',
};

Вот так просто, и процесс запущен. Какие-либо дополнительные изменения файлов не требуются. Плагин позаботится обо всем, сконвертировав файлы Markdown для поддержки формата MDX Storybook.

Для более подробной информации пройдите по ссылке.

Размещение mdjs на GitHub

Учитывая, что GitHub по умолчанию поддерживает Markdown, при помощи mdjs мы можем добиться и большего.

Так как напрямую GitHub не поддерживает mdjs, вам понадобится расширение Chrome mdjs-viewer.

Хотите просматривать демо без открытия другой страницы? Ответ — mdjs-viewer!
Хотите показать актуальный пример проблемы, над которой работаете? Ответ очевиден — mdjs-viewer!

Без темной магии здесь явно не обошлось?! А мы всего лишь установили расширение Chrome, и тут же GitHub получил супер возможности.

Необходимое условие — наличие файлов Markdown c правильными размеченными блоками кода и размещение/функционирование кода на unpkg.com.

Как на самом деле работает расширение?

Оно определяет, на какой странице GitHub вы находитесь. Если оно обнаруживает файл Markdown или запрос с кодом mdjs, то добавляет кнопку “Показать демо” для его активации. При нажатии на кнопку расширение начнет собирать всю необходимую информацию:

Найдёт ближайший package.json.
Прочтёт содержимое актуального файла Markdown.
Заменит весь пустой импорт импортами с unpkg.com.
Заменит все относительные импорты на полученные с unpkg.com и имя package.json, добавив к нему относительный путь.
Создаст защищенный iframe.
Установит абсолютную позицию iframe наложением.
Вложит код JavaScript и HTML в iframe.
Кнопка станет переключателем с двумя состояниями: показать / скрыть iframe.

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

С учетом этого вы можете размещать документацию с актуальными примерами на GitHub. Возможны даже задачи с демо, показывающие реальные ошибки в коде.

Похоже, что для улучшения документации и воспроизведения запроса, потребуется куча инструментов, особенно с учетом того, что readme и содержимое запроса все еще остаются полезными и без расширения.

Для более подробной информации пройдите по ссылке.

Поддержка mdjs на webcomponents.dev

Полностью поддерживается этим прекрасным онлайн редактором.

Вы можете редактировать документацию, демо и код непосредственно в браузере.

Можете начать прямо с документации, как показано на скриншоте сверху, но еще лучше — использовать его в каждом файле Markdown или README.md.

Запустите mdjs в работу и документируйте компоненты во всем их великолепии.

Все ссылки с webcomponents.dev. Посмотрите полезный материал здесь.

Как добавить поддержку mdjs

Ознакомьтесь с официальной страницей документации на https://open-wc.org/mdjs/.

Выводы

Теперь у вас есть mdjs — формат, который можно использовать множеством разных способов. Это ваш единственный источник истины в поисках привлекательного оформления документации. Будь то локальный проект, проект в Storybook, GitHub или npm — везде и всегда mdjs смотрится привлекательно, даже при отсутствии прямой поддержки. Но при возможности поддержки он станет интерактивным с демо благодаря улучшениям.

А прямо сейчас надо сесть и написать хорошую документацию для своих компонентов!

В перспективе

Отдельный GitHub репозиторий (в потенциале также групповой).
Создание специальной домашней страницы.
Улучшение внешнего вида встроенного блока предпросмотра историй.
Поддержка нескольких отрисовщиков.
Выделение фрагментов кода.
Увеличение помощников внутри истории.
… Создание запросов с предложениями внутри соответствующих проектов.