Malah projek sumber terbuka terbaik boleh gagal tanpa dokumentasi yang komprehensif. Dokumentasi dalaman adalah sama pentingnya, menghalang Q & A berulang dan memastikan kesinambungan pengetahuan walaupun dengan perubahan kakitangan. Garis panduan pengekodan yang didokumentasikan dengan baik mempromosikan konsistensi codebase.

Untuk dokumentasi yang luas, Markdown menawarkan alternatif yang unggul kepada HTML mentah. Walau bagaimanapun, batasan Markdown dapat diatasi dengan membenamkan HTML secara langsung dalam fail Markdown, termasuk elemen tersuai untuk sistem reka bentuk menggunakan komponen web. Untuk React (dan rangka kerja serasi JSX seperti Preact atau VUE), MDX menyediakan integrasi yang lancar.

Artikel ini memberikan gambaran keseluruhan tahap dokumentasi dan alat penciptaan panduan gaya. Walaupun tidak semua menggunakan MDX, penggunaannya semakin meningkat.

Memahami MDX

Fail .mdx mencerminkan sintaks markdown standard tetapi membolehkan import dan penyembuhan komponen JSX interaktif. Sokongan komponen Vue kini berada di Alpha. MDX mengintegrasikan dengan mudah dengan Create React App, dan plugin wujud untuk Next.js dan Gatsby. Docusaurus Versi 2 juga akan mempunyai sokongan terbina dalam.

Docusaurus: Dokumentasi Powerhouse

Dibangunkan oleh Facebook (tidak termasuk React), Docusaurus digunakan oleh banyak projek sumber terbuka utama (Redux, Prettier, Gulp, Babel). Fleksibilitasnya melangkaui dokumentasi front-end. Walaupun menggunakan React secara dalaman, Docusaurus tidak memerlukan pengetahuan yang bertindak balas untuk digunakan. Ia mengubah fail markdown ke tapak dokumentasi yang berstruktur dengan visual.

Tapak Docusaurus boleh menggabungkan blog berasaskan markdown dan termasuk prism.js untuk penonjolan sintaks yang lancar. Popularitinya jelas, setelah mengundi alat baru 2018 di Stackshare.

Penyelesaian Dokumentasi Alternatif

Walaupun Docusaurus mengkhususkan diri dalam dokumentasi, banyak alternatif wujud. Penyelesaian tersuai boleh dilaksanakan menggunakan pelbagai bahasa back-end, CMSS, atau penjana tapak statik. React, sistem reka bentuk IBM, Apollo, dan Ghost CMS, sebagai contoh, Leverage Gatsby, penjana tapak statik serba boleh yang sering digunakan untuk blog. Vuepress mendapat daya tarikan dalam ekosistem Vue. Mkdocs, penjana tapak statik sumber terbuka yang ditulis dalam Python, menawarkan konfigurasi YAML yang mudah. Gitbook, pilihan berbayar yang popular, menyediakan akses percuma kepada pasukan sumber terbuka dan bukan keuntungan. Untuk dokumentasi dalaman yang lebih mudah, keupayaan rendering markdown Github adalah pilihan yang sesuai.

Dokumentasi Komponen: Docz, Buku Cerita, dan StyleGuidist

Panduan gaya dan sistem reka bentuk telah mendapat populariti yang besar. Rangka kerja yang didorong oleh komponen (seperti React) dan alat yang berkaitan telah mengubahnya dari projek sia-sia menjadi sumber penting.

Storybook, Docz, dan StyleGuidist berfungsi dengan tujuan yang sama: memaparkan komponen UI interaktif dan mendokumentasikan API mereka. Menguruskan pelbagai komponen dengan pelbagai negeri dan gaya memerlukan katalog berpusat untuk penemuan dan penggunaan semula. Panduan gaya memberikan gambaran keseluruhan yang mudah dicari, mempromosikan konsistensi visual dan mencegah kerja yang berlebihan.

Alat ini memudahkan kajian semula keadaan komponen yang berbeza, mengatasi cabaran menghasilkan semula semua negeri dalam aplikasi langsung. Pembangunan komponen terpencil membolehkan mengejek keadaan yang sukar dicapai (contohnya, keadaan pemuatan).

Komen Dan Green mengenai faedah buku cerita digunakan sama dengan Docz dan StyleGuidist:

"Buku cerita telah mempermudah kerjasama antara reka bentuk dan kejuruteraan. Ia menghapuskan keperluan untuk persediaan yang kompleks (bekas docker, dll). Untuk gelombang, kami menguruskan komponen yang hanya dapat dilihat semasa proses yang berpanjangan, kompleks (misalnya, skrin memuatkan).

- Dan Green, Gelombang Kewangan

Di luar memvisualisasikan keadaan dan penyenaraian prop, kandungan bertulis (rasional reka bentuk, kes penggunaan, hasil pengujian pengguna) meningkatkan dokumentasi komponen. Kebolehcapaian Markdown menjadikannya sesuai untuk dokumentasi kerjasama antara pereka dan pemaju. Docz, Styleguidist, dan Storybook dengan lancar mengintegrasikan markdown dengan komponen.

Docz

Pada masa ini React-only (dengan sokongan yang dirancang untuk komponen Preact, Vue, dan Web), Docz (14,000 GitHub Stars) menawarkan fungsi mesra pengguna. Ia menyediakan<playground></playground> dan<props></props> komponen, yang digunakan secara langsung dalam fail .mdx .

 import {mainground, props} dari "docz";
butang import dari "../src/button";

## anda boleh _write_ ** markdown **
### Anda boleh mengimport dan menggunakan komponen

<playground>
  <button>klik</button>
</playground>

Membungkus komponen reaksi dengan<playground></playground> mewujudkan pratonton interaktif tertanam.<props></props> Memaparkan alat komponen, nilai lalai, dan status yang diperlukan.

<props of="{Button}"></props>

Pendekatan berasaskan MDX Docz adalah intuitif dan cekap, menawarkan integrasi Gatsby yang sangat baik.

Styleguidist

Styleguidist menggunakan blok kod markdown (triple backticks) dalam fail .md standard dan bukannya MDX.

 `` `JS
 Console.log ('diklik')

<code></code>

 <code>>Push Me</code>

Blok kod yang ditandai js , jsx , atau javascript menjadikan komponen reaksi interaktif. Kod ini boleh diedit, memberikan maklum balas visual segera. Styleguidist secara automatik menjana jadual prop dari pengisytiharan Proptypes, Flow, atau TypeScript. Ia menyokong React dan Vue.

Buku cerita

Buku cerita (36,000 bintang GitHub) adalah persekitaran pembangunan komponen UI. Daripada Markdown/MDX, ia menggunakan fail JavaScript untuk cerita (mewakili keadaan komponen).

 cerita ('butang', modul)
  .add ('dilumpuhkan', () => (
    <button disabled>lorem ipsum</button>
  )))

Pendekatan Storybook kurang intuitif daripada Docz dan Styleguidist. Walau bagaimanapun, populariti dan sokongan rangka kerja yang luas (React, React Native, Vue, Angular, Mithril, Ember, Riot, Svelte, HTML) patut diberi perhatian. Dokumentasi pada masa ini memerlukan addons, tetapi siaran masa depan akan menggabungkan MDX, yang diilhamkan oleh Docz.

 Butang #

Beberapa _notes_ mengenai butang anda yang ditulis dengan ** sintaks Markdown **.


<button>lorem ipsum</button>

Dokumen Dokumen Storybook yang akan datang menjanjikan penambahbaikan yang ketara.

Kesimpulan

Nilai perpustakaan corak diakui secara meluas. Perpustakaan yang dilaksanakan dengan baik menggalakkan konsistensi visual dan perpaduan produk. Walaupun alat ini tidak menggantikan reka bentuk dan kepakaran CSS, Docz, Storybook, dan StyleGuidist menyediakan penyelesaian yang sangat baik untuk menyampaikan sistem reka bentuk dengan berkesan dalam organisasi.

Atas ialah kandungan terperinci Dokumentasi depan, panduan gaya dan kebangkitan MDX. Untuk maklumat lanjut, sila ikut artikel berkaitan lain di laman web China PHP!