Живи упътвания — 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 автоматично ще генерира таблица със свойства от PropTypes, Flow или TypeScript декларации.

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

Storybook

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

storiesOf('Button', module)
  .add('disabled', () => (
    lorem ipsum
  ))

Storybook е значително по-сложен от Styleguidist и Docz. Но въпреки това, това е най-популярният вариант; в GitHub проектът има над 36 000 звезди. Това е проект с отворен код, в който участват 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