Garis panduan hidup - MDX dan rangka kerja lain

Anda boleh mempunyai projek sumber terbuka yang terbaik, tetapi jika ia tidak mempunyai dokumentasi yang baik, kemungkinan besar ia tidak akan berjaya. Di pejabat, dokumentasi yang baik akan menghalang anda daripada menjawab soalan yang sama. Dokumentasi juga memastikan bahawa orang ramai boleh memahami projek jika pekerja utama meninggalkan syarikat atau peranan berubah. Garis panduan hidup akan membantu memastikan integriti data.

Jika anda perlu menulis teks panjang, Markdown ialah alternatif yang bagus untuk HTML. Kadangkala sintaks Markdown tidak mencukupi. Dalam kes ini kita boleh menggunakan HTML di dalamnya. Contohnya, elemen tersuai. Oleh itu, jika anda membina sistem reka bentuk dengan komponen web asli, ia boleh disertakan dengan mudah dalam dokumentasi teks. Jika anda menggunakan React (atau mana-mana rangka kerja JSX lain seperti Preact atau Vue), anda boleh melakukan perkara yang sama dengan MDX.

Artikel ini ialah gambaran keseluruhan alat untuk menulis dokumentasi dan membuat garis panduan. Tidak semua alat yang disenaraikan di sini menggunakan MDX, tetapi ia semakin disertakan dalam alat dokumentasi.

Apakah MDX?

fail .mdx mempunyai sintaks yang sama seperti Markdown, tetapi membolehkan anda mengimport komponen JSX interaktif dan membenamkannya ke dalam kandungan anda. Sokongan untuk komponen Vue adalah dalam alpha. Untuk mula bekerja dengan MDX, cuma pasang "Buat Apl Reaksi". Terdapat pemalam untuk Next.js dan Gatsby. Versi seterusnya Docusaurus (versi 2) juga akan mempunyai sokongan asli.

Menulis dokumentasi dengan Docusaurus

Docusaurus menulis di Facebook. Mereka menggunakannya pada setiap projek sumber terbuka kecuali React. Di luar syarikat ia digunakan oleh Redux, Prettier, Gulp dan Babel.

Projek yang menggunakan Docusaurus.

Docusaurus boleh digunakan untuk menulis mana-mana dokumentasi, bukan sahaja untuk menerangkan bahagian hadapan. Ia mempunyai React di bawah hud, tetapi anda tidak perlu membiasakannya untuk menggunakannya. Ia memerlukan fail Markdown anda, sedikit keajaiban dan dokumentasi yang tersusun dengan baik, berformat dan boleh dibaca dengan reka bentuk yang cantik sudah sedia.

Di tapak web Redux anda boleh melihat templat Docusaurus standard

Tapak web yang dibina dengan Docusaurus juga boleh menyertakan blog berasaskan Markdown. Prism.js disambungkan serta-merta untuk penyerlahan sintaks. Walaupun fakta bahawa Docusaurus muncul agak baru-baru ini, ia diiktiraf sebagai alat terbaik 2018 di StackShare.

Pilihan Penciptaan Kandungan Lain

Docusaurus direka khusus untuk membuat dokumentasi. Sudah tentu, terdapat sejuta dan satu cara untuk membuat tapak web - anda boleh menggunakan penyelesaian anda sendiri dalam mana-mana bahasa, CMS, atau menggunakan penjana tapak statik.

Sebagai contoh, dokumentasi untuk React, sistem reka bentuk IBM, Apollo dan Ghost CMS menggunakan Gatsby - penjana tapak statik yang sering digunakan untuk blog. Jika anda bekerja dengan Vue, maka VuePress ialah pilihan yang baik untuk anda. Pilihan lain ialah menggunakan penjana yang ditulis dalam Python - MkDocs. Ia adalah sumber terbuka dan dikonfigurasikan menggunakan satu fail YAML. GitBook juga merupakan pilihan yang baik, tetapi ia hanya percuma untuk pasukan awam dan bukan komersial. Anda juga boleh memuat naik fail mardown menggunakan Git dan bekerja dengannya dalam Github.

Komponen pendokumentasian: Docz, Buku Cerita dan Styleguidist

Garis panduan, reka bentuk sistem, perpustakaan komponen - apa sahaja panggilan anda, ia telah menjadi sangat popular sejak kebelakangan ini. Kemunculan rangka kerja komponen seperti React dan alat yang disebutkan di sini telah mengubahnya daripada projek sia-sia kepada alat yang berguna.

Buku cerita, Docz dan Styleguidist semuanya melakukan perkara yang sama: paparkan elemen interaktif dan dokumentasikan API mereka. Sesuatu projek boleh mempunyai berpuluh-puluh atau bahkan ratusan komponen - semuanya dengan keadaan dan gaya yang berbeza. Jika anda mahu komponen digunakan semula, orang ramai perlu tahu ia wujud. Untuk melakukan ini, hanya katalog komponen. Garis panduan menyediakan gambaran keseluruhan yang mudah dicari bagi semua komponen anda. Ini membantu mengekalkan konsistensi visual dan mengelakkan kerja berulang.

Alat ini menyediakan cara yang mudah untuk melihat keadaan yang berbeza. Ia boleh menjadi sukar untuk menghasilkan semula setiap keadaan komponen dalam konteks aplikasi sebenar. Daripada mengklik pada aplikasi sebenar, ia patut membangunkan komponen yang berasingan. Keadaan yang sukar dicapai (seperti keadaan pemuatan) boleh disimulasikan.

Bersama-sama dengan demonstrasi visual pelbagai keadaan dan senarai sifat, selalunya perlu menulis penerangan umum kandungan - rasional reka bentuk, kes penggunaan atau perihalan hasil ujian pengguna. Penurunan harga sangat mudah dipelajari - secara idealnya, garis panduan harus menjadi sumber yang dikongsi untuk pereka bentuk dan pembangun. Docz, Styleguidist dan Buku Cerita menawarkan cara untuk menggabungkan Markdown dengan komponen dengan mudah.

Docz

Pada masa ini Docz hanya berfungsi dengan React, tetapi kerja aktif sedang dijalankan untuk menyokong Preact, Vue dan komponen web. Docz adalah yang paling terkini daripada tiga alatan, tetapi ia telah berjaya mengumpul lebih 14 bintang di Github. Docz memperkenalkan dua komponen − <Playground> и < Props >. Ia diimport dan digunakan dalam fail .mdx.

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

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

<Button>click</Button>

Anda boleh membungkus komponen React anda sendiri dengan <Playground>untuk mencipta analog CodePen atau CodeSandbox terbina dalam - iaitu, anda melihat komponen anda dan boleh mengeditnya.

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

<Props> akan menunjukkan semua sifat yang tersedia untuk komponen React tertentu, nilai lalai dan sama ada sifat itu diperlukan.

<Props of={Button} />

Secara peribadi, saya mendapati pendekatan berasaskan MDX ini adalah yang paling mudah difahami dan paling mudah untuk digunakan.

Jika anda peminat penjana tapak statik Gatsby, Docz menawarkan integrasi yang hebat.

Panduan gaya

Seperti Docz, contoh ditulis menggunakan sintaks Markdown. Styleguidist menggunakan blok kod Markdown (petikan tiga kali ganda) dalam fail biasa .md fail, bukan MDX.

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

Blok kod dalam Markdown biasanya hanya menunjukkan kod. Apabila menggunakan Styleguidist, mana-mana blok kod dengan tag bahasa js, jsx atau javascript akan dipaparkan sebagai komponen React. Seperti Docz, kod itu boleh diedit - anda boleh menukar sifat dan serta-merta melihat hasilnya.

Styleguidist akan membuat jadual sifat secara automatik daripada PropTypes, Flow atau Typescript pengisytiharan.

Styleguidist kini menyokong React dan Vue.

Buku cerita

Buku cerita meletakkan dirinya sebagai "persekitaran pembangunan komponen UI." Daripada menulis komponen contoh dalam fail Markdown atau MDX, anda menulis cerita dalam fail Javascript. Kisah mendokumenkan keadaan khusus komponen. Sebagai contoh, komponen mungkin mempunyai sejarah untuk keadaan dimuatkan dan keadaan dilumpuhkan (orang kurang upaya).

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

Buku cerita jauh lebih kompleks daripada Styleguidist dan Docz. Tetapi pada masa yang sama, ini adalah pilihan yang paling popular; projek itu mempunyai lebih daripada 36 bintang di Github. Ia adalah projek sumber terbuka dengan 000 penyumbang dan kakitangan sepenuh masa. Ia digunakan oleh Airbnb, Algolia, Atlassian, Lyft dan Salesforce. Buku cerita menyokong lebih banyak rangka kerja berbanding pesaing - React, React Native, Vue, Angular, Mithril, Ember, Riot, Svelte dan HTML biasa.

Dalam keluaran akan datang akan ada ciri dari Docz dan MDX akan diperkenalkan.

# Button

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

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

Ciri baharu buku cerita akan dilancarkan secara beransur-ansur dalam beberapa bulan akan datang dan nampaknya ia akan menjadi satu langkah besar ke hadapan.

Keputusan

Faedah perpustakaan corak dipuji dalam berjuta-juta artikel di Medium. Apabila dilakukan dengan baik, mereka memudahkan untuk mencipta produk berkaitan dan mengekalkan identiti. Sudah tentu, tiada alat ini akan mencipta sistem reka bentuk secara ajaib. Ini memerlukan reka bentuk dan CSS yang teliti. Tetapi apabila tiba masanya untuk menjadikan sistem reka bentuk boleh diakses oleh seluruh syarikat, Docz, Buku Cerita dan Styleguidist adalah pilihan yang hebat.

Daripada penterjemah. Ini adalah pengalaman pertama saya di Habré. Jika anda mendapati sebarang ketidaktepatan, atau mempunyai cadangan untuk menambah baik artikel, tulis kepada saya dalam mesej peribadi.

Sumber: www.habr.com