Ou ka gen pi bon pwojè sous louvri, men si li pa gen bon dokiman, gen chans pou li pa janm dekole. Nan biwo a, bon dokiman ap anpeche w reponn menm kesyon yo. Dokimantasyon tou asire ke moun ka konprann pwojè a si anplwaye kle yo kite konpayi an oswa wòl chanje. Gid lavi yo pral ede asire entegrite done yo.
Si ou bezwen ekri tèks long, Markdown se yon bon altènatif HTML. Pafwa Markdown sentaks pa ase. Nan ka sa a nou ka itilize HTML andedan li. Pou egzanp, eleman koutim. Se poutèt sa, si w ap bati yon sistèm konsepsyon ak eleman entènèt natif natal, yo ka fasilman enkli nan dokiman tèks. Si w ap itilize React (oswa nenpòt lòt fondasyon JSX tankou Preact oswa Vue), ou ka fè menm bagay la ak MDX.
Atik sa a se yon apèsi laj sou zouti pou ekri dokiman ak kreye direktiv. Se pa tout zouti ki nan lis isit la itilize MDX, men li de pli zan pli enkli nan zouti dokimantasyon yo.
ki sa ki MDX?
dosye .mdx gen menm sentaks ak Markdown, men li pèmèt ou enpòte konpozan JSX entèaktif epi entegre yo nan kontni ou. Sipò pou eleman Vue se nan alfa. Pou kòmanse travay ak MDX, jis enstale "Create React App". Gen grefon pou Next.js ak Gatsby. Pwochen vèsyon Docusaurus (vèsyon 2) ap gen sipò natif natal tou.
Ekri dokiman ak Docusaurus
Docusaurus te ekri sou Facebook. Yo itilize li sou chak pwojè sous louvri eksepte React. Deyò konpayi an li itilize pa Redux, Prettier, Gulp ak Babel.
Pwojè ki sèvi ak Docusaurus.
Docusaurus ka itilize pou ekri nenpòt ki dokimantasyon, pa sèlman pou dekri frontend a. Li gen React anba kapo a, men ou pa bezwen abitye ak li pou itilize li. Li pran dosye Markdown ou yo, yon zongle majik ak dokiman ki byen estriktire, fòma ak lizib ak yon bèl konsepsyon pare.
Sou sit entènèt Redux la ou ka wè modèl Docusaurus estanda a
Sit entènèt ki te konstwi ak Docusaurus kapab genyen tou yon blog Markdown ki baze sou. Prism.js imedyatman konekte pou sentaks en. Malgre lefèt ke Docusaurus parèt relativman dènyèman, li te rekonèt kòm pi bon zouti nan 2018 sou StackShare.
Lòt Opsyon Kreyasyon kontni
Docusaurus fèt espesyalman pou kreye dokiman. Natirèlman, gen yon milyon ak yon sèl fason yo fè yon sit entènèt - ou ka deplwaye solisyon pwòp ou a nan nenpòt lang, CMS, oswa itilize yon dèlko sit estatik.
Pou egzanp, dokiman pou React, IBM konsepsyon sistèm, Apollo ak Ghost CMS itilize Gatsby - yon dèlko sit estatik ki souvan itilize pou blogs. Si w ap travay ak Vue, Lè sa a, VuePress se yon bon opsyon pou ou. Yon lòt opsyon se sèvi ak yon dèlko ekri nan Python - MkDocs. Li se sous louvri ak configuré lè l sèvi avèk yon sèl dosye YAML. GitBook se tou yon bon opsyon, men li la sèlman gratis pou ekip piblik ak ki pa komèsyal yo. Ou kapab tou senpleman telechaje dosye mardown lè l sèvi avèk Git epi travay avèk yo nan Github.
Konpozan dokimante: Docz, Storybook ak Styleguidist
Gid, konsepsyon sistèm, bibliyotèk eleman - kèlkeswa sa ou rele yo, li te vin trè popilè dènyèman. Aparisyon nan kad eleman tankou React ak zouti yo mansyone isit la te transfòme yo soti nan pwojè vanite nan zouti itil.
Storybook, Docz ak Styleguidist tout fè menm bagay la: montre eleman entèaktif epi dokimante API yo. Yon pwojè ka gen plizyè douzèn oswa menm dè santèn de eleman - tout ak diferan eta ak estil. Si ou vle konpozan yo dwe reyitilize, moun bezwen konnen yo egziste. Pou fè sa, tou senpleman katalòg eleman yo. Gid bay yon apèsi fasil pou jwenn sou tout eleman ou yo. Sa a ede kenbe konsistans vizyèl epi evite travay repetitif.
Zouti sa yo bay yon fason pratik pou wè diferan eta yo. Li ka difisil pou repwodui chak eta yon eleman nan kontèks yon aplikasyon reyèl. Olye pou yo klike sou aplikasyon aktyèl la, li vo devlope yon eleman separe. Eta ki difisil pou atenn yo (tankou eta chaje yo) ka simulation.
Ansanm ak yon demonstrasyon vizyèl nan divès eta ak yon lis pwopriyete, li souvan nesesè yo ekri yon deskripsyon jeneral nan kontni an - rezon konsepsyon, ka itilize, oswa deskripsyon rezilta tès itilizatè yo. Markdown trè fasil pou aprann - depreferans, direktiv yo ta dwe yon resous pataje pou konsèpteur ak devlopè. Docz, Styleguidist, ak Storybook ofri yon fason fasil melanje Markdown ak eleman yo.
Docz
Kounye a Docz travay sèlman ak React, men travay aktif ap fèt pou sipòte konpozan Preact, Vue ak entènèt. Docz se pi resan nan twa zouti yo, men li te jere yo kolekte plis pase 14 zetwal sou Github. Docz prezante de eleman - <Playground> и < Props >. Yo enpòte ak itilize nan dosye .mdx.
import { Playground, Props } from "docz";
import Button from "../src/Button";
## You can _write_ **markdown**
### You can import and use components
<Button>click</Button>Ou ka vlope pwòp eleman React ou a <Playground>pou kreye yon analogue nan CodePen oswa CodeSandbox entegre - se sa ki, ou wè eleman ou a epi ou ka modifye li.
<Playground>
<Button>click</Button>
</Playground><Props> pral montre tout pwopriyete ki disponib pou yon eleman React bay, valè default, epi si pwopriyete a obligatwa.
<Props of={Button} />Pèsonèlman, mwen jwenn apwòch sa a ki baze sou MDX yo pi fasil pou konprann ak pi fasil pou travay avèk yo.
Si ou se yon fanatik dèlko sit estatik Gatsby, Docz ofri yon gwo entegrasyon.
Gid estil
Menm jan ak Docz, egzanp yo ekri lè l sèvi avèk sentaks Markdown. Styleguidist itilize blòk kòd Markdown (trip quotes) nan dosye regilye .md dosye, pa MDX.
```js
<Button onClick={() => console.log('clicked')>Push Me</Button>Blòk kòd nan Markdown anjeneral jis montre kòd. Lè w ap itilize Styleguidist, nenpòt blòk kòd ki gen yon tag lang js, jsx oswa javascript pral rann kòm yon eleman React. Menm jan ak Docz, kòd la ka modifye - ou ka chanje pwopriyete epi imedyatman wè rezilta a.
Styleguidist pral otomatikman kreye yon tab pwopriyete apati deklarasyon PropTypes, Flow oswa Typescript.
Styleguidist kounye a sipòte React ak Vue.
Liv Istwa
Storybook pozisyone tèt li kòm yon "anviwònman devlopman konpozan UI." Olye pou w ekri eleman egzanp andedan dosye Markdown oswa MDX, ou ekri istwa andedan dosye Javascript yo. Istwa dokimante eta espesifik yon eleman. Pou egzanp, yon eleman ka gen istwa pou yon eta chaje ak yon eta andikape (andikape).
storiesOf('Button', module)
.add('disabled', () => (
<Button disabled>lorem ipsum</Button>
))Storybook se pi plis konplèks pase Styleguidist ak Docz. Men, an menm tan an, sa a se opsyon ki pi popilè; pwojè a gen plis pase 36 zetwal sou Github. Li se yon pwojè sous louvri ak 000 kontribitè ak anplwaye aplentan. Li se itilize pa Airbnb, Algolia, Atlassian, Lyft ak Salesforce. Storybook sipòte plis kad pase konpetitè - React, React Native, Vue, Angilè, Mithril, Ember, Riot, Svelte ak HTML regilye.
Nan yon lage nan lavni pral gen karakteristik ki soti nan Docz ak MDX pral prezante.
# Button
Some _notes_ about your button written with **markdown syntax**.
<Story name="disabled">
<Button disabled>lorem ipsum</Button>
</Story>Nouvo karakteristik Storybook yo pral parèt piti piti pandan kèk mwa kap vini yo e li sanble ke li pral yon gwo etap pi devan.
Rezilta
Benefis ki genyen nan yon bibliyotèk modèl yo fè lwanj nan dè milyon de atik sou Medium. Lè yo fè byen, yo fè li pi fasil yo kreye pwodwi ki gen rapò ak kenbe idantite. Natirèlman, pa youn nan zouti sa yo pral maji kreye yon sistèm konsepsyon. Sa a mande pou konsepsyon atansyon ak CSS. Men, lè li rive tan fè yon sistèm konsepsyon aksesib a tout konpayi an, Docz, Storybook ak Styleguidist se gwo opsyon.
Soti nan tradiktè a. Sa a se premye eksperyans mwen sou Habré. Si w jwenn nenpòt inexactitudes, oswa si w gen sijesyon pou amelyore atik la, ekri m 'nan yon mesaj pèsonèl.
Sous: www.habr.com