Ungase ube nephrojekthi yomthombo ovulekile engcono, kodwa uma ingenawo amadokhumenti amahle, kungenzeka ukuthi ayisoze yasuka. Ehhovisi, imibhalo emihle izokuvimbela ekuphenduleni imibuzo efanayo ngokuphindaphindiwe. Amadokhumenti aphinde aqinisekise ukuthi abantu bangenza umqondo wephrojekthi uma abasebenzi ababalulekile beshiya inkampani noma izindima zishintsha. Imihlahlandlela ebukhoma isiza ukuqinisekisa ubuqotho bedatha.
Uma udinga ukubhala umbhalo omude, i-Markdown iyindlela enhle ye-HTML. Kwesinye isikhathi i-syntax ye-Markdown ayanele. Kulokhu, singasebenzisa i-HTML ngaphakathi kwayo. Ngokwesibonelo, izakhi ngokwezifiso. Ngakho-ke, uma wakha isistimu yokuklama enezingxenye zewebhu zomdabu, kulula ukuzifaka emibhalweni yombhalo. Uma usebenzisa i-React (noma olunye uhlaka lwe-JSX njenge-Preact noma i-Vue), ungenza okufanayo nge-MDX.
Lesi sihloko sichaza kabanzi ngamathuluzi okubhala amadokhumenti nokudala umhlahlandlela. Akuwona wonke amathuluzi asohlwini lapha asebenzisa i-MDX, ββkodwa iya ngokuya ifakwa kumathuluzi emibhalo.
Yini i-MDX?
Π€Π°ΠΉΠ» .mdx ine-syntax efanayo ne-Markdown kodwa ikuvumela ukuthi ungenise izingxenye ze-JSX ezisebenzayo futhi uzishumeke kokuqukethwe kwakho. Ukusekela kwezingxenye ze-Vue kuku-alpha. Ukuze uqale ukusebenza nge-MDX, ββvele ufake "Dala uhlelo lokusebenza lwe-React". Kunama-plugin e-Next.js ne-Gatsby. Inguqulo elandelayo ye-Docusaurus (inguqulo 2) nayo izoba nosekelo olwakhelwe ngaphakathi.
Ukubhala amadokhumenti nge-Docusaurus
UDocusaurus ubhale kuFacebook. Bayisebenzisa kuwo wonke amaphrojekthi omthombo ovulekile ngaphandle kwe-React. Ngaphandle kwenkampani, i-Redux, Prettier, Gulp, ne-Babel bayayisebenzisa.
Amaphrojekthi asebenzisa i-Docusaurus.
I-Docusaurus ingasetshenziswa ukubhala noma yikuphi imibhalo, hhayi nje ukuchaza i-frontend. Ine-React ngaphansi kwe-hood, kodwa akudingeki ukuthi uyijwayele ukuze uyisebenzise. Kudingeka amafayela akho e-Markdown, ingcosana yomlingo kanye nemibhalo eyakhiwe kahle, efomethwe futhi efundekayo enomklamo omuhle isilungile.
Ungabona ithempulethi ye-Docusaurus ezenzakalelayo kuwebhusayithi ye-Redux.
Amasayithi akhiwe nge-Docusaurus angaphinda afake ibhulogi esekelwe ku-Markdown. Ngokugqanyiswa kwe-syntax, i-Prism.js ifakwa ngokushesha. Ngaphandle kweqiniso lokuthi i-Docusaurus ivele muva nje, ibonwe njengethuluzi elingcono kakhulu lango-2018 ku-StackShare.
Ezinye Izinketho Zokudala Okuqukethwe
I-Docusaurus yakhelwe ngokuqondile ukudala amadokhumenti. Yebo, kunesigidi kanye nezindlela eyodwa zokwenza iwebhusayithi - ungasebenzisa isixazululo sakho nganoma yiluphi ulimi, i-CMS, noma usebenzise ijeneretha yesayithi emile.
Isibonelo, imibhalo ye-React, isistimu yokuklama ye-IBM, i-Apollo, ne-Ghost CMS isebenzisa i-Gatsby, ijeneretha yesayithi emile evame ukusetshenziswa kumabhulogi. Uma usebenza ne-Vue i-VuePress iyindlela enhle kuwe. Enye inketho ukusebenzisa ijeneretha ebhalwe kuPython - MkDocs. Ivuliwe futhi yahlelwa ngefayela elilodwa le-YAML. I-GitBook nayo iyinketho enhle, kodwa imahhala kuphela emaqenjini avulekile nangewona awentengiso. Ungakwazi futhi ukulayisha amafayela e-mardown usebenzisa i-git futhi usebenze nawo ku-Github.
Umbhalo Wengxenye: I-Docz, Incwadi Yezindaba kanye ne-Styleguidist
Iziqondiso, ukwakheka kwesistimu, imitapo yolwazi yezingxenye, noma yini ofuna ukuyibiza, lezi sezidume kakhulu kamuva nje. Ukuvela kwezinhlaka zezingxenye ezifana ne-React kanye namathuluzi ashiwo lapha kwenze kwaba nokwenzeka ukuwaguqula asuke kumaphrojekthi ayize abe amathuluzi awusizo.
I-Storybook, i-Docz kanye ne-Styleguidist benza into efanayo: babonisa izici ezisebenzisanayo futhi babhale phansi i-API yabo. Iphrojekthi ingaba nezingxenye noma amakhulu ezingxenye, zonke ezinezifunda nezitayela ezahlukene. Uma ufuna izingxenye ziphinde zisetshenziswe, abantu kumele bazi ukuthi zikhona. Ukuze wenze lokhu, kwanele ukubala izingxenye. Izinkombandlela zinikeza ukubuka konke okulula ukuseshwa kwazo zonke izingxenye zakho. Lokhu kusiza ukugcina ukufana okubonakalayo futhi kugweme umsebenzi ophindaphindayo.
Lawa mathuluzi anikeza indlela elula yokubuka izifundazwe ezahlukahlukene. Kungaba nzima ukuphindaphinda zonke izimo zengxenye kumongo wohlelo lokusebenza lwangempela. Esikhundleni sokuchofoza kuhlelo lokusebenza lwangempela, kufanelekile ukuthuthukisa ingxenye ehlukile. Kungenzeka ukwenza imodeli yezifunda okunzima ukuzifinyelela (isibonelo, isimo sokulayisha).
Kanye nokuboniswa okubonakalayo kwezifunda ezihlukahlukene kanye nohlu lwezakhiwo, ngokuvamile kuyadingeka ukubhala incazelo evamile yokuqukethwe - izilinganiso zokuklama, izimo zokusebenzisa, noma incazelo yemiphumela yokuhlolwa komsebenzisi. I-Markdown ifundeka kalula - ngokufanelekile, imihlahlandlela kufanele ibe insiza eyabiwe yabaklami nabathuthukisi. I-Docz, i-Styleguidist, ne-Storybook inikeza indlela yokuhlanganisa kalula i-Markdown nezingxenye.
Docz
Okwamanje, i-Docz isebenza kuphela ne-React, kodwa isebenza ngenkuthalo ekusekeleni i-Preact, Vue, nezingxenye zewebhu. I-Docz ingeyakamuva kakhulu kula mathuluzi amathathu, kodwa ikwazile ukuqoqa izinkanyezi ezingaphezu kuka-14 ku-Github. U-Docz wethula izingxenye ezimbili β <Playground> ΠΈ < Props >. Angeniswa futhi asetshenziswe kumafayela .mdx.
import { Playground, Props } from "docz";
import Button from "../src/Button";
## You can _write_ **markdown**
### You can import and use components
<Button>click</Button>Ungakwazi ukugoqa izingxenye zakho ze-React nge <Playground>ukwakha i-analogue ye-CodePen eyakhelwe ngaphakathi noma i-CodeSandbox - okungukuthi, ubona ingxenye yakho futhi ungayihlela.
<Playground>
<Button>click</Button>
</Playground><Props> izobonisa zonke izakhiwo ezitholakalayo zengxenye enikeziwe ye-React, amanani azenzakalelayo kanye nokuthi isakhiwo siyadingeka yini.
<Props of={Button} />Ngokwami, ngithola le ndlela esekwe ku-MDX kulula ukuyiqonda futhi kulula kakhulu ukusebenza nayo.
Uma ungumuntu othanda ijeneretha yesayithi ye-Gatsby, i-Docz inikeza ukuhlanganiswa okuhle.
umqondisi wesitayela
Njengaku-Docz, izibonelo zibhalwa kusetshenziswa i-Markdown syntax. I-Styleguidist isebenzisa amabhlogo wekhodi ye-Markdown (izingcaphuno ezintathu) kumafayela avamile .md amafayela, hhayi ku-MDX.
```js
<Button onClick={() => console.log('clicked')>Push Me</Button>Amabhulokhi ekhodi ku-Markdown ngokuvamile abonisa ikhodi. Uma usebenzisa i-Styleguidist, noma iyiphi ibhulokhi yekhodi enomaka wolimi js, jsx noma javascript izonikezela njengengxenye ye-React. Njengo-Docz, ikhodi iyahleleka - ungashintsha izakhiwo futhi ubone umphumela ngaso leso sikhathi.
I-Styleguidist izodala ngokuzenzakalela ishidi lempahla kusuka kuzimemezelo ze-PropTypes, Flow noma Typescript.
I-Styleguidist manje isekela i-React ne-Vue.
Incwadi Yezindaba
Izikweletu ze-storybook ngokwayo "njengendawo yokuthuthukisa ingxenye ye-UI". Esikhundleni sokubhala izibonelo zezingxenye ngaphakathi kwamafayela e-Markdown noma e-MDX, ββuyabhala izindaba ngaphakathi kwamafayela e-Javascript. ΠΡΡΠΎΡΠΈΡ bhala isimo esithile sengxenye. Isibonelo, ingxenye ingaba nomlando wesimo sokulayisha kanye nesimo esikhubazekile (ukhutshaziwe).
storiesOf('Button', module)
.add('disabled', () => (
<Button disabled>lorem ipsum</Button>
))Incwadi yezindaba iyinkimbinkimbi kakhulu kune-Styleguidist kanye ne-Docz. Kodwa ngesikhathi esifanayo, lena inketho ethandwa kakhulu, ku-Github iphrojekthi inezinkanyezi ezingaphezu kuka-36. Lena iphrojekthi yomthombo ovulekile enabanikeli abangama-000 kanye nokuphelezelwa kwabasebenzi. Isetshenziswa yi-Airbnb, i-Algolia, i-Atlassian, iLyft ne-Salesforce. I-Storybook isekela izinhlaka eziningi kunomncintiswano - React, React Native, Vue, Angular, Mithril, Ember, Riot, Svelte, ne-plain HTML.
Ekukhishweni okuzayo, kuzoba nama-chips avela ku-Docz futhi i-MDX iyethula.
# Button
Some _notes_ about your button written with **markdown syntax**.
<Story name="disabled">
<Button disabled>lorem ipsum</Button>
</Story>Izici ezintsha ze-Storybook zizokwethulwa kancane kancane ezinyangeni ezimbalwa ezizayo, futhi kubukeka sengathi kuzoba yisinyathelo esikhulu esiya phambili.
Imiphumela
Izinzuzo zelabhulali yephethini zinconywa ngezigidi zama-athikili ku-Medium. Uma kwenziwa kahle, zenza kube lula ukwakha imikhiqizo ehlobene nokugcina ubuwena. Yiqiniso, alikho kulawa mathuluzi elizodala ngokumangalisayo uhlelo lokuklama. Lokhu kudinga ukuklama okucophelelayo kanye nomklamo we-CSS. Kodwa uma kufika isikhathi sokwenza uhlelo lokuklama lutholakale kuyo yonke inkampani, i-Docz, i-Storybook kanye ne-Stylegudist yizinketho ezinhle kakhulu.
Kusuka kumhumushi. Lesi isipiliyoni sami sokuqala ku-HabrΓ©. Uma uthola noma yikuphi ukungalungi, noma uneziphakamiso zokuthuthukisa isihloko - bhala kumuntu siqu.
Source: www.habr.com