Живи насоки - 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 design system, Apollo и Ghost CMS използва Gatsby – генератор на статичен сайт, който често се използва за блогове. Ако работите с Vue, тогава VuePress е добър вариант за вас. Друг вариант е да използвате генератор, написан на Python - MkDocs. Той е с отворен код и е конфигуриран с помощта на един YAML файл. GitBook също е добър вариант, но е безплатен само за публични и некомерсиални екипи. Можете също така просто да качвате mardown файлове с помощта на Git и да работите с тях в Github.

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

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

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

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

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

Docz

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

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

## You can _write_ **markdown**
### You can import and use components

<Button>click</Button>

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

<Playground>
  <Button>click</Button>
</Playground>

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

<Props of={Button} />

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

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

Ръководство за стил

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

```js
<Button onClick={() => console.log('clicked')>Push Me</Button>

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

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

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

Книга с разкази

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

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

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 са страхотни опции.

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

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