Готовим новые доки 📄
#frontend #storybook #react

С момента выхода этой заметки появилась новая мажорная версия Storybook 6.0, а вместе с ней плагин Notes, который мы использовали для документирования UI, безвозвратно устарел и перестал поддерживаться 👨‍🦳

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

К сожалению, интерфейсы расширений не совместимы друг с другом, а значит, просто заменить Notes на Docs не выйдет. Поскольку оба аддона могут сосуществовать в рамках одного Storybook, можно постепенно переходить на новое расширение, переписывая документацию частями.

После подключения расширения в каждой истории появляется вкладка Docs, которая содержит соответствующую документацию по тому или иному компоненту.
По умолчанию за генерацию документации отвечает DocsPage-компонент. Документация строится на основе метаинформации о текущем сторис.

Для расширения возможностей документирования можно заменить стандартный DocsPage-компонент на кастомный, построенный на нужных нам Dock Blocks. Список доступных блоков c описанием можно найти здесь.

Аддон Docs позволяет использовать MDX-разметку, благодаря чему можно описывать компоненты с помощью Markdown-разметки и JSX для рендеринга их состояния по аналогии с нативным API Storybook. MDX-формат также можно использовать для написания только Markdown-разметки без вывода компонента. В таком случае Canvas будет повторять вкладку Docs. Подробнее о данной фиче можно узнать здесь.

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