Напишите интерактивные демонстрации с использованием Markdown и JavaScript

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

В сети у нас есть много-много разных способов написания документации. Однако почти всех их объединяет то, что они полагаются на 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 вы можете использовать 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 перехватывает замечание и извлекает все помеченные блоки js. В конце концов, HTML и JavaScript доступны отдельно.

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

Процесс выглядит так:

  1. Извлеките js script и отделите его от Markdown.
  2. Рендеринг Markdown.
  3. Предоставьте 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.

У вас получится примерно так:

Под капотом это добавляет дополнительный шаг к обработке:

  1. Извлеките js script и отделите от Markdown.
  2. Извлеките js story и js preview-story и отделите от Markdown.
  3. Поместите заполнитель <mdjs-story mdjs-story-name="demo"></mdjs-story> или mdjs-preview на его место.
  4. Рендеринг Markdown.
  5. Предоставьте HTML, JavaScript и истории.

Это вся информация, которая нам нужна для создания полных JavaScrip и демонстрационных страниц исключительно из 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 по умолчанию

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

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

Все это происходит для вас под капотом.

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

Вы можете использовать его локально через es-dev-server

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

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

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

Вы можете увидеть пример настройки в репо demo-wc-card.

Вы можете использовать его через Storybook

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

  • Установить зависимость npm i -D @open-wc/demoing-storybook.
  • Добавьте в свой package.json:
  • Настройте свой .storybook/main.js для загрузки файлов Markdown:
  • Добавьте к каждому файлу Markdown, который должен быть в Storybook, имя с помощью:

И вот так, все готово. Никаких дополнительных изменений каких-либо файлов не требуется; плагин позаботится обо всем, преобразовав ваши файлы Markdown для поддержки формата MDX Storybook.

Для получения более подробной информации см. Https://open-wc.org/demoing-storybook/.

Покажи это на GitHub

Поскольку GitHub поддерживает Markdown из коробки, мы можем пойти еще дальше, используя mdjs.

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

  • Хотите посмотреть демонстрацию, не открывая другую страницу?
    mdjs-viewer!
  • Хотите показать на живом примере возникшую проблему?
    mdjs-viewer!

Почти похоже на черную магию, да? Все, что вы сделали, это установили расширение Chrome, и внезапно GitHub получил суперспособности.

Все, что вам нужно, это иметь несколько файлов Markdown с правильными блоками ограничения кода, и ваш код должен работать на unpkg.com.

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

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

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

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

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

Это определенно звучит как адский инструмент для улучшения вашей документации и воспроизведения выпусков, не так ли? Тем более, что ридми и контент по-прежнему остаются полезными даже без расширения.

Для получения более подробной информации см. Https://github.com/open-wc/mdjs-viewer.

Поддерживается на webcomponents.dev

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

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

Вы можете начать непосредственно с документации, как на скриншоте выше. Более того, вы можете использовать его в каждом файле Markdown или README.md.

Попробуйте и задокументируйте свои компоненты во всей их красе.

Все демонстрационные ссылки взяты с сайта webcomponents.dev. Обязательно зацените.

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

Пожалуйста, проверьте страницу официальной документации по адресу https://open-wc.org/mdjs/.

Резюме

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

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

Будущее

  • Имейте отдельный репозиторий GitHub (возможно, тоже групповой)
  • Иметь специальную домашнюю страницу
  • Рамка предварительного просмотра истории по умолчанию должна выглядеть немного лучше
  • Поддержка нескольких рендеров - обсуждение в вопросе
  • Выделение фрагментов кода
  • Дополнительные помощники для использования в историях
  • … (Не стесняйтесь открывать вопросы в рамках соответствующих проектов)

Благодарности

Спасибо Pascal за отзывы и помощь в превращении моих каракулей в интересную историю.

Хотите писать на Medium в Markdown? Попробуйте Маркдиум!