Живи ръководства — MDX и други фреймворци

Можете да имате страхотен проект с открит код, но ако му липсва добра документация, съществува вероятност той никога да не успее. В офиса добрата документация ще ви позволи да не отговаряте на едни и същи въпроси постоянно. Документацията също така гарантира, че хората могат да се справят с проекта, ако ключови служители напуснат компанията или се сменят роли. Живите указания ще помогнат за осигуряване на целостта на данните.

Ако трябва да напишете дълъг текст, Markdown е отлична алтернатива на HTML. Понякога синтаксисът на Markdown не е достатъчен. В такъв случай можем да използваме HTML в него. Например, за потребителски елементи. Затова, ако изграждате дизайн система с нативни уеб компоненти, лесно можете да ги включите в текстовата документация. Ако използвате React (или друга JSX рамка, например Preact или Vue), можете да направите същото с помощта на MDX.

Тази статия е широк обзор на инструментите за писане на документация и създаване на указания. Не всички инструменти, изброени тук, използват MDX, но той все по-често се включва в инструментите за документация.

Какво е MDX?

файл .mdx има същия синтаксис като Markdown, но позволява импорт на интерактивни JSX компоненти и вграждането им в съдържанието ви. Поддръжката на Vue компоненти е в алфа. За да започнете работа с MDX, достатъчно е да инсталирате 'Create React App'. Има плъгини за Next.js и Gatsby. Следващата версия на Docusaurus (версия 2) също ще има вградена поддръжка.

Писане на документация с Docusaurus

Docusaurus е разработен от Facebook. Те го използват за всеки проект с открит код, освен React. Извън компанията, той се използва от Redux, Prettier, Gulp и Babel.

Проекти, които използват Docusaurus.

Docusaurus може да се използва за писане на всеки документация, не само за описание на фронтенда. Той под капака има React, но за да го използвате, не е необходимо да сте запознати с него. Той взима вашите Markdown файлове, щипка магия и добре структурираната, форматирана и четима документация с красив дизайн е готова.

На сайта на Redux можете да видите стандартен шаблон на Docusaurus.

Сайтовете, създадени с Docusaurus, могат да включват и блог, базиран на Markdown. За синтактична подсветка е интегриран Prism.js. Въпреки че Docusaurus е сравнително нов, той беше признат за най-добрия инструмент на 2018 година в StackShare.

Други възможности за създаване на съдържание

Docusaurus е специално проектиран за създаване на документация. Разбира се, има милион и един начин да създадете сайт — можете да развиете собствено решение на всеки език, CMS или да използвате генератор на статичен сайт.

Например, документацията за React, дизайна на IBM, Apollo и Ghost CMS използват Gatsby — генератор на статични сайтове, който често се използва за блогове. Ако работите с Vue, VuePress ще бъде добро решение за вас. Друг вариант е да използвате генератора, написан на Python — MkDocs. Той е с отворен код и се конфигурира с един YAML файл. GitBook също е неплох вариант, но е безплатен само за отворени и некомерсиални екипи. Освен това, можете просто да качвате markdown файлове, използвайки git, и да работите с тях в Github.

Документиране на компоненти: Docz, Storybook и Styleguidist

Насоки, дизайн системи, библиотеки от компоненти — независимо как ги наричате, те бяха много популярни напоследък. Появата на компонентни фреймворкове, като React, и инструментите, споменати тук, позволиха да превърнем тези проекти от тщеславие в полезни инструменти.

Storybook, Docz и Styleguidist правят едно и също: показват интерактивни елементи и документират техния API. Проектът може да има десетки или дори стотици компоненти — всички с различни състояния и стилове. Ако искате компонентите да се използват повторно, хората трябва да знаят, че съществуват. За това е достатъчно да каталогизирате компонентите. Насоките предоставят удобен за търсене преглед на всичките ви компоненти. Това помага за поддържане на визуална последователност и избягване на повторна работа.

Тези инструменти предоставят удобен начин за преглед на различни състояния. Може да е трудно да се възпроизведе всяко състояние на компонента в контекста на реално приложение. Вместо да кликате в реално приложение, е по-добре да разработите отделен компонент. Можете да моделирате трудно достъпни състояния (например, състояние на зареждане).

Със визуализация на различни състояния и списък на свойства, често е необходимо да се напише общо описание на съдържанието — обосновка на дизайна, примери за използване или описание на резултатите от потребителското тестване. Markdown е много лесен за изучаване — в идеалния случай насоките трябва да бъдат съвместен ресурс за дизайнери и разработчици. Docz, Styleguidist и Storybook предлагат начин за лесно комбиниране на Markdown с компоненти.

Docz

В момента Docz работи само с React, но активно се работи по поддръжка на Preact, Vue и уеб компоненти. Docz е най-новият от трите инструмента, но в Github успя да събере над 14 000 звезди. Docz представя два компонента — <Playground> и < Props >. Те се импортират и използват в файлове .mdx.

import { Playground, Props } from "docz";
import Button from "..\/src\/Button";

## Можете да _пишете_ **markdown**
### Можете да импортирате и използвате компоненти

кликнете

Можете да обгърнете собствените си React компоненти с <Playground>, за да създадете аналог на вграден CodePen или CodeSandbox — т.е. виждате компонтента си и можете да го редактирате.

кликнете

<Props> ще покаже всички налични свойства за този React компонент, стойностите по подразбиране и дали свойството е задължително.

<Props of={Button} />

Лично смятам, че този подход, базиран на MDX, е най-лесен за разбиране и най-лесен за работа.

Ако сте фен на генератора на статични сайтове Gatsby, Docz предлага отлична интеграция.

Styleguidist

Както и в Docz, примерите се пишат, използвайки синтакса на Markdown. Styleguidist използва блокове с код на Markdown (тройни кавички) в обикновени .md файлове, а не в MDX.

```js
 console.log('clicked')}>Натиснете мен

Блоковете с код в Markdown обикновено просто показват кода. При използване на Styleguidist, всеки блок с код, маркиран с езиковия таг js, jsx или javascript ще бъде показан като React компонент. Както в Docz, кодът е редактиращ — можете да променяте свойствата и веднага да виждате резултата.

Styleguidist автоматично ще създаде таблица със свойства от проп типове, Flow или Typescript декларации.

Styleguidist в момента поддържа React и Vue.

Storybook

Storybook се позиционира като „среда за разработка на UI компоненти“. Вместо да пишете примери за компоненти в файлове Markdown или MDX, вие пишете история във файлове Javascript. История документират конкретно състояние на компонента. Например, един компонент може да има истории за състояние на зареждане и изключено състояние (деактивиран).

storiesOf('Button', module)
  .add('деактивиран', () => (
    lorem ipsum
  ))

Storybook е значително по-сложен от Styleguidist и Docz. Въпреки това, той е най-популярният вариант, с над 36 000 звезди в GitHub. Това е проект с отворен код, в който участват 657 участници и се поддържа от служители. Използва се от Airbnb, Algolia, Atlassian, Lyft и Salesforce. Storybook поддържа повече фреймворкове от конкуренцията — React, React Native, Vue, Angular, Mithril, Ember, Riot, Svelte и обикновен HTML.

В бъдещото издание ще бъдат добавени функции от Docz и внедряване на MDX.

# Button

Some _notes_ about your button written with **markdown syntax**.

<Story name="disabled">
  <Button disabled>lorem ipsum</Button>
</Story>

Новите функции на Storybook ще бъдат пуснати постепенно през следващите няколко месеца и изглежда, че това ще бъде значителен напредък.

Итог

Предимствата на библиотеките с шаблони са възхвалявани в милиони статии в Medium. Когато всичко е направено добре, те улесняват създаването на свързани продукти и поддържането на идентичността. Разбира се, нито един от тези инструменти не може да създаде магически дизайн система. Това изисква внимателно проектиране на дизайна и CSS. Но когато дойде време да се направи дизайн системата достъпна за цялата компания, Docz, Storybook и Styleguidist са отлични варианти.

От преводача. Това е моят първи опит в Хабра. Ако сте забелязали неточности или имате предложения за подобрение на статията — пишете ми на лично съобщение.

Източник: habr.com