Насоки за живеење - MDX и други рамки

Може да го имате најдобриот проект со отворен код, но ако нема добра документација, големи се шансите дека никогаш нема да полета. Во канцеларијата, добрата документација ќе ве спречи да одговорите на истите прашања. Документацијата, исто така, гарантира дека луѓето можат да го разберат проектот ако клучните вработени ја напуштат компанијата или ако се сменат улогите. Насоките за живеење ќе помогнат да се обезбеди интегритет на податоците.

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

Оваа статија е широк преглед на алатки за пишување документација и креирање упатства. Не сите алатки наведени овде користат MDX, но тој сè повеќе се вклучува во алатките за документација.

Што е MDX?

датотека .mdx ја има истата синтакса како Markdown, но ви овозможува да внесувате интерактивни JSX компоненти и да ги вметнете во вашата содржина. Поддршката за Vue компонентите е во алфа. За да започнете да работите со MDX, само инсталирајте „Create React App“. Постојат додатоци за Next.js и Гетсби. Следната верзија на Docusaurus (верзија 2) исто така ќе има мајчин поддршка.

Пишување документација со Docusaurus

напиша Докусаурус на Фејсбук. Тие го користат на секој проект со отворен код освен 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 користи Гетсби - статичен генератор на сајтови кој често се користи за блогови. Ако работите со Vue, тогаш VuePress е добра опција за вас. Друга опција е да користите генератор напишан во Python - MkDocs. Тој е со отворен код и е конфигуриран со користење на една датотека YAML. GitBook е исто така добра опција, но е бесплатен само за јавни и некомерцијални тимови. Можете исто така едноставно да прикачувате mardown датотеки користејќи Git и да работите со нив во Github.

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

Насоки, дизајн на системот, библиотеки на компоненти - како и да ги наречете, во последно време стана многу популарен. Доаѓањето на компонентите рамки како React и алатките споменати овде ги трансформираа од суета проекти во корисни алатки.

Storybook, Docz и Styleguidist сите го прават истото: прикажуваат интерактивни елементи и документираат нивните API. Проектот може да има десетици, па дури и стотици компоненти - сите со различни состојби и стилови. Ако сакате компонентите да се користат повторно, луѓето треба да знаат дека постојат. За да го направите ова, едноставно каталогирајте ги компонентите. Упатствата овозможуваат лесен преглед на сите ваши компоненти. Ова помага да се одржи визуелната конзистентност и да се избегне повторлива работа.

Овие алатки обезбедуваат пригоден начин за прегледување на различни состојби. Може да биде тешко да се репродуцира секоја состојба на компонента во контекст на вистинска апликација. Наместо да кликнете на вистинската апликација, вреди да се развие посебна компонента. Може да се симулираат тешко достапни состојби (како што се состојби на вчитување).

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

Доц

Во моментов Docz работи само со React, но во тек е активна работа за поддршка на Preact, Vue и веб компоненти. Docz е најновата од трите алатки, но успеа да собере над 14 ѕвезди на 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 е најлесен за разбирање и најлесен за работа.

Ако сте љубител на генератор на статички сајтови на Гетсби, 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 ѕвезди на Github. Тоа е проект со отворен код со 000 соработници и персонал со полно работно време. Го користат 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 ќе се применуваат постепено во текот на следните неколку месеци и се чини дека тоа ќе биде голем чекор напред.

Резултатите од

Придобивките од библиотеката со шаблони се пофалени во милиони статии на Медиум. Кога се работи добро, тие го олеснуваат создавањето на сродни производи и го одржуваат идентитетот. Се разбира, ниту една од овие алатки нема магично да создаде систем за дизајн. Ова бара внимателен дизајн и CSS. Но, кога ќе дојде време да се направи дизајн систем достапен за целата компанија, Docz, Storybook и Styleguidist се одлични опции.

Од преведувачот. Ова е мое прво искуство на Хабре. Доколку најдете неточности, или имате предлози за подобрување на статијата, пишете ми во лична порака.

Извор: www.habr.com