Anjeun tiasa gaduh proyék open source pangsaéna, tapi upami éta henteu gaduh dokuméntasi anu saé, kamungkinan éta moal pernah pareum. Di kantor, dokuméntasi anu saé bakal nyegah anjeun ngawalon patarosan anu sami. Dokuméntasi ogé mastikeun yén jalma-jalma tiasa ngartos proyék éta upami karyawan konci ngantunkeun perusahaan atanapi robih kalungguhan. Tungtunan hirup bakal ngabantosan mastikeun integritas data.
Upami anjeun kedah nyerat téks anu panjang, Markdown mangrupikeun alternatif anu hadé pikeun HTML. Kadang sintaksis Markdown henteu cekap. Dina hal ieu urang tiasa nganggo HTML di jerona. Contona, elemen custom. Janten, upami anjeun ngawangun sistem desain sareng komponén wéb asli, aranjeunna tiasa gampang diasupkeun kana dokuméntasi téks. Upami anjeun nganggo React (atanapi kerangka JSX anu sanés sapertos Preact atanapi Vue), anjeun tiasa ngalakukeun hal anu sami nganggo MDX.
Tulisan ieu mangrupikeun tinjauan lega alat pikeun nyerat dokuméntasi sareng nyiptakeun pedoman. Henteu sakabéh parabot didaptarkeun di dieu ngagunakeun MDX, tapi ieu beuki keur kaasup dina parabot dokuméntasi.
Naon MDX?
file .mdx boga sintaksis sarua Markdown, tapi ngidinan Anjeun pikeun ngimpor komponén JSX interaktif tur embed kana eusi Anjeun. Rojongan pikeun komponén Vue aya dina alfa. Pikeun ngamimitian damel sareng MDX, pasang "Jieun React App". Aya plugins pikeun Next.js jeung Gatsby. Versi salajengna Docusaurus (versi 2) ogé bakal gaduh dukungan asli.
Nulis dokuméntasi jeung Docusaurus
Docusaurus nyerat dina Facebook. Aranjeunna nganggo éta dina unggal proyék open source iwal React. Di luar perusahaan dianggo ku Redux, Prettier, Gulp sareng Babel.
Proyék anu ngagunakeun Docusaurus.
Docusaurus bisa dipaké pikeun nulis sagala dokuméntasi, teu ukur keur ngajelaskeun frontend nu. Éta ngagaduhan React handapeun tiung, tapi anjeun henteu kedah wawuh pikeun ngagunakeunana. Butuh file Markdown anjeun, ciwit sihir sareng dokuméntasi anu terstruktur, formatna sareng tiasa dibaca kalayan desain anu saé parantos siap.
Dina situs wéb Redux anjeun tiasa ningali template Docusaurus standar
Situs wéb anu diwangun ku Docusaurus ogé tiasa ngalebetkeun blog dumasar Markdown. Prism.js langsung disambungkeun pikeun panyorot sintaksis. Najan kanyataan yén Docusaurus mucunghul rélatif anyar, éta dipikawanoh salaku alat pangalusna 2018 on StackShare.
Pilihan Nyiptakeun Kandungan séjén
Docusaurus dirancang husus pikeun nyieun dokuméntasi. Tangtosna, aya sajuta sareng hiji cara pikeun ngadamel halaman wéb - anjeun tiasa nyebarkeun solusi anjeun nyalira dina basa naon waé, CMS, atanapi nganggo generator situs statik.
Salaku conto, dokuméntasi pikeun React, sistem desain IBM, Apollo sareng Ghost CMS nganggo Gatsby - generator situs statik anu sering dianggo pikeun blog. Upami anjeun damel sareng Vue, maka VuePress mangrupikeun pilihan anu saé pikeun anjeun. Pilihan séjén nyaéta ngagunakeun generator ditulis dina Python - MkDocs. Éta open source sareng dikonpigurasi nganggo file YAML tunggal. GitBook ogé pilihan anu saé, tapi éta ngan ukur gratis pikeun tim umum sareng non-komersial. Anjeun ogé tiasa ngan ukur unggah file mardown nganggo Git sareng damel sareng aranjeunna dina Github.
Dokuméntasi komponén: Docz, Storybook na Styleguidist
Tungtunan, desain sistem, perpustakaan komponén - naon waé anu anjeun sebut, éta parantos populer pisan akhir-akhir ieu. Munculna kerangka komponén sapertos React sareng alat anu disebatkeun di dieu parantos ngarobih aranjeunna tina proyék kasombongan janten alat anu mangpaat.
Storybook, Docz sareng Styleguidist sadayana ngalakukeun hal anu sami: nampilkeun elemen interaktif sareng dokumén API na. Hiji proyék tiasa gaduh puluhan atanapi malah ratusan komponén - sadayana kalayan kaayaan sareng gaya anu béda. Upami anjeun hoyong komponén tiasa dianggo deui, jalma kedah terang yén éta aya. Jang ngalampahkeun ieu, ngan saukur katalog komponén. Tungtunan nyadiakeun tinjauan gampang pikeun manggihan sakabeh komponen Anjeun. Ieu ngabantuan ngajaga konsistensi visual jeung nyegah karya repetitive.
Alat ieu nyayogikeun cara anu gampang pikeun ningali kaayaan anu béda. Bisa jadi hésé baranahan unggal kaayaan komponén dina konteks hiji aplikasi nyata. Gantina ngaklik dina aplikasi nu sabenerna, éta patut ngamekarkeun komponén misah. Kaayaan anu susah dihontal (sapertos kaayaan ngamuat) tiasa disimulasi.
Marengan démo visual rupa-rupa nagara bagian jeung daptar sipat, mindeng perlu nulis pedaran umum eusi - rationales design, kasus pamakéan, atawa déskripsi hasil nguji pamaké. Markdown gampang pisan diajar - idéal, tungtunan kedah janten sumber daya anu dibagikeun pikeun désainer sareng pamekar. Docz, Styleguidist, sareng Storybook nawiskeun cara pikeun gampang nyampur Markdown sareng komponén.
Dok
Ayeuna Docz ngan ukur tiasa dianggo sareng React, tapi padamelan aktip dijalankeun pikeun ngadukung Preact, Vue sareng komponén wéb. Docz mangrupikeun anu pang anyarna tina tilu alat, tapi parantos tiasa ngumpulkeun langkung ti 14 béntang dina Github. Docz ngawanohkeun dua komponén − <Playground> и < Props >. Éta diimpor sareng dianggo dina file .mdx.
import { Playground, Props } from "docz";
import Button from "../src/Button";
## You can _write_ **markdown**
### You can import and use components
<Button>click</Button>Anjeun tiasa mungkus komponén Réaksi anjeun nyalira <Playground>pikeun nyiptakeun analog tina CodePen atanapi CodeSandbox anu diwangun - nyaéta, anjeun ningali komponén anjeun sareng tiasa ngédit éta.
<Playground>
<Button>click</Button>
</Playground><Props> bakal mintonkeun sadaya sipat sadia pikeun komponén React dibikeun, nilai standar, jeung naha sipat diperlukeun.
<Props of={Button} />Pribadi, kuring manggihan pendekatan dumasar MDX ieu panggampangna pikeun ngarti tur panggampangna pikeun digawekeun ku.
Upami anjeun kipas tina generator situs statik Gatsby, Docz nawiskeun integrasi anu saé.
Pituduh gaya
Sapertos Docz, conto ditulis nganggo sintaksis Markdown. Styleguidist ngagunakeun blok kode Markdown (tanda kutip triple) dina file biasa .md file, sanes MDX.
```js
<Button onClick={() => console.log('clicked')>Push Me</Button>Blok kode dina Markdown biasana ngan ukur nunjukkeun kode. Nalika nganggo Styleguidist, blok kode naon waé anu nganggo tag basa js, jsx atawa javascript bakal ngajadikeun salaku komponén Réaksi. Sapertos Docz, kodeu tiasa diédit - anjeun tiasa ngarobih sipat sareng langsung ningali hasilna.
Styleguidist bakal otomatis nyieun tabel sipat tina PropTypes, Aliran atanapi Typescript deklarasi.
Styleguidist ayeuna ngadukung React sareng Vue.
Buku Carita
Storybook posisi dirina salaku "lingkungan ngembangkeun komponén UI." Gantina nulis komponén conto di jero Markdown atanapi MDX file, anjeun nulis sajarah jero file Javascript. dongeng dokumén kaayaan spésifik komponén. Contona, komponén bisa mibanda sajarah pikeun kaayaan dimuat jeung kaayaan ditumpurkeun (cacad).
storiesOf('Button', module)
.add('disabled', () => (
<Button disabled>lorem ipsum</Button>
))Storybook langkung kompleks tibatan Styleguidist sareng Docz. Tapi dina waktos anu sami, ieu mangrupikeun pilihan anu paling populér pikeun proyék éta langkung ti 36 béntang dina Github. Éta mangrupikeun proyék open source kalayan 000 kontributor sareng staf full-time. Éta dianggo ku Airbnb, Algolia, Atlassian, Lyft sareng Salesforce. Buku carita ngadukung langkung seueur kerangka tibatan pesaing - React, React Native, Vue, Angular, Mithril, Ember, Riot, Svelte sareng HTML biasa.
Dina siaran hareup bakal aya fitur ti Docz jeung MDX bakal diwanohkeun.
# Button
Some _notes_ about your button written with **markdown syntax**.
<Story name="disabled">
<Button disabled>lorem ipsum</Button>
</Story>Fitur anyar Storybook bakal diluncurkeun laun-laun dina sababaraha bulan ka hareup sareng sigana éta bakal janten léngkah anu ageung.
hasil
Mangpaat perpustakaan pola anu extolled dina jutaan artikel dina Medium. Nalika dilakukeun saé, aranjeunna ngagampangkeun nyiptakeun produk anu aya hubunganana sareng ngajaga identitas. Tangtosna, teu aya alat-alat ieu anu bakal nyiptakeun sistem desain. Ieu merlukeun desain ati tur CSS. Tapi lamun datang waktuna sangkan sistem desain diaksés ka sakabéh parusahaan, Docz, Storybook na Styleguidist pilihan hébat.
Ti penerjemah. Ieu mangrupikeun pangalaman munggaran kuring dina Habré. Upami anjeun mendakan anu teu akurat, atanapi gaduh saran pikeun ningkatkeun tulisan, nyerat ka kuring dina pesen pribadi.
sumber: www.habr.com