Pedoman langsung - MDX dan kerangka kerja lainnya

Anda dapat memiliki proyek sumber terbuka terbaik, tetapi jika proyek tersebut tidak memiliki dokumentasi yang baik, kemungkinan besar proyek tersebut tidak akan pernah berhasil. Di kantor, dokumentasi yang baik akan mencegah Anda menjawab pertanyaan yang sama. Dokumentasi juga memastikan bahwa orang-orang dapat memahami proyek jika karyawan kunci meninggalkan perusahaan atau perubahan peran. Pedoman hidup akan membantu memastikan integritas data.

Jika Anda perlu menulis teks yang panjang, Markdown adalah alternatif yang bagus untuk HTML. Terkadang sintaks Markdown saja tidak cukup. Dalam hal ini kita bisa menggunakan HTML di dalamnya. Misalnya, elemen khusus. Oleh karena itu, jika Anda sedang membangun sistem desain dengan komponen web asli, komponen tersebut dapat dengan mudah disertakan dalam dokumentasi teks. Jika Anda menggunakan React (atau kerangka kerja JSX lainnya seperti Preact atau Vue), Anda dapat melakukan hal yang sama dengan MDX.

Artikel ini adalah ikhtisar luas tentang alat untuk menulis dokumentasi dan membuat pedoman. Tidak semua alat yang tercantum di sini menggunakan MDX, namun semakin banyak yang disertakan dalam alat dokumentasi.

Apa itu MDX?

berkas .mdx memiliki sintaks yang sama dengan Markdown, tetapi memungkinkan Anda mengimpor komponen JSX interaktif dan menyematkannya ke dalam konten Anda. Dukungan untuk komponen Vue masih dalam tahap alpha. Untuk mulai bekerja dengan MDX, cukup instal “Buat Aplikasi React”. Ada plugin untuk Next.js dan Gatsby. Versi Docusaurus berikutnya (versi 2) juga akan mendapat dukungan asli.

Menulis dokumentasi dengan Docusaurus

tulis Docusaurus di Facebook. Mereka menggunakannya di setiap proyek open source kecuali React. Di luar perusahaan ini digunakan oleh Redux, Prettier, Gulp dan Babel.

Proyek yang menggunakan Docusaurus.

Docusaurus dapat digunakan untuk menulis apa saja dokumentasi, tidak hanya untuk mendeskripsikan frontend. Ia memiliki React, tetapi Anda tidak harus terbiasa dengannya untuk menggunakannya. Dibutuhkan file Markdown Anda, sedikit keajaiban dan dokumentasi yang terstruktur dengan baik, diformat dan dapat dibaca dengan desain yang indah sudah siap.

Di situs web Redux Anda dapat melihat template Docusaurus standar

Situs web yang dibangun dengan Docusaurus juga dapat menyertakan blog berbasis penurunan harga. Prism.js segera terhubung untuk penyorotan sintaksis. Meskipun Docusaurus muncul relatif baru, Docusaurus diakui sebagai alat terbaik tahun 2018 di StackShare.

Opsi Pembuatan Konten Lainnya

Docusaurus dirancang khusus untuk membuat dokumentasi. Tentu saja, ada sejuta cara untuk membuat situs web - Anda dapat menerapkan solusi Anda sendiri dalam bahasa apa pun, CMS, atau menggunakan generator situs statis.

Misalnya dokumentasi untuk React, sistem desain IBM, Apollo dan Ghost CMS menggunakan Gatsby - generator situs statis yang sering digunakan untuk blog. Jika Anda bekerja dengan Vue, maka VuePress adalah pilihan yang baik untuk Anda. Pilihan lainnya adalah menggunakan generator yang ditulis dengan Python - MkDocs. Ini adalah open source dan dikonfigurasi menggunakan satu file YAML. GitBook juga merupakan pilihan yang bagus, tetapi hanya gratis untuk tim publik dan non-komersial. Anda juga dapat mengunggah file mardown menggunakan Git dan mengerjakannya di Github.

Komponen pendokumentasian: Docz, Storybook, dan Styleguidist

Pedoman, desain sistem, pustaka komponen - apa pun sebutannya, akhir-akhir ini menjadi sangat populer. Munculnya kerangka komponen seperti React dan alat-alat yang disebutkan di sini telah mengubahnya dari proyek sia-sia menjadi alat yang berguna.

Storybook, Docz, dan Styleguidist semuanya melakukan hal yang sama: menampilkan elemen interaktif dan mendokumentasikan API mereka. Sebuah proyek dapat memiliki lusinan atau bahkan ratusan komponen - semuanya dengan status dan gaya berbeda. Jika Anda ingin komponen digunakan kembali, orang perlu mengetahui keberadaannya. Untuk melakukan ini, cukup buat katalog komponennya. Pedoman memberikan gambaran umum yang mudah ditemukan tentang semua komponen Anda. Ini membantu menjaga konsistensi visual dan menghindari pekerjaan berulang.

Alat-alat ini menyediakan cara mudah untuk melihat berbagai negara bagian. Sulit untuk mereproduksi setiap keadaan komponen dalam konteks aplikasi nyata. Daripada mengklik aplikasi sebenarnya, ada baiknya mengembangkan komponen terpisah. Status yang sulit dijangkau (seperti status pemuatan) dapat disimulasikan.

Seiring dengan demonstrasi visual dari berbagai keadaan dan daftar properti, seringkali perlu untuk menulis gambaran umum tentang konten - alasan desain, kasus penggunaan, atau deskripsi hasil pengujian pengguna. Penurunan harga sangat mudah dipelajari - idealnya, pedoman harus menjadi sumber daya bersama bagi desainer dan pengembang. Docz, Styleguidist, dan Storybook menawarkan cara untuk menggabungkan Markdown dengan komponen dengan mudah.

Dok

Saat ini Docz hanya bekerja dengan React, namun pekerjaan aktif sedang dilakukan untuk mendukung komponen Preact, Vue dan web. Docz adalah yang terbaru dari ketiga alat tersebut, tetapi telah berhasil mengumpulkan lebih dari 14 bintang di Github. Docz memperkenalkan dua komponen - <Playground> и < Props >. Mereka diimpor dan digunakan dalam 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>

Anda dapat membungkus komponen React Anda sendiri dengan <Playground>untuk membuat analog dari CodePen atau CodeSandbox bawaan - yaitu, Anda melihat komponen Anda dan dapat mengeditnya.

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

<Props> akan menampilkan semua properti yang tersedia untuk komponen React tertentu, nilai default, dan apakah properti tersebut diperlukan.

<Props of={Button} />

Secara pribadi, menurut saya pendekatan berbasis MDX ini adalah yang paling mudah dipahami dan paling mudah digunakan.

Jika Anda penggemar generator situs statis Gatsby, Docz menawarkan integrasi yang hebat.

Panduan gaya

Seperti Docz, contoh ditulis menggunakan sintaks Markdown. Styleguidist menggunakan blok kode penurunan harga (tanda kutip tiga) dalam file biasa .md file, bukan MDX.

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

Blok kode di Markdown biasanya hanya menampilkan kode. Saat menggunakan Styleguidist, blok kode apa pun dengan tag bahasa js, jsx или javascript akan dirender sebagai komponen React. Seperti Docz, kodenya dapat diedit - Anda dapat mengubah properti dan langsung melihat hasilnya.

Styleguidist akan secara otomatis membuat tabel properti dari deklarasi PropTypes, Flow, atau TypeScript.

Styleguidist saat ini mendukung React dan Vue.

Buku cerita

Storybook memposisikan dirinya sebagai “lingkungan pengembangan komponen UI.” Daripada menulis komponen contoh di dalam file Markdown atau MDX, Anda menulis cerita di dalam file Javascript. Cerita mendokumentasikan keadaan spesifik suatu komponen. Misalnya, sebuah komponen mungkin memiliki riwayat untuk status dimuat dan status nonaktif (cacat).

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

Buku Cerita jauh lebih kompleks daripada Styleguidist dan Docz. Namun pada saat yang sama, ini adalah opsi paling populer; proyek ini memiliki lebih dari 36 bintang di Github. Ini adalah proyek sumber terbuka dengan 000 kontributor dan staf penuh waktu. Ini digunakan oleh Airbnb, Algolia, Atlassian, Lyft, dan Salesforce. Storybook mendukung lebih banyak kerangka kerja dibandingkan kompetitor - React, React Native, Vue, Angular, Mithril, Ember, Riot, Svelte, dan HTML biasa.

Dalam rilis mendatang akan ada fitur dari Docz dan MDX yang akan diperkenalkan.

# Button

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

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

Fitur-fitur baru Storybook akan diluncurkan secara bertahap selama beberapa bulan ke depan dan sepertinya ini akan menjadi langkah maju yang besar.

Hasil

Manfaat perpustakaan pola dipuji dalam jutaan artikel di Medium. Jika dilakukan dengan baik, mereka akan mempermudah pembuatan produk terkait dan mempertahankan identitas. Tentu saja, tidak satu pun dari alat ini yang secara ajaib menciptakan sistem desain. Ini membutuhkan desain dan CSS yang cermat. Namun ketika tiba waktunya untuk membuat sistem desain dapat diakses oleh seluruh perusahaan, Docz, Storybook, dan Styleguidist adalah pilihan yang bagus.

Dari penerjemah. Ini adalah pengalaman pertama saya di Habré. Jika Anda menemukan ketidakakuratan, atau memiliki saran untuk memperbaiki artikel, tulislah kepada saya melalui pesan pribadi.

Sumber: www.habr.com