Livsriktlinjer - MDX och andra ramverk

Du kanske har ett bättre projekt med öppen källkod, men om det inte har bra dokumentation är chansen stor att det aldrig kommer att ta fart. På kontoret kommer bra dokumentation att hindra dig från att svara på samma frågor om och om igen. Dokumentation säkerställer också att människor kan förstå projektet om nyckelmedarbetare lämnar företaget eller roller ändras. Liveriktlinjer hjälper till att säkerställa dataintegritet.

Om du behöver skriva lång text är Markdown ett bra alternativ till HTML. Ibland räcker inte Markdown-syntaxen. I det här fallet kan vi använda HTML inuti den. Till exempel anpassade element. Därför, om du bygger ett designsystem med inbyggda webbkomponenter, är det enkelt att inkludera dem i textdokumentation. Om du använder React (eller något annat JSX-ramverk som Preact eller Vue), kan du göra detsamma med MDX.

Den här artikeln är en bred översikt över verktyg för att skriva dokumentation och skapa en riktlinje. Inte alla verktyg som listas här använder MDX, men det ingår i allt större utsträckning i dokumentationsverktyg.

Vad är MDX?

fil .mdx har samma syntax som Markdown men låter dig importera interaktiva JSX-komponenter och bädda in dem i ditt innehåll. Stöd för Vue-komponenter är i alfa. För att börja arbeta med MDX, installera bara "Create React App". Det finns plugins för Next.js och Gatsby. Nästa version av Docusaurus (version 2) kommer också att ha inbyggt stöd.

Skriva dokumentation med Docusaurus

Docusaurus skrev på Facebook. De använder det på alla open source-projekt utom React. Utanför företaget använder Redux, Prettier, Gulp och Babel det.

Projekt som använder Docusaurus.

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

Du kan se standardmallen för Docusaurus på Redux-webbplatsen.

Webbplatser byggda med Docusaurus kan också innehålla en Markdown-baserad blogg. För syntaxmarkering ingår Prism.js omedelbart. Trots att Docusaurus har dykt upp relativt nyligen, erkändes det som det bästa verktyget 2018 på StackShare.

Andra alternativ för att skapa innehåll

Docusaurus är speciellt utformad för att skapa dokumentation. Naturligtvis finns det en miljon och ett sätt att skapa en webbplats - du kan distribuera din egen lösning på vilket språk som helst, CMS, eller använda en statisk webbplatsgenerator.

Till exempel använder dokumentationen för React, IBMs designsystem, Apollo och Ghost CMS Gatsby, en statisk webbplatsgenerator som ofta används för bloggar. Om du arbetar med Vue är VuePress ett bra alternativ för dig. Ett annat alternativ är att använda en generator skriven i Python - MkDocs. Den är öppen och konfigurerad med en enda YAML-fil. GitBook är också ett bra alternativ, men det är bara gratis för öppna och icke-kommersiella team. Du kan också bara ladda upp mardown-filer med git och arbeta med dem i Github.

Komponentdokumentation: Docz, Storybook och Styleguidist

Riktlinjer, systemdesign, komponentbibliotek, vad du än vill kalla dem, dessa har blivit väldigt populära på sistone. Framväxten av komponentramverk som React och de verktyg som nämns här har gjort det möjligt att omvandla dem från fåfängaprojekt till användbara verktyg.

Storybook, Docz och Styleguidist gör samma sak: visa interaktiva element och dokumentera deras API. Ett projekt kan ha dussintals eller till och med hundratals komponenter, alla med olika tillstånd och stilar. Om du vill att komponenter ska återanvändas måste folk veta att de finns. För att göra detta räcker det att katalogisera komponenterna. Riktlinjer ger en översikt över alla dina komponenter som är lätt att söka. Detta hjälper till att upprätthålla visuell konsekvens och undvika repetitivt arbete.

Dessa verktyg ger ett bekvämt sätt att visa olika tillstånd. Det kan vara svårt att replikera varje tillstånd av en komponent i samband med en verklig applikation. Istället för att klicka på själva applikationen är det värt att utveckla en separat komponent. Det är möjligt att modellera svåråtkomliga tillstånd (till exempel laddningstillstånd).

Tillsammans med en visuell demonstration av olika tillstånd och en lista över egenskaper är det ofta nödvändigt att skriva en allmän beskrivning av innehållet - designrationalen, användningsfall eller en beskrivning av resultaten av användartestning. Markdown är väldigt lätt att lära sig – helst bör riktlinjer vara en delad resurs för designers och utvecklare. Docz, Styleguidist och Storybook erbjuder ett sätt att enkelt blanda Markdown med komponenter.

Docz

För närvarande arbetar Docz bara med React, men arbetar aktivt med stöd för Preact, Vue och webbkomponenter. Docz är det senaste av de tre verktygen, men har kunnat samla över 14 000 stjärnor på Github. Docz introducerar två komponenter − <Playground> и < Props >. De importeras och används i filer .mdx.

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

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

<Button>click</Button>

Du kan slå in dina egna React-komponenter med <Playground>för att skapa en analog till den inbyggda CodePen eller CodeSandbox - det vill säga du ser din komponent och kan redigera den.

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

<Props> kommer att visa alla tillgängliga egenskaper för den givna React-komponenten, standardvärden och om egenskapen krävs.

<Props of={Button} />

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

Om du är ett fan av Gatsbys statiska webbplatsgenerator, erbjuder Docz fantastiska integrationer.

stilguide

Som i Docz skrivs exempel med Markdown-syntax. Styleguidist använder Markdown-kodblock (trippelcitattecken) i vanliga filer .md filer, inte i MDX.

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

Kodblock i Markdown visar vanligtvis bara koden. När du använder Styleguidist, valfritt kodblock med en språktagg js, jsx eller javascript kommer att återges som en React-komponent. Liksom Docz är koden redigerbar - du kan ändra egenskaper och direkt se resultatet.

Styleguidist skapar automatiskt ett egenskapsblad från PropTypes, Flow eller Typescript-deklarationer.

Styleguidist stöder nu React och Vue.

Sagobok

Storybook fakturerar sig själv som en "UI-komponentutvecklingsmiljö". Istället för att skriva komponentexempel i Markdown- eller MDX-filer, skriver du historia inuti Javascript-filer. Story dokumentera det specifika tillståndet för en komponent. Till exempel kan en komponent ha historik för ett laddningstillstånd och ett inaktiverat tillstånd (inaktiverad).

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

Storybook är mycket mer komplex än Styleguidist och Docz. Men samtidigt är detta det mest populära alternativet, på Github har projektet mer än 36 000 stjärnor. Detta är ett projekt med öppen källkod med 657 bidragsgivare och personal. Den används av Airbnb, Algolia, Atlassian, Lyft och Salesforce. Storybook stöder fler ramverk än konkurrenterna - React, React Native, Vue, Angular, Mithril, Ember, Riot, Svelte och vanlig HTML.

I en framtida release kommer det att finnas chips från Docz och MDX introduceras.

# Button

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

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

De nya Storybook-funktionerna kommer att rullas ut gradvis under de närmaste månaderna, och det ser ut som att det kommer att vara ett stort steg framåt.

Resultat av

Fördelarna med mönsterbiblioteket hyllas i miljontals artiklar på Medium. När de görs väl gör de det lättare att skapa relaterade produkter och behålla en identitet. Naturligtvis kommer inget av dessa verktyg på magiskt sätt att skapa ett designsystem. Detta kräver noggrann design och CSS-design. Men när det är dags att göra designsystemet tillgängligt för hela företaget är Docz, Storybook och Styleguidist bra alternativ.

Från en översättare. Detta är min första upplevelse på Habré. Om du hittar några felaktigheter, eller har förslag på förbättring av artikeln - skriv i ett personligt brev.

Källa: will.com