Elavad juhised — MDX ja muud raamistikke

Teie projekt võib olla parim avatud koodiga, kuid kui sellel puudub korralik dokumentatsioon, on tõenäoline, et see ei õnnestu kunagi. Head dokumentatsioon büroos aitab vältida sama küsimuse korduvat esitamist. Dokumentatsioon tagab ka, et inimesed saavad projektiga hakkama, isegi kui võtmemängijad lahkuvad ettevõttest või rollid muutuvad. Elavad juhised aitavad andmete terviklikkust tagada.

Kui peate kirjutama pika teksti, on Markdown suurepärane alternatiiv HTML-ile. Mõnikord ei piisa markdowni süntaksist. Sel juhul saame selle sees kasutada HTML-i. Näiteks kohandatud elemendid. Seega, kui ehitate disainisüsteemi kohalike veebikomponentidega, on neid lihtne lisada tekstidokumentatsiooni. Kui kasutate Reacti (või mõnda muud JSX raamistiku, nagu Preact või Vue), saate sama teha MDX abil.

See artikkel on ulatuslik ülevaade dokumentatsioonitööriistadest ja juhiste koostamisest. Mitte kõik siin loetletud tööriistad ei kasuta MDX-i, kuid see lisandub üha sagedamini dokumenteerimistööriistadesse.

Mis on MDX?

File .mdx MDX'il on sama süntaks nagu Markdown, kuid see võimaldab importida interaktiivseid JSX komponente ja lisada need teie sisusse. Vue komponentide toetus on alfa-etapis. MDX-iga alustamiseks piisab, kui installida 'Create React App'. On pluginaid Next.js ja Gatsby jaoks. Järgmine Docusaurus versioon (versioon 2) sisaldab ka sisseehitatud tuge.

Dokumentatsiooni kirjutamine Docusaurus'e abil

Docusaurus'e on kirjutanud Facebook. Nad kasutavad seda igas avatud lähtekoodiga projektis, välja arvatud React'i puhul. Väljaspoole ettevõtte kasutatakse seda Redux'i, Prettier'i, Gulp'i ja Babel'i jaoks.

Projektid, mis kasutavad Docusaurus'e.

Docusaurus'e saab kasutada mitte ainult dokumentatsiooni alusena igaühe , vaid ka frontendi kirjeldamiseks. Selle all on React, kuid selle kasutamiseks ei ole tingimata vaja sellega tuttav olla. See võtab teie Markdown failid, veidi maagiat ja korralik, hästi struktureeritud ning loetav dokumentatsioon kauni disainiga on valmis.

Redux'i saidil saab vaadata Docusaurus'e standardset mall.

Docusaurusega loodud saidid võivad sisaldada ka Markdown-põhist päeva. Sünktaksisoni esitlemiseks on kohe ühendatud Prism.js. Kuigi Docusaurus ilmus suhteliselt hiljuti, tunnustati seda 2018. aasta parimaks tööriistaks StackShare'il.

Teised sisu loomise võimalused

Docusaurus on spetsiaalselt välja töötatud dokumentatsiooni loomiseks. Loomulikult on olemas miljon ja üks viis saidi loomiseks — võite installida oma lahenduse mis tahes keeles, CMS-is või kasutada staatilise saidi generaatorit.

Näiteks kasutavad Reacti dokumentatsioon, IBM-i disainisüsteem, Apollo ja Ghost CMS Gatsby't — see on staatiliste veebisaitide generaator, mida sageli kasutatakse blogide jaoks. Kui töötate Vue'iga, on VuePress teile hea variant. Teine võimalus on kasutada Pythonis kirjutatud generaatorit — MkDocs. See on avatud ja konfigureeritav ühe YAML-faili kaudu. GitBook on samuti hea variant, kuid see on tasuta ainult avatud ja mittekaubanduslikele meeskondadele. Veel võite lihtsalt laadida mmarkdown-faile, kasutades giti, ja töötada nendega GitHubis.

Komponentide dokumenteerimine: Docz, Storybook ja Styleguidist

Guidelines, disainisüsteemid, komponente teegid — olenemata sellest, kuidas te neid nimetate, on need viimase ajal väga populaarsed. Komponentide raamistikud, näiteks React, ja siinkohal mainitud tööriistad on võimaldanud neid tuua uhkete projektide seast kasulikeks tööriistadeks.

Storybook, Docz ja Styleguidist teevad ühte ja sama: nad kuvavad interaktiivseid komponente ja dokumenteerivad nende API. Projekt võib sisaldada kümneid või isegi sadu komponente — kõik erinevate olekute ja stiilidega. Kui te soovite, et komponente kasutataks uuesti, peavad inimesed teadma, et need eksisteerivad. Selleks piisab komponentide katalogiseerimisest. Güdde lainid pakuvad hõlpsasti otsitavat ülevaadet kõigist teie komponentidest. See aitab säilitada visuaalset konsistentsi ja vältida korduvat tööd.

Need to know all of your application's states quickly? These tools provide a convenient way to view various states. It can be challenging to recreate every component state in the context of a real application. Instead of clicking through a real app, it's worth developing a separate component. You can simulate hard-to-reach states (like loading state).

In addition to visually demonstrating different states and listing properties, it’s often necessary to write a general description of the content — design rationales, use cases, or results from user testing. Markdown is very easy to learn — ideally, the guidelines should be a collaborative resource for designers and developers. Docz, Styleguidist, and Storybook offer a way to easily mix Markdown with components.

Docz

Currently, Docz only works with React, but active efforts are underway to support Preact, Vue, and web components. Docz is the freshest of the three tools, yet it has managed to gather over 14,000 stars on GitHub. Docz features two components — <Playground> ja < Props >. They are imported and used in files. .mdx.

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

## Saate _kirjutada_ **markdown**
### Saate importida ja kasutada komponente

kliki

Saate oma React-komponente ümber mähkida, et <Playground>, et luua sarnane sisseehitatud CodePen või CodeSandbox - see tähendab, et näete oma komponenti ja saate seda redigeerida.

kliki

<Props> näitab kõiki saadaval olevaid omadusi antud React-komponendi jaoks, vaikimisi väärtusi ja seda, kas omadus on vajalik.

<Props of={Button} />

Isiklikult arvan, et see MDX-põhine lähenemine on kõige arusaadavam ja lihtsaim, millega töötada.

Kui olete Gatsby staatiliste veebisaitide generaatori fänn, siis Docz pakub suurepärast integreerimist.

Styleguidist

Nagu Dokz'is, kirjutatakse näidendid markdown-süntaksit kasutades. Styleguidist kasutab Markdowni koodiblokke (kolm tsitaati) tavalisetes failides, .md mitte MDX-is.

```js
 console.log('clicked')}>Push Me

Markdownis olevad koodiblokid näitavad tavaliselt lihtsalt koodi. Styleguidist'i puhul kuvatakse iga koodiblokki, millel on keele silt, js, jsx või javascript React-komponendina. Nagu Docz'is, on kood redigeeritav — saate omadusi muuta ja kohe tulemusi näha.

Styleguidist loob automaatselt omaduste tabeli PropTypes, Flow või Typescripti kuulutustest.

Styleguidist toetab nüüd Reacti ja Vue'i.

Storybook

Storybook positsioneerib end kui "UI komponentide arenduskeskkond". Selle asemel, et kirjutada komponentide näiteid Markdowni või MDX failide sees, kirjutate lood JavaScripti failide sisse. Ajalugu dokumendid konkreetse komponendi olekut. Näiteks võib komponendil olla lugemisolekuga ja keelatud seisundiga lood (disabled).

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

Storybook on tunduvalt keerulisem kui Styleguidist ja Docz. Küll aga on see kõige populaarsem valik, millel on GitHubis üle 36 000 tähe. See on avatud lähtekoodiga projekt, milles osaleb 657 osalist ja hooldab seda ametlik personal. Seda kasutavad Airbnb, Algolia, Atlassian, Lyft ja Salesforce. Storybook toetab rohkem raamistikku kui konkurendid — React, React Native, Vue, Angular, Mithril, Ember, Riot, Svelte ja tavaline HTML.

Järgmises väljaandes on funktsioonid Docz-st ning MDX integreeritakse.

# Button

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

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

Uued Storybooki funktsioonid lisanduvad järk-järgult järgmise paari kuu jooksul ja need näivad olevat suur samm edasi.

Kokkuvõte

Mustrikogud on tuvastatud miljonites artiklites Mediumis. Kui kõik on õigesti tehtud, lihtsustavad nad seotud toodete loomist ning identiteedi hoidmist. Loomulikult ei aita ükski neist tööriistadest maagiliselt luua disainisüsteemi. See nõuab meie disaini ja CSS-i põhjalikku planeerimist. Kuid kui aeg on disainisüsteem kogu ettevõttele kergesti kättesaadavaks muuta, on Docz, Storybook ja Styleguidist suurepärased valikud.

Tõlkijalt. See on minu esimene kogemus Habras. Kui leiate mõningaid ebatäpsusi või teil on ettepanekuid artikli parandamiseks — kirjuta mulle isikliku sõnumiga.

Allikas: habr.com