Сизде ачык булактуу долбоор болушу мүмкүн, бирок анын жакшы документтери жок болсо, анда ал эч качан ишке ашпай калышы мүмкүн. Кеңседе жакшы документтер бир эле суроолорго кайра-кайра жооп берүүдөн сактайт. Документтер ошондой эле, эгерде негизги кызматкерлер компаниядан кетсе же ролдор өзгөрсө, адамдар долбоордун маанисин түшүнө алышына кепилдик берет. Түз нускамалар берилиштердин бүтүндүгүн камсыз кылууга жардам берет.
Эгер сизге узун текст жазуу керек болсо, Markdown HTMLге эң сонун альтернатива болуп саналат. Кээде Markdown синтаксиси жетишсиз. Бул учурда биз анын ичинде HTML колдоно алабыз. Мисалы, ыңгайлаштырылган элементтер. Ошондуктан, эгер сиз жергиликтүү веб компоненттери менен дизайн системасын куруп жатсаңыз, аларды тексттик документтерге киргизүү оңой. Эгер сиз React (же Preact же Vue сыяктуу башка JSX алкактарын) колдонуп жатсаңыз, MDX менен да ушундай кыла аласыз.
Бул макалада документтерди жазуу жана көрсөтмөлөрдү түзүү үчүн куралдардын кеңири баяндамасы. Бул жерде саналган бардык куралдар MDX колдонбойт, бирок ал документация куралдарына барган сайын көбүрөөк кошулууда.
MDX деген эмне?
билэ .mdx Markdown сыяктуу синтаксиске ээ, бирок интерактивдүү JSX компоненттерин импорттоого жана аларды мазмунуңузга кыстарууга мүмкүнчүлүк берет. Vue компоненттерин колдоо альфада. MDX менен иштөө үчүн жөн гана "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 салыштырмалуу жакында эле пайда болгонуна карабастан, ал StackShare сайтында 2018-жылдын эң мыкты куралы катары таанылган.
Башка Мазмун түзүү параметрлери
Docusaurus атайын документтерди түзүү үчүн иштелип чыккан. Албетте, веб-сайтты жасоонун бир миллион жолу бар - сиз өзүңүздүн чечимиңизди каалаган тилде, CMSде орното аласыз же статикалык сайт генераторун колдоно аласыз.
Мисалы, React документтери, IBM дизайн системасы, Apollo жана Ghost CMS блогдор үчүн көбүнчө колдонулган статикалык сайт генератору Гэтсбиди колдонушат. Эгерде сиз Vue менен иштеп жатсаңыз, анда VuePress сиз үчүн жакшы вариант. Дагы бир вариант - Python - MkDocs тилинде жазылган генераторду колдонуу. Ал ачык жана бир YAML файлы менен конфигурацияланган. GitBook да жакшы вариант, бирок ал ачык жана коммерциялык эмес командалар үчүн гана акысыз. Ошондой эле git аркылуу mardown файлдарын жүктөй аласыз жана алар менен Githubда иштей аласыз.
Компоненттик документация: Docz, Storybook жана Styleguidist
Көрсөтмөлөр, системанын дизайны, компоненттер китепканалары, аларды эмне деп атагыңыз келсе, булар акыркы убакта абдан популярдуу болуп калды. React жана бул жерде айтылган инструменттер сыяктуу компоненттик алкактардын пайда болушу аларды куру долбоорлордон пайдалуу куралдарга айландырууга мүмкүндүк берди.
Storybook, Docz жана Styleguidist бир эле нерсени аткарышат: интерактивдүү элементтерди көрсөтүү жана алардын API документтештирүү. Долбоор ондогон, ал тургай жүздөгөн компоненттерди камтышы мүмкүн, алардын бардыгы ар кандай абалда жана стилде. Эгер сиз компоненттердин кайра колдонулушун кааласаңыз, адамдар алардын бар экенин билиши керек. Бул үчүн, компоненттерди каталогдоштуруу жетиштүү. Көрсөтмөлөр сиздин бардык компоненттериңизди издөөгө оңой карап чыгууну камсыз кылат. Бул визуалдык ырааттуулукту сактоого жана кайталануучу иштердин алдын алууга жардам берет.
Бул куралдар ар кандай мамлекеттерди көрүү үчүн ыңгайлуу жол менен камсыз кылат. Чыныгы колдонмонун контекстинде компоненттин ар бир абалын кайталоо кыйын болушу мүмкүн. Чыныгы тиркемени басуунун ордуна, өзүнчө компонентти иштеп чыгуу керек. Жетүү кыйын абалдарды (мисалы, жүктөө абалын) моделдөө мүмкүн.
Ар кандай абалдардын визуалдык демонстрациясы жана касиеттердин тизмеси менен бирге көбүнчө мазмундун жалпы сыпаттамасын жазуу керек - дизайн негиздери, колдонуу учурлары же колдонуучу тестирлөөнүн натыйжаларынын сыпаттамасы. Markdown үйрөнүү абдан оңой - идеалдуу түрдө көрсөтмөлөр дизайнерлер жана иштеп чыгуучулар үчүн жалпы булак болушу керек. Docz, Styleguidist жана Storybook Markdownду компоненттер менен оңой аралаштыруунун жолун сунуштайт.
Докз
Учурда Docz React менен гана иштейт, бирок Preact, Vue жана веб компоненттерин колдоо боюнча жигердүү иштеп жатат. Docz үч куралдын эң акыркысы, бирок Githubда 14 000ден ашык жылдыздарды чогулта алган. 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 караганда алда канча татаал. Бирок, ошол эле учурда, бул эң популярдуу вариант, 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 - эң сонун варианттар.
Котормочудан. Бул менин Хабредеги биринчи тажрыйбам. Эгерде сиз кандайдыр бир так эместиктерди тапсаңыз, же макаланы жакшыртуу боюнча сунуштарыңыз болсо - жекече жазыңыз.
Source: www.habr.com