Mga giya sa kinabuhi - MDX ug uban pang mga gambalay

Mahimong adunay ka usa ka mas maayo nga open source nga proyekto, apan kung wala kini maayong dokumentasyon, lagmit nga dili kini mawala. Sa opisina, ang maayong dokumentasyon magpugong kanimo sa pagtubag sa parehas nga mga pangutana nga balik-balik. Gisiguro usab sa dokumentasyon nga masabtan sa mga tawo ang proyekto kung ang mga yawe nga empleyado mobiya sa kompanya o magbag-o ang mga tahas. Ang live nga mga giya makatabang sa pagsiguro sa integridad sa datos.

Kung kinahanglan nimo nga magsulat og taas nga teksto, ang Markdown usa ka maayong alternatibo sa HTML. Usahay ang Markdown syntax dili igo. Sa kini nga kaso, mahimo natong gamiton ang HTML sa sulod niini. Pananglitan, custom nga mga elemento. Busa, kung nagtukod ka usa ka sistema sa disenyo nga adunay lumad nga mga sangkap sa web, dali nga ilakip kini sa dokumentasyon sa teksto. Kung naggamit ka og React (o bisan unsang lain nga JSX framework sama sa Preact o Vue), mahimo nimo ang parehas sa MDX.

Kini nga artikulo usa ka halapad nga pagtan-aw sa mga himan alang sa pagsulat sa dokumentasyon ug paghimo og usa ka giya. Dili tanan nga mga himan nga gilista dinhi naggamit sa MDX, apan kini labi nga gilakip sa mga himan sa dokumentasyon.

Unsa ang MDX?

file .mdx adunay parehas nga syntax sa Markdown apan gitugotan ka sa pag-import sa mga interactive nga sangkap sa JSX ug i-embed kini sa imong sulud. Ang suporta alang sa mga sangkap sa Vue naa sa alpha. Aron makasugod sa pagtrabaho uban sa MDX, i-install lang ang "Create React App". Adunay mga plugins alang sa Next.js ug Gatsby. Ang sunod nga bersyon sa Docusaurus (bersyon 2) makabaton usab og built-in nga suporta.

Pagsulat og dokumentasyon gamit ang Docusaurus

Nagsulat si Docusaurus sa Facebook. Gigamit nila kini sa matag open source nga proyekto gawas sa React. Sa gawas sa kompanya, gigamit kini ni Redux, Prettier, Gulp, ug Babel.

Mga proyekto nga naggamit sa Docusaurus.

Ang Docusaurus mahimong gamiton sa pagsulat bisan unsa dokumentasyon, dili lang para sa paghulagway sa frontend. Kini adunay React sa ilawom sa hood, apan dili kinahanglan nga pamilyar ka niini aron magamit kini. Nagkinahanglan kini sa imong mga Markdown nga mga file, usa ka pinch sa magic ug maayo nga pagkahan-ay, pormat ug mabasa nga dokumentasyon nga adunay nindot nga disenyo andam na.

Imong makita ang default nga Docusaurus template sa Redux website.

Ang mga site nga gitukod gamit ang Docusaurus mahimo usab nga maglakip sa usa ka blog nga nakabase sa Markdown. Alang sa pag-highlight sa syntax, gilakip dayon ang Prism.js. Bisan pa sa kamatuoran nga ang Docusaurus nagpakita nga bag-o lang, giila kini nga labing kaayo nga himan sa 2018 sa StackShare.

Ubang mga Opsyon sa Paghimo sa Kontento

Ang Docusaurus espesipikong gidisenyo alang sa paghimo og dokumentasyon. Siyempre, adunay usa ka milyon ug usa ka paagi sa paghimo sa usa ka website - mahimo nimong i-deploy ang imong kaugalingon nga solusyon sa bisan unsang lengguwahe, CMS, o mogamit usa ka static nga site generator.

Pananglitan, ang dokumentasyon alang sa React, ang sistema sa disenyo sa IBM, Apollo, ug Ghost CMS naggamit sa Gatsby, usa ka static nga site generator nga sagad gigamit alang sa mga blog. Kung nagtrabaho ka sa Vue nan ang VuePress usa ka maayong kapilian alang kanimo. Ang laing kapilian mao ang paggamit sa generator nga gisulat sa Python - MkDocs. Kini bukas ug gi-configure sa usa ka YAML file. Ang GitBook usa usab ka maayong kapilian, apan kini libre lamang alang sa bukas ug dili komersyal nga mga koponan. Mahimo ka usab mag-upload sa mga mardown file gamit ang git ug magtrabaho kauban nila sa Github.

Component Documentation: Docz, Storybook ug Styleguidist

Mga panudlo, disenyo sa sistema, mga librarya sa sangkap, bisan unsa nga gusto nimo nga itawag kanila, kini nahimong popular kaayo karong bag-o. Ang pagtunga sa mga component frameworks sama sa React ug ang mga himan nga gihisgutan dinhi nagpaposible sa pagbag-o kanila gikan sa mga proyekto sa kakawangan ngadto sa mapuslanong mga himan.

Ang Storybook, Docz ug Styleguidist nagbuhat sa samang butang: ipakita ang mga interactive nga elemento ug idokumento ang ilang API. Ang usa ka proyekto mahimong adunay dosena o bisan gatosan nga mga sangkap, tanan adunay lainlaing mga estado ug istilo. Kung gusto nimo nga magamit pag-usab ang mga sangkap, kinahanglan mahibal-an sa mga tawo nga naglungtad kini. Aron mahimo kini, igo na ang pag-catalog sa mga sangkap. Ang mga panudlo naghatag usa ka dali nga pagpangita nga kinatibuk-ang panan-aw sa tanan nimo nga mga sangkap. Makatabang kini sa pagpadayon sa pagkamakanunayon sa biswal ug paglikay sa balik-balik nga trabaho.

Kini nga mga himan naghatag usa ka kombenyente nga paagi sa pagtan-aw sa lainlaing mga estado. Mahimong lisud ang pagkopya sa matag kahimtang sa usa ka sangkap sa konteksto sa usa ka tinuud nga aplikasyon. Imbis nga mag-klik sa aktuwal nga aplikasyon, angayan nga maghimo usa ka lahi nga sangkap. Posible nga mag-modelo sa mga estado nga lisud maabot (pananglitan, estado sa pagkarga).

Uban sa usa ka biswal nga demonstrasyon sa lainlaing mga estado ug usa ka lista sa mga kabtangan, kanunay nga kinahanglan nga isulat ang usa ka kinatibuk-ang paghulagway sa sulud - mga katarungan sa disenyo, mga kaso sa paggamit, o usa ka paghulagway sa mga resulta sa pagsulay sa gumagamit. Ang Markdown dali ra mahibal-an - labing maayo, ang mga panudlo kinahanglan nga usa ka gipaambit nga kapanguhaan alang sa mga tigdesinyo ug mga developer. Ang Docz, Styleguidist, ug Storybook nagtanyag usa ka paagi aron dali nga masagol ang Markdown sa mga sangkap.

Si Docz

Sa pagkakaron, nagtrabaho lang si Docz sa React, apan aktibong nagtrabaho sa suporta para sa Preact, Vue, ug mga sangkap sa web. Ang Docz mao ang pinakabag-o sa tulo ka mga himan, apan nakahimo sa pagkolekta sa sobra sa 14 ka bituon sa Github. Gipaila ni Docz ang duha ka sangkap − <Playground> и < Props >. Gi-import sila ug gigamit sa mga 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>

Mahimo nimong ibalot ang imong kaugalingon nga mga sangkap sa React <Playground>aron makahimo usa ka analogue sa built-in nga CodePen o CodeSandbox - nga mao, makita nimo ang imong sangkap ug mahimo nimo kini i-edit.

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

<Props> ipakita ang tanan nga magamit nga mga kabtangan alang sa gihatag nga sangkap sa React, mga default nga kantidad ug kung gikinahanglan ang kabtangan.

<Props of={Button} />

Sa personal, akong nakita nga kini nga nakabase sa MDX nga pamaagi mao ang labing dali masabtan ug labing kadali nga magamit.

Kung ikaw usa ka fan sa Gatsby's static site generator, ang Docz nagtanyag daghang mga panagsama.

estilo nga giya

Sama sa Docz, ang mga pananglitan gisulat gamit ang Markdown syntax. Ang Styleguidist naggamit sa Markdown code blocks (triple quotes) sa regular nga mga file .md mga file, dili sa MDX.

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

Ang mga bloke sa code sa Markdown kasagarang ipakita lang ang code. Kung gigamit ang Styleguidist, bisan unsang bloke sa code nga adunay tag sa pinulongan js, jsx o javascript i-render isip usa ka React component. Sama sa Docz, ang code ma-edit - mahimo nimong usbon ang mga kabtangan ug makita dayon ang resulta.

Ang Styleguidist awtomatik nga maghimo ug property sheet gikan sa PropTypes, Flow o Typescript nga mga deklarasyon.

Gisuportahan na karon sa Styleguidist ang React ug Vue.

Basahon sa istorya

Ang Storybook nagbayad sa kaugalingon isip usa ka "UI component development environment". Imbis nga isulat ang mga pananglitan sa sangkap sa sulod sa Markdown o MDX nga mga file, nagsulat ka mga istorya sulod sa Javascript files. История idokumento ang piho nga kahimtang sa usa ka sangkap. Pananglitan, ang usa ka component mahimong adunay mga kasaysayan alang sa usa ka loading state ug usa ka disabled state (baldado).

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

Ang libro sa istorya labi ka komplikado kaysa sa Styleguidist ug Docz. Apan sa samang higayon, kini ang labing popular nga kapilian, sa Github ang proyekto adunay labaw pa sa 36 ka bituon. Kini usa ka bukas nga gigikanan nga proyekto nga adunay 000 nga mga kontribyutor ug kauban nga kawani. Gigamit kini sa Airbnb, Algolia, Atlassian, Lyft ug Salesforce. Gisuportahan sa Storybook ang daghang mga framework kaysa sa kompetisyon - React, React Native, Vue, Angular, Mithril, Ember, Riot, Svelte, ug yano nga HTML.

Sa umaabot nga pagpagawas, adunay mga chips gikan sa Docz ug ang MDX gipaila.

# Button

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

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

Ang bag-ong mga feature sa Storybook anam-anam nga mogawas sa sunod nga pipila ka bulan, ug morag kini usa ka dakong lakang sa unahan.

Mga resulta

Ang mga benepisyo sa pattern nga librarya gidayeg sa minilyon nga mga artikulo sa Medium. Kung nahimo nga maayo, gipasayon ​​nila ang paghimo og mga produkto nga may kalabutan ug pagpadayon sa usa ka identidad. Siyempre, walay bisan usa niini nga mga himan ang makahimo og usa ka sistema sa disenyo. Nagkinahanglan kini og maampingong disenyo ug disenyo sa CSS. Apan kung moabut na ang panahon aron mahimo ang sistema sa disenyo nga magamit sa tibuuk nga kompanya, ang Docz, Storybook ug Styleguidist maayo nga kapilian.

Gikan sa usa ka tighubad. Kini ang akong una nga kasinatian sa Habré. Kung nakit-an nimo ang bisan unsang mga sayup, o adunay mga sugyot alang sa pagpaayo sa artikulo - pagsulat sa usa ka personal.

Source: www.habr.com