Pedoman urip - MDX lan kerangka kerja liyane

Sampeyan bisa duwe proyek open source sing paling apik, nanging yen ora duwe dokumentasi sing apik, kemungkinan ora bakal ilang. Ing kantor, dokumentasi sing apik bakal nyegah sampeyan njawab pitakonan sing padha. Dokumentasi uga njamin manawa wong bisa ngerti proyek kasebut yen karyawan utama ninggalake perusahaan utawa owah-owahan peran. Pedoman urip bakal mbantu njamin integritas data.

Yen sampeyan kudu nulis teks dawa, Markdown minangka alternatif sing apik kanggo HTML. Kadhangkala sintaks Markdown ora cukup. Ing kasus iki kita bisa nggunakake HTML nang. Contone, unsur adat. Mulane, yen sampeyan mbangun sistem desain kanthi komponen web asli, bisa gampang dilebokake ing dokumentasi teks. Yen sampeyan nggunakake React (utawa kerangka JSX liyane kaya Preact utawa Vue), sampeyan bisa nindakake perkara sing padha nggunakake MDX.

Artikel iki minangka gambaran umum babagan alat kanggo nulis dokumentasi lan nggawe pedoman. Ora kabeh alat sing didhaptar ing kene nggunakake MDX, nanging tambah akeh kalebu ing alat dokumentasi.

Apa MDX?

berkas .mdx nduweni sintaks sing padha karo Markdown, nanging ngidini sampeyan ngimpor komponen JSX interaktif lan nglebokake menyang konten sampeyan. Dhukungan kanggo komponen Vue ana ing alpha. Kanggo miwiti nggarap MDX, mung nginstal "Gawe React App". Ana plugins kanggo Next.js lan Gatsby. Versi sabanjure Docusaurus (versi 2) uga bakal duwe dhukungan asli.

Nulis dokumentasi nganggo Docusaurus

Docusaurus nulis ing Facebook. Dheweke nggunakake ing saben proyek open source kajaba React. Ing njaba perusahaan digunakake dening Redux, Prettier, Gulp lan Babel.

Proyek sing nggunakake Docusaurus.

Docusaurus bisa digunakake kanggo nulis apa wae dokumentasi, ora mung kanggo njlèntrèhaké frontend. Wis React ing hood, nanging sampeyan ora kudu menowo kanggo nggunakake. Sampeyan butuh file Markdown, sawetara sihir lan dokumentasi sing terstruktur, diformat lan bisa diwaca kanthi desain sing apik.

Ing situs web Redux sampeyan bisa ndeleng template Docusaurus standar

Situs web sing dibangun nganggo Docusaurus uga bisa kalebu blog adhedhasar Markdown. Prism.js langsung disambungake kanggo nyorot sintaks. Sanajan kasunyatane Docusaurus muncul relatif anyar, iki diakoni minangka alat paling apik ing 2018 ing StackShare.

Pilihan Nggawe Konten Liyane

Docusaurus dirancang khusus kanggo nggawe dokumentasi. Mesthi, ana yuta lan siji cara kanggo nggawe situs web - sampeyan bisa masang solusi dhewe ing basa apa wae, CMS, utawa nggunakake generator situs statis.

Contone, dokumentasi kanggo React, sistem desain IBM, Apollo lan Ghost CMS nggunakake Gatsby - generator situs statis sing asring digunakake kanggo blog. Yen sampeyan nggarap Vue, banjur VuePress minangka pilihan sing apik kanggo sampeyan. Pilihan liyane yaiku nggunakake generator sing ditulis ing Python - MkDocs. Iki mbukak sumber lan dikonfigurasi nggunakake file YAML siji. GitBook uga minangka pilihan sing apik, nanging mung gratis kanggo tim umum lan non-komersial. Sampeyan uga bisa ngunggah file mardown nggunakake Git lan nggarap file kasebut ing Github.

Komponen dokumentasi: Docz, Storybook lan Styleguidist

Pedoman, desain sistem, perpustakaan komponen - apa wae sing sampeyan sebut, akhir-akhir iki dadi populer banget. Tekane kerangka komponen kaya React lan alat sing kasebut ing kene wis ngowahi saka proyek kesombongan dadi alat sing migunani.

Storybook, Docz lan Styleguidist kabeh nindakake perkara sing padha: nampilake unsur interaktif lan dokumen API. Proyek bisa duwe puluhan utawa malah atusan komponen - kabeh kanthi negara lan gaya sing beda. Yen sampeyan pengin komponen digunakake maneh, wong kudu ngerti yen ana. Kanggo nindakake iki, mung katalog komponen. Pedoman nyedhiyakake ringkesan sing gampang ditemokake kabeh komponen sampeyan. Iki mbantu njaga konsistensi visual lan nyegah karya sing bola-bali.

Piranti kasebut nyedhiyakake cara sing trep kanggo ndeleng macem-macem negara. Bisa dadi angel kanggo ngasilake saben negara komponen ing konteks aplikasi nyata. Tinimbang ngeklik aplikasi nyata, luwih becik ngembangake komponen sing kapisah. Negara sing angel digayuh (kayata status loading) bisa disimulasikan.

Bebarengan karo demonstrasi visual saka macem-macem negara lan dhaptar properti, asring perlu nulis deskripsi umum babagan isi - rasional desain, kasus panggunaan, utawa deskripsi asil tes pangguna. Markdown gampang banget kanggo sinau - saenipun, pedoman kudu dadi sumber daya sing dienggo bareng kanggo perancang lan pangembang. Docz, Styleguidist, lan Storybook nawakake cara kanggo gampang nyampur Markdown karo komponen.

Dok

Saiki Docz mung bisa digunakake karo React, nanging karya aktif ditindakake kanggo ndhukung Preact, Vue lan komponen web. Docz minangka alat paling anyar saka telung alat kasebut, nanging wis bisa nglumpukake luwih saka 14 bintang ing Github. Docz ngenalake rong komponen − <Playground> и < Props >. Padha diimpor lan digunakake ing 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>

Sampeyan bisa mbungkus komponen React dhewe karo <Playground>kanggo nggawe analog saka CodePen utawa CodeSandbox sing dibangun - yaiku, sampeyan ndeleng komponen sampeyan lan bisa ngowahi.

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

<Props> bakal nuduhake kabeh sifat sing kasedhiya kanggo komponen React sing diwenehake, nilai standar, lan apa properti kasebut dibutuhake.

<Props of={Button} />

Secara pribadi, aku nemokake pendekatan adhedhasar MDX iki minangka sing paling gampang dingerteni lan paling gampang digarap.

Yen sampeyan penggemar generator situs statis Gatsby, Docz nawakake integrasi sing apik.

Pandhuan gaya

Kaya Docz, conto ditulis nggunakake sintaks Markdown. Styleguidist nggunakake pamblokiran kode Markdown (kuotasi telung) ing file biasa .md file, ora MDX.

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

Blok kode ing Markdown biasane mung nuduhake kode. Nalika nggunakake Styleguidist, sembarang blok kode karo tag basa js, jsx utawa javascript bakal nerjemahake minangka komponen React. Kaya Docz, kode kasebut bisa diowahi - sampeyan bisa ngganti properti lan langsung ndeleng asile.

Styleguidist bakal nggawe tabel properti kanthi otomatis saka PropTypes, Flow utawa Typescript deklarasi.

Styleguidist saiki ndhukung React lan Vue.

Buku Crita

Storybook posisi dhewe minangka "lingkungan pangembangan komponen UI." Tinimbang nulis komponen conto ing file Markdown utawa MDX, sampeyan nulis crita nang file Javascript. История dokumen kahanan tartamtu saka komponen. Contone, komponen bisa uga duwe riwayat kanggo status dimuat lan status dipatèni (dipatèni).

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

Storybook luwih rumit tinimbang Styleguidist lan Docz. Nanging ing wektu sing padha, iki minangka pilihan sing paling populer; proyek kasebut duwe luwih saka 36 bintang ing Github. Iki minangka proyek open source kanthi 000 kontributor lan staf full-time. Iki digunakake dening Airbnb, Algolia, Atlassian, Lyft lan Salesforce. Storybook ndhukung kerangka kerja luwih akeh tinimbang pesaing - React, React Native, Vue, Angular, Mithril, Ember, Riot, Svelte lan HTML biasa.

Ing release mangsa bakal ana fitur saka Docz lan MDX bakal ngenalaken.

# Button

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

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

Fitur anyar Storybook bakal diluncurake kanthi bertahap sajrone sawetara wulan sabanjure lan kayane bakal dadi langkah maju.

Hasil

Keuntungan saka perpustakaan pola dipuji ing jutaan artikel ing Medium. Yen rampung kanthi becik, dheweke nggawe luwih gampang nggawe produk sing gegandhengan lan njaga identitas. Mesthine, ora ana alat kasebut kanthi ajaib nggawe sistem desain. Iki mbutuhake desain sing ati-ati lan CSS. Nanging nalika entuk wektu kanggo nggawe sistem desain bisa diakses kabeh perusahaan, Docz, Storybook lan Styleguidist minangka pilihan sing apik.

Saka penerjemah. Iki pengalaman pisanan ing Habré. Yen sampeyan nemokake sing ora akurat, utawa duwe saran kanggo ngapikake artikel, nulis menyang aku ing pesen pribadi.

Source: www.habr.com