Smjernice za život - MDX i drugi okviri

Možda imate bolji projekat otvorenog koda, ali ako nema dobru dokumentaciju, velike su šanse da nikada neće uspjeti. U kancelariji će vas dobra dokumentacija spriječiti da stalno odgovarate na ista pitanja. Dokumentacija također osigurava da ljudi mogu razumjeti projekat ako ključni zaposleni napuste kompaniju ili se uloge promijene. Smjernice uživo pomažu u osiguravanju integriteta podataka.

Ako trebate pisati dug tekst, Markdown je odlična alternativa HTML-u. Ponekad Markdown sintaksa nije dovoljna. U ovom slučaju, možemo koristiti HTML unutar njega. Na primjer, prilagođeni elementi. Stoga, ako gradite sistem dizajna sa izvornim web komponentama, lako ih je uključiti u tekstualnu dokumentaciju. Ako koristite React (ili bilo koji drugi JSX framework kao što su Preact ili Vue), isto možete učiniti sa MDX-om.

Ovaj članak je širok pregled alata za pisanje dokumentacije i kreiranje smjernica. Ne koriste svi ovdje navedeni alati MDX, ali se on sve više uključuje u dokumentacijske alate.

Šta je MDX?

fajl .mdx ima istu sintaksu kao Markdown, ali vam omogućava da uvezete interaktivne JSX komponente i ugradite ih u svoj sadržaj. Podrška za Vue komponente je u alfa verziji. Da biste počeli raditi sa MDX-om, samo instalirajte "Create React App". Postoje dodaci za Next.js i Gatsby. Sljedeća verzija Docusaurusa (verzija 2) će također imati ugrađenu podršku.

Pisanje dokumentacije sa Docusaurusom

Napisao je Dokusaurus na Fejsbuku. Koriste ga na svim projektima otvorenog koda osim Reacta. Izvan kompanije ga koriste Redux, Prettier, Gulp i Babel.

Projekti koji koriste Docusaurus.

Docusaurus se može koristiti za pisanje bilo koji dokumentaciju, ne samo za opisivanje frontenda. Ima React ispod haube, ali ne morate biti upoznati s njim da biste ga koristili. Potrebne su vaše Markdown datoteke, prstohvat magije i dobro strukturirana, formatirana i čitljiva dokumentacija s prekrasnim dizajnom je spremna.

Zadani Docusaurus predložak možete vidjeti na Redux web stranici.

Web lokacije napravljene pomoću Docusaurus-a također mogu uključivati ​​blog zasnovan na Markdownu. Za isticanje sintakse, Prism.js je odmah uključen. Unatoč činjenici da se Docusaurus pojavio relativno nedavno, na StackShareu je prepoznat kao najbolji alat 2018.

Druge opcije za kreiranje sadržaja

Docusaurus je posebno dizajniran za kreiranje dokumentacije. Naravno, postoji milion i jedan način da napravite web stranicu - možete implementirati vlastito rješenje na bilo kojem jeziku, CMS-u ili koristiti statički generator web stranica.

Na primjer, dokumentacija za React, IBM dizajn sistem, Apollo i Ghost CMS koriste Gatsby, generator statičke stranice koji se često koristi za blogove. Ako radite sa Vue-om, onda je VuePress dobra opcija za vas. Druga opcija je korištenje generatora napisanog u Python-u - MkDocs. Otvoren je i konfigurisan sa jednom YAML datotekom. GitBook je također dobra opcija, ali je besplatan samo za otvorene i nekomercijalne timove. Također možete jednostavno otpremiti mardown datoteke koristeći git i raditi s njima na Githubu.

Dokumentacija komponenti: Docz, Storybook i Styleguidist

Smjernice, dizajn sistema, biblioteke komponenti, kako god da ih nazovete, postali su vrlo popularni u posljednje vrijeme. Pojava komponentnih okvira kao što je React i ovdje spomenuti alati omogućila je njihovu transformaciju iz ispraznih projekata u korisne alate.

Storybook, Docz i Styleguidist rade istu stvar: prikazuju interaktivne elemente i dokumentiraju njihov API. Projekat može imati desetine ili čak stotine komponenti, sve s različitim stanjima i stilovima. Ako želite da se komponente ponovo koriste, ljudi moraju znati da postoje. Da biste to učinili, dovoljno je katalogizirati komponente. Smjernice pružaju pregled svih vaših komponenti koji je lak za pretraživanje. Ovo pomaže u održavanju vizualne konzistentnosti i izbjegavanju ponavljanja rada.

Ovi alati pružaju zgodan način za pregled različitih stanja. Može biti teško replicirati svako stanje komponente u kontekstu stvarne aplikacije. Umjesto klikanja na stvarnu aplikaciju, vrijedi razviti zasebnu komponentu. Moguće je modelirati teško dostupna stanja (na primjer stanje učitavanja).

Uz vizuelnu demonstraciju različitih stanja i listu svojstava, često je potrebno napisati opšti opis sadržaja – obrazloženja dizajna, slučajeve upotrebe ili opis rezultata testiranja korisnika. Markdown je vrlo lako naučiti – u idealnom slučaju, smjernice bi trebale biti zajednički resurs za dizajnere i programere. Docz, Styleguidist i Storybook nude način za jednostavno miješanje Markdowna sa komponentama.

Docz

Trenutno, Docz radi samo sa React-om, ali aktivno radi na podršci za Preact, Vue i web komponente. Docz je najnoviji od tri alata, ali je uspio prikupiti preko 14 zvjezdica na Githubu. Docz uvodi dvije komponente − <Playground> и < Props >. Oni se uvoze i koriste u datotekama .mdx.

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

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

<Button>click</Button>

Možete umotati svoje React komponente <Playground>da kreirate analogni ugrađeni CodePen ili CodeSandbox - to jest, vidite svoju komponentu i možete je uređivati.

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

<Props> će prikazati sva dostupna svojstva za datu React komponentu, zadane vrijednosti i da li je svojstvo potrebno.

<Props of={Button} />

Lično, smatram da je ovaj pristup zasnovan na MDX-u najlakši za razumjeti i najlakši za rad.

Ako ste obožavatelj Gatsbyjevog generatora statičnih stranica, Docz nudi odlične integracije.

stilski vodič

Kao iu Doczu, primjeri su napisani korištenjem Markdown sintakse. Styleguidist koristi blokove koda Markdown (trostruki navodniki) u regularnim datotekama .md datoteke, ne u MDX.

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

Blokovi koda u Markdownu obično samo prikazuju kod. Kada koristite Styleguidist, bilo koji blok koda sa jezičkom oznakom js, jsx ili javascript će se prikazati kao React komponenta. Kao i Docz, kod se može uređivati ​​- možete promijeniti svojstva i odmah vidjeti rezultat.

Styleguidist će automatski kreirati listu svojstava iz deklaracija PropTypes, Flow ili Typescript.

Styleguidist sada podržava React i Vue.

Knjiga priča

Storybook se označuje kao "okruženje za razvoj komponenti korisničkog sučelja". Umjesto da pišete primjere komponenti unutar Markdown ili MDX datoteka, vi pišete istorija unutar Javascript fajlova. История dokumentirati specifično stanje komponente. Na primjer, komponenta može imati historije za stanje učitavanja i onemogućeno stanje (onemogućeno).

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

Knjiga priča je mnogo složenija od Styleguidista i Docza. Ali u isto vrijeme, ovo je najpopularnija opcija, na Githubu projekt ima više od 36 zvjezdica. Ovo je projekat otvorenog koda sa 000 saradnika i pratnjom osoblja. Koriste ga Airbnb, Algolia, Atlassian, Lyft i Salesforce. Storybook podržava više okvira od konkurencije - React, React Native, Vue, Angular, Mithril, Ember, Riot, Svelte i običan HTML.

U budućem izdanju, bit će čipovi iz Docz-a i MDX je uveden.

# Button

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

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

Nove funkcije Storybook-a će se postepeno uvoditi u narednih nekoliko mjeseci i čini se da će to biti veliki korak naprijed.

Ishodi

Prednosti biblioteke šablona su pohvaljene u milionima članaka na Medium-u. Kada se urade dobro, olakšavaju kreiranje povezanih proizvoda i održavanje identiteta. Naravno, nijedan od ovih alata neće magično stvoriti sistem dizajna. Ovo zahtijeva pažljiv dizajn i CSS dizajn. Ali kada dođe vrijeme da se sistem dizajna učini dostupnim cijeloj kompaniji, Docz, Storybook i Styleguidist su odlične opcije.

Od prevodioca. Ovo je moje prvo iskustvo na Habréu. Ako nađete bilo kakve netočnosti, ili imate prijedloge za poboljšanje članka - pišite u osobno.

izvor: www.habr.com