Linji gwida ħajjin - MDX u oqfsa oħra

Jista' jkollok l-aħjar proġett ta' sors miftuħ, imma jekk ma jkollux dokumentazzjoni tajba, ċansijiet li qatt ma jitlaq. Fl-uffiċċju, dokumentazzjoni tajba tipprevjenik milli twieġeb l-istess mistoqsijiet. Id-dokumentazzjoni tiżgura wkoll li n-nies jistgħu jifhmu l-proġett jekk impjegati ewlenin iħallu l-kumpanija jew ir-rwoli jinbidlu. Linji gwida tal-ħajja se jgħinu biex tiġi żgurata l-integrità tad-dejta.

Jekk għandek bżonn tikteb test twil, Markdown huwa alternattiva kbira għall-HTML. Xi drabi s-sintassi ta' Markdown mhix biżżejjed. F'dan il-każ nistgħu nużaw HTML ġewwa fih. Per eżempju, elementi tad-dwana. Għalhekk, jekk qed tibni sistema ta 'disinn b'komponenti tal-web indiġeni, jistgħu jiġu inklużi faċilment fid-dokumentazzjoni tat-test. Jekk qed tuża React (jew kwalunkwe qafas JSX ieħor bħal Preact jew Vue), tista 'tagħmel l-istess ħaġa billi tuża MDX.

Dan l-artikolu huwa ħarsa ġenerali wiesgħa ta 'għodod għall-kitba ta' dokumentazzjoni u l-ħolqien ta 'linji gwida. Mhux l-għodod kollha elenkati hawn jużaw MDX, iżda qed jiġi inkluż dejjem aktar fl-għodod tad-dokumentazzjoni.

X'inhu MDX?

fajl .mdx għandu l-istess sintassi bħal Markdown, iżda jippermettilek timporta komponenti interattivi JSX u tiddaħħalhom fil-kontenut tiegħek. L-appoġġ għall-komponenti Vue huwa f'alpha. Biex tibda taħdem ma 'MDX, installa biss "Oħloq React App". Hemm plugins għal Next.js u Gatsby. Il-verżjoni li jmiss ta 'Docusaurus (verżjoni 2) se jkollha wkoll appoġġ nattiv.

Kitba ta' dokumentazzjoni b'Docusaurus

Docusaurus kiteb fuq Facebook. Jużawha fuq kull proġett open source ħlief React. Barra l-kumpanija huwa użat minn Redux, Prettier, Gulp u Babel.

Proġetti li jużaw Docusaurus.

Docusaurus jista 'jintuża biex tikteb kwalunkwe dokumentazzjoni, mhux biss biex jiddeskrivu l-frontend. Għandu React taħt il-barnuża, imma m'għandekx għalfejn tkun familjari magħha biex tużah. Huwa jieħu l-fajls Markdown tiegħek, niskata ta 'maġija u dokumentazzjoni strutturata tajjeb, ifformattjata u li tinqara b'disinn sabiħ hija lesta.

Fuq il-websajt Redux tista 'tara l-mudell standard Docusaurus

Websajts mibnija b'Docusaurus jistgħu jinkludu wkoll blog ibbażat fuq Markdown. Prism.js huwa immedjatament konness għall-enfasi tas-sintassi. Minkejja l-fatt li Docusaurus deher relattivament reċentement, ġie rikonoxxut bħala l-aħjar għodda tal-2018 fuq StackShare.

Għażliet oħra ta' Ħolqien ta' Kontenut

Docusaurus huwa ddisinjat speċifikament għall-ħolqien ta 'dokumentazzjoni. Naturalment, hemm miljun u mod wieħed biex tagħmel websajt - tista 'skjera s-soluzzjoni tiegħek stess fi kwalunkwe lingwa, CMS, jew tuża ġeneratur ta' sit statiku.

Pereżempju, id-dokumentazzjoni għal React, is-sistema tad-disinn IBM, Apollo u Ghost CMS jużaw Gatsby - ġeneratur ta 'sit statiku li spiss jintuża għall-blogs. Jekk taħdem ma' Vue, allura VuePress hija għażla tajba għalik. Għażla oħra hija li tuża ġeneratur miktub f'Python - MkDocs. Huwa sors miftuħ u kkonfigurat bl-użu ta 'fajl YAML wieħed. GitBook huwa wkoll għażla tajba, iżda huwa b'xejn biss għal timijiet pubbliċi u mhux kummerċjali. Tista 'wkoll sempliċement ittella' fajls mardown billi tuża Git u taħdem magħhom f'Github.

Komponenti dokumentati: Docz, Storybook u Styleguidist

Linji gwida, disinn tas-sistema, libreriji tal-komponenti - tkun xi tkun issejjaħhom, dan l-aħħar sar popolari ħafna. Il-miġja ta 'oqfsa ta' komponenti bħal React u l-għodod imsemmija hawn ttrasformawhom minn proġetti vanity f'għodod utli.

Storybook, Docz u Styleguidist kollha jagħmlu l-istess ħaġa: juru elementi interattivi u jiddokumentaw l-API tagħhom. Proġett jista 'jkollu għexieren jew saħansitra mijiet ta' komponenti - kollha bi stati u stili differenti. Jekk trid li l-komponenti jerġgħu jintużaw, in-nies iridu jkunu jafu li jeżistu. Biex tagħmel dan, sempliċement katalogu l-komponenti. Linji gwida jipprovdu ħarsa ġenerali faċli biex issib il-komponenti kollha tiegħek. Dan jgħin biex tinżamm il-konsistenza viżwali u jiġi evitat xogħol ripetittiv.

Dawn l-għodod jipprovdu mod konvenjenti biex tara stati differenti. Jista' jkun diffiċli li tirriproduċi kull stat ta' komponent fil-kuntest ta' applikazzjoni reali. Minflok tikklikkja fuq l-applikazzjoni attwali, ta 'min tiżviluppa komponent separat. Stati diffiċli biex jintlaħqu (bħal stati tat-tagħbija) jistgħu jiġu simulati.

Flimkien ma 'dimostrazzjoni viżwali ta' diversi stati u lista ta 'proprjetajiet, ħafna drabi huwa meħtieġ li tikteb deskrizzjoni ġenerali tal-kontenut - raġunijiet ta' disinn, każijiet ta 'użu, jew deskrizzjonijiet tar-riżultati tal-ittestjar tal-utent. Markdown huwa faċli ħafna biex titgħallem - idealment, il-linji gwida għandhom ikunu riżors kondiviż għad-disinjaturi u l-iżviluppaturi. Docz, Styleguidist, u Storybook joffru mod kif faċilment tħallat Markdown mal-komponenti.

Dokz

Bħalissa Docz jaħdem biss ma' React, iżda għaddej xogħol attiv biex jappoġġja Preact, Vue u komponenti tal-web. Docz huwa l-aktar reċenti mit-tliet għodod, iżda rnexxielu jiġbor aktar minn 14 stilla fuq Github. Docz jintroduċi żewġ komponenti − <Playground> и < Props >. Huma importati u użati fil-fajls .mdx.

import { Playground, Props } from "docz";
import Button from "../src/Button";

## You can _write_ **markdown**
### You can import and use components

<Button>click</Button>

Tista 'wrap-komponenti React tiegħek stess bihom <Playground>biex toħloq analogu tal-CodePen jew CodeSandbox integrati - jiġifieri, tara l-komponent tiegħek u tista 'teditjah.

<Playground>
  <Button>click</Button>
</Playground>

<Props> se juri l-proprjetajiet kollha disponibbli għal komponent React partikolari, valuri awtomatiċi, u jekk il-proprjetà hijiex meħtieġa.

<Props of={Button} />

Personalment, insib li dan l-approċċ ibbażat fuq MDX huwa l-aktar faċli biex tifhem u l-aktar faċli biex taħdem miegħu.

Jekk int fan tal-ġeneratur tas-sit statiku Gatsby, Docz joffri integrazzjoni kbira.

Gwida tal-istil

Bħal Docz, eżempji jinkitbu bl-użu tas-sintassi Markdown. Styleguidist juża blokki tal-kodiċi Markdown (kwotazzjonijiet tripli) f'fajls regolari .md fajls, mhux MDX.

```js
<Button onClick={() => console.log('clicked')>Push Me</Button>

Il-blokki tal-kodiċi f'Markdown normalment juru biss il-kodiċi. Meta tuża Styleguidist, kwalunkwe blokk ta 'kodiċi b'tikketta tal-lingwa js, jsx jew javascript se tirrendi bħala komponent React. Bħal Docz, il-kodiċi huwa editjabbli - tista 'tbiddel il-proprjetajiet u istantanjament tara r-riżultat.

Styleguidist awtomatikament joħloq tabella tal-proprjetà minn dikjarazzjonijiet PropTypes, Flow jew Typescript.

Styleguidist bħalissa jappoġġja React u Vue.

Ktieb tal-Istejjer

Storybook jippożizzjona ruħu bħala "ambjent ta 'żvilupp tal-komponenti tal-UI." Minflok tikteb komponenti ta 'eżempju ġewwa fajls Markdown jew MDX, tikteb stejjer ġewwa fajls Javascript. Story jiddokumenta l-istat speċifiku ta’ komponent. Pereżempju, komponent jista' jkollu storja għal stat mgħobbi u stat diżabbli (persuni b'diżabilità).

storiesOf('Button', module)
  .add('disabled', () => (
    <Button disabled>lorem ipsum</Button>
  ))

Storybook huwa ħafna aktar kumpless minn Styleguidist u Docz. Iżda fl-istess ħin, din hija l-aktar għażla popolari; il-proġett għandu aktar minn 36 stilla fuq Github. Huwa proġett ta' sors miftuħ b'000 kontributur u persunal full-time. Jintuża minn Airbnb, Algolia, Atlassian, Lyft u Salesforce. Storybook jappoġġja aktar oqfsa minn kompetituri - React, React Native, Vue, Angular, Mithril, Ember, Riot, Svelte u HTML regolari.

F'rilaxx futur se jkun hemm karatteristiċi minn Docz u se jiġu introdotti MDX.

# Button

Some _notes_ about your button written with **markdown syntax**.

<Story name="disabled">
  <Button disabled>lorem ipsum</Button>
</Story>

Il-karatteristiċi ġodda ta' Storybook se joħorġu gradwalment matul il-ftit xhur li ġejjin u jidher li se jkun pass kbir 'il quddiem.

Riżultati ta '

Il-benefiċċji ta 'librerija tal-mudelli huma mfaħħra f'miljuni ta' artikli fuq Medium. Meta jsir tajjeb, jagħmluha aktar faċli biex jinħolqu prodotti relatati u tinżamm l-identità. Naturalment, l-ebda waħda minn dawn l-għodod ma toħloq b'mod maġiku sistema ta 'disinn. Dan jeħtieġ disinn bir-reqqa u CSS. Imma meta jasal iż-żmien li sistema tad-disinn tkun aċċessibbli għall-kumpanija kollha, Docz, Storybook u Styleguidist huma għażliet kbar.

Mit-traduttur. Din hija l-ewwel esperjenza tiegħi fuq Habré. Jekk issib xi ineżattezzi, jew għandek suġġerimenti biex ittejjeb l-artiklu, iktebli f'messaġġ personali.

Sors: www.habr.com