Linee di vita - MDX è altri quadri

Pudete avè u megliu prughjettu open source, ma s'ellu ùn hà micca una bona ducumentazione, a probabilità hè chì ùn si sparghjerà mai. In l'uffiziu, una bona documentazione vi impediscenu di risponde à e stesse dumande. A ducumentazione assicura ancu chì a ghjente pò capisce u prugettu se l'impiegati chjave lascianu a cumpagnia o cambianu i roli. E linee viventi aiutanu à assicurà l'integrità di e dati.

Sè avete bisognu di scrive un testu longu, Markdown hè una grande alternativa à HTML. Calchì volta a sintassi Markdown ùn hè micca abbastanza. In questu casu, pudemu usà HTML in ellu. Per esempiu, elementi persunalizati. Dunque, sè vo site un sistema di cuncepimentu cù cumpunenti web nativi, ponu esse facilmente inclusi in a documentazione di testu. Sè vo aduprate React (o qualsiasi altru framework JSX cum'è Preact o Vue), pudete fà a stessa cosa cù MDX.

Questu articulu hè una panoramica larga di l'arnesi per scrive documentazione è creà linee guida. Micca tutti l'arnesi elencati quì utilizanu MDX, ma hè sempre più inclusu in l'arnesi di documentazione.

Cosa hè MDX?

u schedariu .mdx hà a listessa sintassi cum'è Markdown, ma permette di impurtà cumpunenti interattivi JSX è incrustà in u vostru cuntenutu. U supportu per i cumpunenti Vue hè in alfa. Per cumincià à travaglià cù MDX, basta à stallà "Create React App". Ci sò plugins per Next.js è Gatsby. A prossima versione di Docusaurus (versione 2) averà ancu supportu nativu.

Scrittura di documentazione cù Docusaurus

Docusaurus hà scrittu annantu à Facebook. L'utilizanu in ogni prughjettu open source eccettu React. Fora di a cumpagnia hè utilizatu da Redux, Prettier, Gulp è Babel.

Prughjetti chì utilizanu Docusaurus.

Docusaurus pò esse usatu per scrive qualchissia documentazione, micca solu per discrive u frontend. Hà React sottu u cappucciu, ma ùn avete micca esse familiarizatu per aduprà. Piglia i vostri fugliali Markdown, un pizzicu di magia è una documentazione ben strutturata, furmatu è leggibile cù un bellu disignu hè pronta.

In u situ Redux pudete vede u mudellu standard di Docusaurus

I siti web custruiti cù Docusaurus ponu ancu include un blog basatu in Markdown. Prism.js hè immediatamente cunnessu per l'evidenziazione di sintassi. Malgradu u fattu chì Docusaurus hè apparsu pocu pocu tempu, hè statu ricunnisciutu cum'è u megliu strumentu di 2018 in StackShare.

Altre opzioni di creazione di cuntenutu

Docusaurus hè specificamente cuncepitu per creà documentazione. Di sicuru, ci sò un milione è una manera di fà un situ web - pudete implementà a vostra propria suluzione in ogni lingua, CMS, o utilizate un generatore di situ staticu.

Per esempiu, a documentazione per React, u sistema di design IBM, Apollo è Ghost CMS utilizanu Gatsby - un generatore di situ staticu chì hè spessu usatu per i blog. Sè vo travaglià cù Vue, tandu VuePress hè una bona opzione per voi. Un'altra opzione hè di utilizà un generatore scrittu in Python - MkDocs. Hè open source è cunfiguratu cù un unicu schedariu YAML. GitBook hè ancu una bona opzione, ma hè solu gratuitu per i gruppi publichi è micca cummerciale. Pudete ancu caricà i fugliali mardown cù Git è travaglià cun elli in Github.

Cumpunenti di documentazione: Docz, Storybook è Styleguidist

Linee guida, cuncepimentu di u sistema, biblioteche di cumpunenti - ciò chì chjamate, hè diventatu assai populari ultimamente. L'avventu di frameworks cumpunenti cum'è React è l'arnesi citati quì anu trasfurmatu da prughjetti di vanità in strumenti utili.

Storybook, Docz è Styleguidist facenu tutti a stessa cosa: mostra elementi interattivi è documentà a so API. Un prughjettu pò avè decine o ancu centinaie di cumpunenti - tutti cù diversi stati è stili. Se vulete chì i cumpunenti sò riutilizzati, a ghjente hà bisognu di sapè chì esistenu. Per fà questu, basta à catalogà i cumpunenti. Guidelines furnisce una panoramica faciule da truvà di tutti i vostri cumpunenti. Questu aiuta à mantene a cunsistenza visuale è evite u travagliu ripetitivu.

Questi strumenti furniscenu un modu convenientu per vede diverse stati. Pò esse difficiule di ripruduce ogni statu di un cumpunente in u cuntestu di una vera applicazione. Invece di cliccà nantu à l'applicazione attuale, vale a pena sviluppà un cumpunente separatu. I stati difficiuli di ghjunghje (cum'è stati di carica) ponu esse simulati.

Inseme cù una manifestazione visuale di diversi stati è una lista di pruprietà, hè spessu necessariu di scrive una descrizzione generale di u cuntenutu - ragiuni di cuncepimentu, casi d'usu, o descrizzioni di i risultati di teste d'utilizatori. Markdown hè assai faciule d'amparà - idealmente, e linee guida deve esse una risorsa cumuna per i diseggiani è i sviluppatori. Docz, Styleguidist è Storybook offrenu un modu per mischjà facilmente Markdown cù cumpunenti.

Docz

Attualmente Docz travaglia solu cù React, ma u travagliu attivu hè in corso per sustene Preact, Vue è cumpunenti web. Docz hè u più recente di i trè strumenti, ma hà sappiutu cullà più di 14 stelle in Github. Docz introduce dui cumpunenti - <Playground> и < Props >. Sò impurtati è usati in i schedari .mdx.

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

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

<Button>click</Button>

Pudete imballà i vostri cumpunenti React cù <Playground>per creà un analogu di u CodePen o CodeSandbox integratu - vale à dì, vede u vostru cumpunente è pudete edità.

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

<Props> mostrarà tutte e proprietà dispunibili per un cumpunente React, i valori predeterminati, è se a pruprietà hè necessaria.

<Props of={Button} />

In modu persunale, mi pare chì questu approcciu basatu in MDX hè u più faciule da capisce è u più faciule per travaglià.

Sè vo site un fan di u generatore di situ staticu Gatsby, Docz offre una grande integrazione.

Guida di stile

Cum'è Docz, l'esempii sò scritti cù a sintassi Markdown. Styleguidist usa i blocchi di codice Markdown (virgole triple) in i schedarii regulari .md i schedari, micca MDX.

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

I blocchi di codice in Markdown di solitu mostranu solu u codice. Quandu si usa Styleguidist, ogni bloccu di codice cù una tag di lingua js, jsx o javascript renderà cum'è un cumpunente React. Cum'è Docz, u codice hè editable - pudete cambià e proprietà è vede istantaneamente u risultatu.

Styleguidist creà automaticamente una tabella di pruprietà da dichjarazioni PropTypes, Flow o Typescript.

Styleguidist supporta attualmente React è Vue.

Libru di Storie

Storybook si pone cum'è un "ambiente di sviluppu di cumpunenti UI". Invece di scrive cumpunenti di esempiu in i schedari Markdown o MDX, scrivite stori in i schedari Javascript. История documentu u statu specificu di un cumpunente. Per esempiu, un cumpunente puderia avè storie per un statu caricatu è un statu disattivatu (disabilitatu).

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

Storybook hè assai più cumplessu di Styleguidist è Docz. Ma à u stessu tempu, questa hè l'opzione più pupulare; u prughjettu hà più di 36 000 stelle in Github. Hè un prughjettu open source cù 657 cuntributori è persunale full-time. Hè utilizatu da Airbnb, Algolia, Atlassian, Lyft è Salesforce. Storybook supporta più frameworks cà i cuncurrenti - React, React Native, Vue, Angular, Mithril, Ember, Riot, Svelte è HTML regular.

In una futura versione ci saranu caratteristiche da Docz è MDX seranu introdutte.

# Button

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

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

E novi funzioni di Storybook si sparghjeranu gradualmente in i prossimi mesi è pare chì serà un grande passu avanti.

Risultati

I benefici di una biblioteca di mudelli sò esaltati in milioni d'articuli nantu à Medium. Quandu sò fatti bè, facenu più faciule per creà prudutti cunnessi è mantene l'identità. Di sicuru, nimu di sti strumenti magicamente creà un sistema di disignu. Questu hè bisognu di cuncepimentu attentu è CSS. Ma quandu vene u tempu di rende un sistema di cuncepimentu accessibile à tutta a cumpagnia, Docz, Storybook è Styleguidist sò grandi opzioni.

Da u traduttore. Questa hè a mo prima sperienza nantu à Habré. Sè truvate ogni imprecisione, o avete suggerimenti per migliurà l'articulu, scrivitemi in un missaghju persunale.

Source: www.habr.com