Jo kinne it bêste iepen boarne-projekt hawwe, mar as it gjin goede dokumintaasje hat, is de kâns grut dat it noait sil begjinne. Op it kantoar sil goede dokumintaasje foarkomme dat jo deselde fragen beantwurdzje. Dokumintaasje soarget der ek foar dat minsken it projekt kinne begripe as wichtige meiwurkers it bedriuw ferlitte of rollen feroarje. Rjochtlinen foar libjen sille helpe om gegevensintegriteit te garandearjen.
As jo lange tekst moatte skriuwe, is Markdown in geweldich alternatyf foar HTML. Soms is Markdown-syntaksis net genôch. Yn dit gefal kinne wy HTML deryn brûke. Bygelyks, oanpaste eleminten. Dêrom, as jo in ûntwerpsysteem bouwe mei native webkomponinten, kinne se maklik wurde opnommen yn tekstdokumintaasje. As jo React brûke (of in oar JSX-ramt lykas Preact of Vue), kinne jo itselde dwaan mei MDX.
Dit artikel is in breed oersjoch fan ark foar it skriuwen fan dokumintaasje en it meitsjen fan rjochtlinen. Net alle hjir neamde ark brûke MDX, mar it wurdt hieltyd mear opnommen yn dokumintaasje-ark.
Wat is MDX?
file .mdx hat deselde syntaksis as Markdown, mar kinne jo ymportearje ynteraktive JSX komponinten en ynbêde se yn jo ynhâld. Stipe foar Vue-komponinten is yn alfa. Om te begjinnen mei wurkjen mei MDX, ynstallearje gewoan "React App oanmeitsje". D'r binne plugins foar Next.js en Gatsby. De folgjende ferzje fan Docusaurus (ferzje 2) sil ek native stipe hawwe.
Skriuwen fan dokumintaasje mei Docusaurus
Docusaurus skreau op Facebook. Se brûke it op elk iepen boarne-projekt útsein React. Bûten it bedriuw wurdt it brûkt troch Redux, Prettier, Gulp en Babel.
Projekten dy't Docusaurus brûke.
Docusaurus kin brûkt wurde om te skriuwen ien dokumintaasje, net allinich om de frontend te beskriuwen. It hat React ûnder de motorkap, mar jo hoege der net mei bekend te wêzen om it te brûken. It nimt jo Markdown-bestannen, in stikje magy en goed strukturearre, opmakke en lêsbere dokumintaasje mei in prachtich ûntwerp is klear.
Op de Redux-webside kinne jo it standert Docusaurus-sjabloan sjen
Websites boud mei Docusaurus kinne ek in Markdown-basearre blog omfetsje. Prism.js is fuortendaliks ferbûn foar syntaksis markearring. Nettsjinsteande it feit dat Docusaurus relatyf koartlyn ferskynde, waard it erkend as it bêste ark fan 2018 op StackShare.
Oare opsjes foar oanmeitsjen fan ynhâld
Docusaurus is spesifyk ûntworpen foar it meitsjen fan dokumintaasje. Fansels binne d'r in miljoen en ien manieren om in webside te meitsjen - jo kinne jo eigen oplossing ynsette yn elke taal, CMS, of in statyske sidegenerator brûke.
Bygelyks, dokumintaasje foar React, IBM-ûntwerpsysteem, Apollo en Ghost CMS brûke Gatsby - in statyske sidegenerator dy't faaks wurdt brûkt foar blogs. As jo mei Vue wurkje, dan is VuePress in goede opsje foar jo. In oare opsje is om in generator te brûken skreaun yn Python - MkDocs. It is iepen boarne en konfigureare mei ien YAML-bestân. GitBook is ek in goede opsje, mar it is allinich fergees foar iepenbiere en net-kommersjele teams. Jo kinne ek gewoan mardown-bestannen uploade mei Git en mei har wurkje yn Github.
Dokumentearje komponinten: Docz, Storybook en Styleguidist
Rjochtlinen, systeemûntwerp, komponintbiblioteken - wat jo se ek neame, it is de lêste tiid heul populêr wurden. De komst fan komponintframes lykas React en de hjir neamde ark hawwe se omfoarme fan idelheidsprojekten yn nuttige ark.
Storybook, Docz en Styleguidist dogge allegear itselde: werjaan ynteraktive eleminten en dokumintearje har API. In projekt kin tsientallen of sels hûnderten komponinten hawwe - allegear mei ferskate steaten en stilen. As jo wolle dat komponinten opnij brûkt wurde, moatte minsken witte dat se bestean. Om dit te dwaan, katalogisearje de komponinten gewoan. Rjochtlinen jouwe in maklik te finen oersjoch fan al jo komponinten. Dit helpt fisuele konsistinsje te behâlden en repetitive wurk te foarkommen.
Dizze ark jouwe in handige manier om ferskate steaten te besjen. It kin lestich wêze om elke steat fan in komponint te reprodusearjen yn 'e kontekst fan in echte applikaasje. Ynstee fan te klikken op 'e eigentlike applikaasje, is it de muoite wurdich om in aparte komponint te ûntwikkeljen. Moeilik te berikken steaten (lykas laden steaten) kinne wurde simulearre.
Tegearre mei in fisuele demonstraasje fan ferskate steaten en in list mei eigenskippen, is it faaks nedich om in algemiene beskriuwing fan 'e ynhâld te skriuwen - ûntwerpbegrûnen, gebrûksgefallen of beskriuwingen fan resultaten fan brûkerstests. Markdown is heul maklik te learen - ideaal soene rjochtlinen in dielde boarne wêze moatte foar ûntwerpers en ûntwikkelders. Docz, Styleguidist en Storybook biede in manier om Markdown maklik te mingjen mei komponinten.
Docz
Op it stuit wurket Docz allinich mei React, mar aktyf wurk is oan 'e gong om Preact, Vue en webkomponinten te stypjen. Docz is de meast resinte fan 'e trije ark, mar it is slagge om mear dan 14 stjerren te sammeljen op Github. Docz yntrodusearret twa komponinten - <Playground> и < Props >. Se wurde ymportearre en brûkt yn bestannen .mdx.
import { Playground, Props } from "docz";
import Button from "../src/Button";
## You can _write_ **markdown**
### You can import and use components
<Button>click</Button>Jo kinne jo eigen React-komponinten mei ynpakke <Playground>om in analoog te meitsjen fan 'e ynboude CodePen of CodeSandbox - dat is, jo sjogge jo komponint en kinne it bewurkje.
<Playground>
<Button>click</Button>
</Playground><Props> sil alle beskikbere eigenskippen sjen litte foar in opjûne React-komponint, standertwearden, en oft it pân nedich is.
<Props of={Button} />Persoanlik fyn ik dizze MDX-basearre oanpak de maklikste te begripen en de maklikste om mei te wurkjen.
As jo fan binne fan 'e Gatsby statyske sidegenerator, biedt Docz in geweldige yntegraasje.
Stylgids
Lykas Docz wurde foarbylden skreaun mei Markdown-syntaksis. Styleguidist brûkt Markdown-koadeblokken (triple quotes) yn reguliere bestannen .md triemmen, net MDX.
```js
<Button onClick={() => console.log('clicked')>Push Me</Button>Koadeblokken yn Markdown litte normaal gewoan koade sjen. By it brûken fan Styleguidist, elk blok koade mei in taaltag js, jsx of javascript sil werjaan as in React-komponint. Lykas Docz is de koade te bewurkjen - jo kinne eigenskippen feroarje en it resultaat direkt sjen.
Styleguidist sil automatysk in eigenskipstabel meitsje fan PropTypes, Flow of Typescript deklaraasjes.
Styleguidist stipet op it stuit React en Vue.
Ferhaalboek
Storybook positionearret himsels as in "UI-komponintûntwikkelingsomjouwing." Ynstee fan it skriuwen fan foarbyldkomponinten yn Markdown- as MDX-bestannen, skriuwe jo de ferhalen binnen Javascript triemmen. История dokumint de spesifike steat fan in komponint. Bygelyks, in komponint kin histoarjes hawwe foar in laden steat en in útskeakele steat (ynvalide).
storiesOf('Button', module)
.add('disabled', () => (
<Button disabled>lorem ipsum</Button>
))Ferhaleboek is folle komplekser dan Styleguidist en Docz. Mar tagelyk is dit de populêrste opsje; it projekt hat mear dan 36 stjerren op Github. It is in iepen boarne projekt mei 000 meiwurkers en fulltime personiel. It wurdt brûkt troch Airbnb, Algolia, Atlassian, Lyft en Salesforce. Storybook stipet mear kaders dan konkurrinten - React, React Native, Vue, Angular, Mithril, Ember, Riot, Svelte en reguliere HTML.
Yn in takomstige release sille d'r funksjes fan Docz en MDX wurde yntrodusearre.
# Button
Some _notes_ about your button written with **markdown syntax**.
<Story name="disabled">
<Button disabled>lorem ipsum</Button>
</Story>De nije funksjes fan Storybook sille de kommende moannen stadichoan útrolje en it liket derop dat it in grutte stap foarút sil wêze.
Resultaten
De foardielen fan in patroanbibleteek wurde ferheven yn miljoenen artikels op Medium. As goed dien, meitsje se it makliker om besibbe produkten te meitsjen en identiteit te behâlden. Fansels sil gjin fan dizze ark op magyske wize in ûntwerpsysteem meitsje. Dit fereasket foarsichtich ûntwerp en CSS. Mar as it tiid komt om in ûntwerpsysteem tagonklik te meitsjen foar it heule bedriuw, binne Docz, Storybook en Styleguidist geweldige opsjes.
Fan de oersetter. Dit is myn earste ûnderfining op Habré. As jo ûnkrektiviteiten fine, of suggestjes hawwe foar it ferbetterjen fan it artikel, skriuw dan nei my yn in persoanlik berjocht.
Boarne: www.habr.com