🥇Ghiduri interactive — MDX și alte framework-uri

Puteți avea cel mai bun proiect open-source, dar dacă nu are o documentație bună, există șanse mari să nu decoleze niciodată. O documentație bine concepută în birou vă va ajuta să nu răspundeți la aceleași întrebări din nou și din nou. Documentația garantează, de asemenea, că oamenii pot înțelege proiectul dacă angajații cheie părăsesc compania sau dacă rolurile se schimbă. Ghidurile interactive vor ajuta la asigurarea integrității datelor.

Dacă trebuie să scrieți un text lung, Markdown este o alternativă excelentă la HTML. Uneori, sintaxa Markdown nu este suficientă. În acest caz, putem folosi HTML în interiorul său. De exemplu, elemente personalizate. Așadar, dacă construiți un sistem de design cu componente web native, aceste componente pot fi ușor incluse în documentația textuală. Dacă utilizați React (sau orice alt cadru JSX, cum ar fi Preact sau Vue), puteți face același lucru folosind MDX.

Acest articol este o prezentare generală amplă a instrumentelor pentru scrierea documentației și crearea de ghiduri. Nu toate instrumentele enumerate aici folosesc MDX, dar acesta este din ce în ce mai frecvent integrat în instrumentele de documentare.

Ce este MDX?

Fișier .mdx are aceeași sintaxă ca Markdown, dar permite importarea componentelor JSX interactive și încorporarea lor în conținutul dumneavoastră. Suportul pentru componentele Vue este în faza alfa. Pentru a începe să lucrați cu MDX, este suficient să instalați „Create React App”. Există pluginuri pentru Next.js și Gatsby. Următoarea versiune Docusaurus (versiunea 2) va avea, de asemenea, suport încorporat.

Scrierea documentației cu Docusaurus

Docusaurus a fost creat de Facebook. Aceștia îl folosesc pentru fiecare proiect open-source, cu excepția React. În afara companiei, este utilizat de Redux, Prettier, Gulp și Babel.

Proiecte care folosesc Docusaurus.

Docusaurus poate fi folosit pentru scrierea oricine documentației, nu doar pentru descrierea frontend-ului. Sub capotă are React, dar nu este necesar să îl cunoașteți pentru a-l folosi. El preia fișierele dumneavoastră Markdown, cu o mică magie, și documentația bine structurată, formatată și ușor de citit cu un design frumos este gata.

Pe site-ul Redux puteți consulta șablonul standard Docusaurus

Site-urile create cu Docusaurus pot include, de asemenea, un blog bazat pe Markdown. Pentru evidențierea sintaxei, Prism.js este deja integrat. Deși Docusaurus a apărut relativ recent, a fost recunoscut ca fiind cel mai bun instrument din 2018 pe StackShare.

Alte opțiuni pentru crearea de conținut

Docusaurus este special conceput pentru a crea documentație. Sigur, există milioane de modalități de a face un site — puteți implementa propria soluție în orice limbă, CMS sau utiliza un generator de site-uri statice.

De exemplu, documentația pentru React, sistemul de design IBM, Apollo și Ghost CMS folosesc Gatsby — un generator de site-uri statice care este adesea folosit pentru bloguri. Dacă lucrați cu Vue, VuePress va fi o opțiune bună pentru dumneavoastră. O altă opțiune este să folosiți un generator scris în Python — MkDocs. Acesta este deschis și se configurează cu ajutorul unui singur fișier YAML. GitBook este de asemenea o opțiune decentă, dar este gratuit doar pentru echipele deschise și non-profit. De asemenea, puteți pur și simplu să încărcați fișiere Markdown folosind Git și să lucrați cu ele în Github.

Documentarea componentelor: Docz, Storybook și Styleguidist

Guideline-urile, sistemele de design, bibliotecile de componente — indiferent de cum le numiți, acestea au devenit foarte populare în ultima vreme. Apariția cadrelor de componente, cum ar fi React și uneltele menționate aici — a transformat aceste proiecte din lucruri vanitoase în instrumente utile.

Storybook, Docz și Styleguidist — fac același lucru: afișează elemente interactive și documentează API-urile acestora. Un proiect poate avea zeci sau chiar sute de componente — toate cu diverse stări și stiluri. Dacă doriți ca componentele să fie reutilizate, oamenii trebuie să știe că ele există. Este suficient să catalogizați componentele. Guideline-urile oferă o privire de ansamblu ușor de căutat asupra tuturor componentelor dvs. Acest lucru ajută la menținerea coerenței vizuale și la evitarea muncii redundante.

Aceste unelte oferă o modalitate convenabilă de a vizualiza diverse stări. Poate fi dificil să reproduceți fiecare stare a unei componente în contextul unei aplicații reale. În loc să faceți clic pe o aplicație reală, este mai bine să dezvoltați o componentă separată. Puteți modela stări greu accesibile (de exemplu, starea de încărcare).

Împreună cu demonstrarea vizuală a diferitelor stări și lista de proprietăți, este adesea necesar să scriem o descriere generală a conținutului — justificarea designului, cazurile de utilizare sau descrierea rezultatelor testării utilizatorilor. Markdown este foarte ușor de învățat — ideal, ghidurile ar trebui să fie o resursă comună pentru designeri și dezvoltatori. Docz, Styleguidist și Storybook oferă o modalitate ușoară de a amesteca Markdown cu componente.

Docz

În prezent, Docz funcționează doar cu React, dar se lucrează activ la sprijinul pentru Preact, Vue și componente web. Docz este cel mai nou dintre cele trei instrumente, dar pe Github a reușit să adune peste 14.000 de stele. Docz prezintă două componente — <Playground> și < Props >. Acestea sunt importate și folosite în fișiere .mdx.

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

## Poți _scrie_ **markdown**
### Poți importa și folosi componente

Poți învălui propriile componente React folosind <Playground>, pentru a crea un analog al CodePen sau CodeSandbox — adică vezi componenta ta și o poți edita.

<Props> va arăta toate proprietățile disponibile pentru componenta React respectivă, valorile implicite și dacă o proprietate este necesară.

<Props of={Button} />

Personal, consider că această abordare bazată pe MDX este cea mai ușor de înțeles și cea mai simplă de utilizat.

Dacă ești fan al generatorului de site-uri statice Gatsby, Docz oferă o integrare excelentă.

Styleguidist

Ca și în Docz, exemplele sunt scrise folosind sintaxa Markdown. Styleguidist folosește blocuri de cod Markdown (cotele triple) în fișierele obișnuite .md în loc de MDX.

```js

Blocurile de cod în Markdown arată de obicei codul. Atunci când folosești Styleguidist, orice bloc de cod cu eticheta limbajului js, jsx sau javascript va fi afișat ca o componentă React. Ca și în Docz, codul este editabil — poți schimba proprietățile și vezi instantaneu rezultatul.

Styleguidist va crea automat o tabelă de proprietăți din declaratiile PropTypes, Flow sau Typescript.

Styleguidist acceptă acum React și Vue.

Storybook

Storybook se poziționează ca „un mediu de dezvoltare a componentelor UI”. În loc să scrii exemple de componente în fișiere Markdown sau MDX, scrii povești în fișiere Javascript. Istoria documentează o stare specifică a componentului. De exemplu, o componentă poate avea istorii pentru starea de încărcare și starea dezactivată (dezactivat).

storiesOf('Button', module)
  .add('dezactivat', () => (
    
  ))

Storybook este mult mai complicat decât Styleguidist și Docz. Totuși, este cea mai populară opțiune, având peste 36.000 de stele pe Github. Acesta este un proiect open-source, cu 657 de participanți și întreținut de angajați permanenți. Este utilizat de Airbnb, Algolia, Atlassian, Lyft și Salesforce. Storybook suportă mai multe framework-uri decât competitorii săi — React, React Native, Vue, Angular, Mithril, Ember, Riot, Svelte și HTML obișnuit.

În următoarea versiune vor fi caracteristici din Docz și se va implementa MDX.

# Button

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

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

Noile funcționalități ale Storybook-ului vor apărea treptat în următoarele câteva luni și, aparent, aceasta va fi o mare avansare.

Concluzii

Avantajele bibliotecii de pattern-uri sunt lăudate în milioane de articole pe Medium. Când totul este făcut bine, acestea facilitează crearea produselor înrudite și menținerea identității. Desigur, niciunul dintre aceste instrumente nu poate ajuta ca prin magie în crearea unui sistem de design. Acesta necesită o proiectare atentă a designului și CSS-ului. Dar când vine momentul de a face sistemul de design accesibil întregii companii, Docz, Storybook și Styleguidist sunt opțiuni excelente.

De la translator. Aceasta este prima mea experiență pe Habr. Dacă ați găsit vreo inexactitate sau aveți sugestii pentru îmbunătățirea articolului — scrieți-mi în privat.

Sursa: habr.com