Шумо метавонед беҳтарин лоиҳаи кушодаасос дошта бошед, аммо агар он ҳуҷҷатҳои хуб надошта бошад, эҳтимол дорад, ки он ҳеҷ гоҳ аз кор набарояд. Дар офис ҳуҷҷатгузории хуб шуморо аз ҷавоб додан ба як саволҳо бозмедорад. Ҳуҷҷатҳо инчунин кафолат медиҳанд, ки одамон лоиҳаро дарк кунанд, агар кормандони асосӣ аз ширкат хориҷ шаванд ё нақшҳо иваз шаванд. Роҳнамои зиндагӣ ба таъмини якпорчагии маълумот кӯмак хоҳад кард.
Агар ба шумо лозим ояд, ки матни дароз нависед, 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 дар Фейсбук навишт. Онҳо онро дар ҳама лоиҳаҳои кушодаасос ба истиснои 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 низ як варианти хуб аст, аммо он танҳо барои дастаҳои ҷамъиятӣ ва ғайритиҷоратӣ ройгон аст. Шумо инчунин метавонед бо истифода аз Git файлҳои mardown бор кунед ва бо онҳо дар Github кор кунед.
Ҷузъҳои ҳуҷҷатгузорӣ: Docz, Storybook ва Styleguidist
Дастурҳо, тарҳрезии система, китобхонаҳои ҷузъӣ - ҳар чизе ки шумо онҳоро меномед, вақтҳои охир хеле маъмул шудааст. Пайдоиши чаҳорчӯбаҳои ҷузъӣ ба монанди React ва абзорҳои дар ин ҷо зикршуда онҳоро аз лоиҳаҳои ботил ба абзорҳои муфид табдил доданд.
Ҳикояҳо, Docz ва Styleguidist ҳама як корро мекунанд: унсурҳои интерактивиро намоиш диҳед ва API-и онҳоро ҳуҷҷатгузорӣ кунед. Лоиҳа метавонад даҳҳо ва ҳатто садҳо ҷузъҳо дошта бошад - ҳама бо ҳолат ва услубҳои гуногун. Агар шумо хоҳед, ки ҷузъҳо дубора истифода шаванд, одамон бояд донанд, ки онҳо вуҷуд доранд. Барои ин танҳо ҷузъҳоро каталог кунед. Дастурҳо шарҳи ба осонӣ пайдо кардани ҳамаи ҷузъҳои шуморо таъмин мекунанд. Ин ба нигоҳ доштани мутобиқати визуалӣ ва пешгирӣ кардани кори такрорӣ кӯмак мекунад.
Ин асбобҳо роҳи қулайро барои дидани ҳолатҳои гуногун таъмин мекунанд. Таҷдиди ҳар як ҳолати ҷузъ дар заминаи барномаи воқеӣ душвор буда метавонад. Ба ҷои клик кардани замимаи воқеӣ, он бамаврид аст, ки як ҷузъи алоҳида таҳия карда шавад. Ҳолатҳои дастнорас (масалан, ҳолати боркунӣ) метавонанд тақлид карда шаванд.
Дар баробари намоиши визуалии ҳолатҳои гуногун ва рӯйхати хосиятҳо, аксар вақт бояд тавсифи умумии мундариҷаро нависед - асосҳои тарҳрезӣ, ҳолатҳои истифода ё тавсифи натиҷаҳои санҷиши корбар. Markdown омӯхтан хеле осон аст - идеалӣ, роҳнамо бояд як манбаи муштарак барои тарроҳон ва таҳиягарон бошад. Docz, Styleguidist ва Storybook роҳи ба осонӣ омехта кардани Markdown бо ҷузъҳоро пешниҳод мекунанд.
Доч
Дар айни замон 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 -ро дастгирӣ мекунад.
Китоби ҳикояҳо
Ҳикояҳо худро ҳамчун "муҳити рушди ҷузъи UI" ҷойгир мекунад. Ба ҷои навиштани ҷузъҳои мисол дар дохили файлҳои Markdown ё MDX, шумо менависед таърих дар дохили файлҳои Javascript. ҳикояи ҳолати мушаххаси ҷузъро ҳуҷҷатгузорӣ кунед. Масалан, ҷузъ метавонад таърихи ҳолати пурборшуда ва ҳолати ғайрифаъол дошта бошад (маъюбон).
storiesOf('Button', module)
.add('disabled', () => (
<Button disabled>lorem ipsum</Button>
))Китоби ҳикоя нисбат ба Styleguidist ва Docz хеле мураккабтар аст. Аммо дар айни замон, ин варианти маъмултарин аст; лоиҳа дар Github зиёда аз 36 000 ситора дорад. Ин як лоиҳаи кушодаасос бо 657 саҳмгузор ва кормандони пурравақт мебошад. Он аз ҷониби Airbnb, Algolia, Atlassian, Lyft ва Salesforce истифода мешавад. Ҳикояҳо нисбат ба рақибон чаҳорчӯбаҳои бештарро дастгирӣ мекунанд - 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 имконоти олӣ мебошанд.
Аз тарчумон. Ин аввалин таҷрибаи ман дар Ҳабре аст. Агар шумо ягон иштибоҳ пайдо кунед ё барои беҳтар кардани мақола пешниҳоде дошта бошед, ба ман дар паёми шахсӣ нависед.
Манбаъ: will.com