🥇Levande riktlinjer — MDX och andra ramverk

Du kan ha det bästa projektet med öppen källkod, men om det inte finns bra dokumentation finns det en risk att det aldrig får fart. God dokumentation på kontoret gör att du slipper svara på samma frågor om och om igen. Dokumentationen säkerställer också att människor kan förstå projektet om nyckelpersoner lämnar företaget eller roller ändras. Levande riktlinjer hjälper till att säkerställa dataintegritet.

Om du behöver skriva en lång text är Markdown ett utmärkt alternativ till HTML. Ibland räcker inte Markdown-syntaxen till. I så fall kan vi använda HTML inuti den. Till exempel anpassade element. Om du bygger ett designsystem med inbyggda webbkomponenter är det enkelt att inkludera dem i dokumenttexten. Om du använder React (eller något annat JSX-ramverk, som Preact eller Vue), kan du göra samma sak med MDX.

Denna artikel är en översikt över verktyg för att skriva dokumentation och skapa riktlinjer. Inte alla verktyg som nämns här använder MDX, men det blir alltmer vanligt i dokumentationsverktyg.

Vad är MDX?

Fil .mdx har samma syntax som Markdown, men tillåter import av interaktiva JSX-komponenter och att de bäddas in i ditt innehåll. Stöd för Vue-komponenter är fortfarande i alfa. För att börja använda MDX räcker det att installera 'Create React App'. Det finns plugins för Next.js och Gatsby. Nästa version av Docusaurus (version 2) kommer också ha inbyggt stöd.

Skriva dokumentation med Docusaurus

Docusaurus skapades av Facebook. De använder det i varje projekt med öppen källkod, utom för React. Utanför företaget används det av Redux, Prettier, Gulp och Babel.

Projekt som använder Docusaurus.

Docusaurus kan användas för att skriva någon dokumentation, inte bara för att beskriva frontend. Den bygger på React, men för att använda den behöver du inte vara bekant med den. Den tar dina Markdown-filer, en gnutta magi och så är välstrukturerad, formaterad och läsbar dokumentation med vacker design klar.

På Redux-webbplatsen kan du se den standardmall som Docusaurus använder.

Webbplatser som skapats med Docusaurus kan även inkludera en blogg baserad på Markdown. För syntaxmarkering är Prism.js direkt integrerat. Trots att Docusaurus är relativt nytt har det erkänds som det bästa verktyget 2018 på StackShare.

Andra alternativ för att skapa innehåll

Docusaurus är speciellt utformat för att skapa dokumentation. Självklart finns det miljoner sätt att skapa en webbplats — du kan driftsätta din egen lösning i valfritt språk, CMS eller använda en statisk webbplatsgenerator.

Till exempel använder dokumentationen för React, design systemet IBM, Apollo och Ghost CMS Gatsby — en statisk webbplatsgenerator som ofta används för bloggar. Om du arbetar med Vue kan VuePress vara ett bra alternativ för dig. Ett annat alternativ är att använda en generator skriven i Python — MkDocs. Den är öppen och konfigureras med en enda YAML-fil. GitBook är också ett bra alternativ, men det är gratis endast för öppna och ideella team. Du kan även helt enkelt ladda upp Markdown-filer med hjälp av git och arbeta med dem i GitHub.

Dokumentera komponenter: Docz, Storybook och Styleguidist

Riktlinjer, designsystem, komponentbibliotek — vad du än kallar dem, så har de blivit mycket populära på sistone. Framväxten av komponentramverk som React och verktygen som nämns här har möjliggjort att de kan omvandlas från fåfänga projekt till användbara verktyg.

Storybook, Docz och Styleguidist gör i princip samma sak: de visar interaktivaelement och dokumenterar deras API. Ett projekt kan ha tiotals eller till och med hundratals komponenter — alla med olika tillstånd och stilar. Om du vill att komponenterna ska återanvändas, måste människor veta att de finns. För det räcker det med att katalogisera komponenterna. Riktlinjer ger en lättillgänglig översikt över alla dina komponenter. Detta hjälper till att upprätthålla visuell konsekvens och undvika duplicerat arbete.

Dessa verktyg erbjuder ett bekvämt sätt att visa olika tillstånd. Det kan vara svårt att återskapa varje komponenttillstånd i kontexten av en verklig applikation. Istället för att klicka kring i en verklig applikation är det bättre att utveckla en separat komponent. Du kan modellera svåråtkomliga tillstånd (t.ex. laddningstillstånd).

I takt med den visuella visningen av olika tillstånd och en lista över egenskaper är det ofta nödvändigt att skriva en allmän beskrivning av innehållet — designmotiveringar, användningsfall eller beskrivningar av resultat från användartester. Markdown är mycket enkelt att lära sig — idealiskt sett bör riktlinjer vara en gemensam resurs för designers och utvecklare. Docz, Styleguidist och Storybook erbjuder ett sätt att enkelt blanda Markdown med komponenter.

Docz

Just nu fungerar Docz endast med React, men arbete pågår aktivt för att stödja Preact, Vue och webbkomponenter. Docz är det senaste av de tre verktygen, men har samlat mer än 14 000 stjärnor på Github. Docz presenterar två komponenter — <Playground> och < Props >. De importeras och används i filer .mdx.

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

## Du kan _skriva_ **markdown**
### Du kan importera och använda komponenter

Du kan svepa dina egna React-komponenter med hjälp av <Playground>, för att skapa en analog av inbyggda CodePen eller CodeSandbox — det vill säga att du ser din komponent och kan redigera den.

<Props> visar alla tillgängliga egenskaper för denna React-komponent, standardvärden och om egenskapen är nödvändig.

<Props of={Button} />

Personligen anser jag att detta MDX-baserade tillvägagångssätt är det lättaste att förstå och det enklaste att arbeta med.

Om du är ett fan av den statiska webbplatsgeneratorn Gatsby, erbjuder Docz utmärkt integration.

Styleguidist

Precis som i Docz skrivs exempel med Markdown-syntax. Styleguidist använder Markdown-kodblock (tre citattecken) i vanliga filer .md och inte i MDX.

```js

Kodblock i Markdown visar vanligtvis bara koden. När du använder Styleguidist kommer vilket kodblock som helst med språkets tagg js, jsx eller javascript att visas som en React-komponent. Precis som i Docz är koden redigerbar — du kan ändra egenskaper och se resultatet omedelbart.

Styleguidist kommer automatiskt att skapa en egenskapstabell från PropTypes, Flow eller Typescript-deklarationer.

Styleguidist stödjer nu React och Vue.

Storybook

Storybook positionerar sig som "utvecklingsmiljö för UI-komponenter". Istället för att skriva exempel på komponenter inuti Markdown- eller MDX-filer skriver du historien inne i Javascript-filer. Historien dokumentera ett specifikt tillstånd av komponenten. Till exempel kan en komponent ha historik för laddningstillstånd och avstängd tillstånd (inaktiverad).

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

Storybook är mycket mer komplex än Styleguidist och Docz. Men det är samtidigt det mest populära alternativet, med över 36 000 stjärnor på Github. Det är ett projekt med öppen källkod, som har 657 bidragsgivare och stöds av anställda. Används av Airbnb, Algolia, Atlassian, Lyft och Salesforce. Storybook stöder fler ramverk än sina konkurrenter — React, React Native, Vue, Angular, Mithril, Ember, Riot, Svelte och vanlig HTML.

I framtida releaser kommer funktioner från Docz att inkluderas och MDX kommer att implementeras.

# Button

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

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

Nya funktioner för Storybook kommer att introduceras gradvis under de kommande månaderna och det verkar som om detta kommer att bli ett stort framsteg.

Sammanfattning

Fördelarna med mönsterbibliotek hyllas i miljontals artiklar på Medium. När allt görs rätt underlättar de skapandet av relaterade produkter och upprätthållandet av enhetlighet. Selvklart, inget av dessa verktyg kan magiskt skapa en designsystem. Det kräver noggrant utformande av design och CSS. Men när det är dags att göra designsystemet tillgängligt för hela företaget, är Docz, Storybook och Styleguidist utmärkta alternativ.

Från översättaren. Detta är min första erfarenhet på Habré. Om du har hittat några brister eller har förslag på förbättringar av artikeln — skicka mig ett meddelande.

Källa: habr.com