Lewende riglyne - MDX en ander raamwerke

Jy het dalk 'n beter oopbronprojek, maar as dit nie goeie dokumentasie het nie, is die kans goed dat dit nooit sal opstyg nie. In die kantoor sal goeie dokumentasie jou daarvan weerhou om dieselfde vrae oor en oor te beantwoord. Dokumentasie verseker ook dat mense sin kan maak van die projek as sleutelwerknemers die maatskappy verlaat of rolle verander. Regstreekse riglyne help om data-integriteit te verseker.

As jy lang teks moet skryf, is Markdown 'n goeie alternatief vir HTML. Soms is die Markdown-sintaksis nie genoeg nie. In hierdie geval kan ons HTML daarin gebruik. Byvoorbeeld, pasgemaakte elemente. As jy dus 'n ontwerpstelsel met inheemse webkomponente bou, is dit maklik om dit by teksdokumentasie in te sluit. As jy React (of enige ander JSX-raamwerk soos Preact of Vue) gebruik, kan jy dieselfde met MDX doen.

Hierdie artikel is 'n breë oorsig van hulpmiddels vir die skryf van dokumentasie en die skep van 'n riglyn. Nie al die gereedskap wat hier gelys word, gebruik MDX nie, maar dit word toenemend by dokumentasie-instrumente ingesluit.

Wat is MDX?

lêer .mdx het dieselfde sintaksis as Markdown, maar laat jou toe om interaktiewe JSX-komponente in te voer en dit in jou inhoud in te bed. Ondersteuning vir Vue-komponente is in alfa. Om met MDX te begin werk, installeer net "Create React App". Daar is plugins vir Next.js en Gatsby. Die volgende weergawe van Docusaurus (weergawe 2) sal ook ingeboude ondersteuning hê.

Skryf dokumentasie met Docusaurus

Docusaurus het op Facebook geskryf. Hulle gebruik dit op elke oopbronprojek behalwe React. Buite die maatskappy gebruik Redux, Prettier, Gulp en Babel dit.

Projekte wat Docusaurus gebruik.

Docusaurus kan gebruik word om te skryf enige dokumentasie, nie net vir die beskrywing van die frontend nie. Dit het React onder die enjinkap, maar jy hoef nie daarmee vertroud te wees om dit te gebruik nie. Dit neem jou Markdown-lêers, 'n knippie magie en goed gestruktureerde, geformatteerde en leesbare dokumentasie met 'n pragtige ontwerp is gereed.

U kan die standaard Docusaurus-sjabloon op die Redux-webwerf sien.

Werwe wat met Docusaurus gebou is, kan ook 'n Markdown-gebaseerde blog insluit. Vir sintaksis-uitlig, is Prism.js onmiddellik ingesluit. Ten spyte van die feit dat Docusaurus relatief onlangs verskyn het, is dit erken as die beste hulpmiddel van 2018 op StackShare.

Ander opsies vir inhoudskepping

Docusaurus is spesifiek ontwerp vir die skep van dokumentasie. Natuurlik is daar 'n miljoen en een maniere om 'n webwerf te maak - jy kan jou eie oplossing in enige taal, CMS, ontplooi of 'n statiese werfgenerator gebruik.

Byvoorbeeld, die dokumentasie vir React, die IBM-ontwerpstelsel, Apollo en Ghost CMS gebruik Gatsby, 'n statiese werfgenerator wat dikwels vir blogs gebruik word. As u met Vue werk, is VuePress 'n goeie opsie vir u. Nog 'n opsie is om 'n kragopwekker te gebruik wat in Python - MkDocs geskryf is. Dit is oop en gekonfigureer met 'n enkele YAML-lêer. GitBook is ook 'n goeie opsie, maar dit is net gratis vir oop en nie-kommersiële spanne. U kan ook net mardown-lêers oplaai met behulp van git en daarmee in Github werk.

Komponentdokumentasie: Docz, Storieboek en Styleguidist

Riglyne, stelselontwerp, komponentbiblioteke, wat jy dit ook al wil noem, dit het die afgelope tyd baie gewild geword. Die opkoms van komponentraamwerke soos React en die gereedskap wat hier genoem word, het dit moontlik gemaak om dit van nietigheidsprojekte in nuttige instrumente te omskep.

Storieboek, Docz en Styleguidist doen dieselfde ding: vertoon interaktiewe elemente en dokumenteer hul API. 'n Projek kan dosyne of selfs honderde komponente hê, almal met verskillende toestande en style. As jy wil hê dat komponente hergebruik moet word, moet mense weet dat hulle bestaan. Om dit te doen, is dit genoeg om die komponente te katalogiseer. Riglyne bied 'n maklik om te soek oorsig van al jou komponente. Dit help om visuele konsekwentheid te handhaaf en herhalende werk te vermy.

Hierdie instrumente bied 'n gerieflike manier om verskillende state te sien. Dit kan moeilik wees om elke toestand van 'n komponent in die konteks van 'n werklike toepassing te herhaal. In plaas daarvan om op die werklike toepassing te klik, is dit die moeite werd om 'n aparte komponent te ontwikkel. Dit is moontlik om moeilik bereikbare toestande te modelleer (byvoorbeeld laaitoestand).

Saam met 'n visuele demonstrasie van verskeie toestande en 'n lys eienskappe, is dit dikwels nodig om 'n algemene beskrywing van die inhoud te skryf - ontwerpredes, gebruiksgevalle of 'n beskrywing van die resultate van gebruikerstoetsing. Markdown is baie maklik om te leer - ideaal gesproke moet riglyne 'n gedeelde hulpbron vir ontwerpers en ontwikkelaars wees. Docz, Styleguidist en Storybook bied 'n manier om Markdown maklik met komponente te meng.

Docz

Tans werk Docz net met React, maar werk aktief aan ondersteuning vir Preact, Vue en webkomponente. Docz is die mees onlangse van die drie instrumente, maar kon meer as 14 000 sterre op Github versamel. Docz stel twee komponente bekend − <Playground> и < Props >. Hulle word ingevoer en in lêers gebruik .mdx.

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

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

<Button>click</Button>

Jy kan jou eie React-komponente daarmee toedraai <Playground>om 'n analoog van die ingeboude CodePen of CodeSandbox te skep - dit wil sê, jy sien jou komponent en kan dit wysig.

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

<Props> sal alle beskikbare eiendomme vir die gegewe React-komponent, verstekwaardes wys en of die eiendom benodig word.

<Props of={Button} />

Persoonlik vind ek hierdie MDX-gebaseerde benadering die maklikste om te verstaan ​​en die maklikste om mee te werk.

As jy 'n aanhanger is van Gatsby se statiese werfgenerator, bied Docz wonderlike integrasies.

stylgids

Soos in Docz, word voorbeelde geskryf met behulp van Markdown-sintaksis. Styleguidist gebruik Markdown-kodeblokke (drievoudige aanhalingstekens) in gewone lêers .md lêers, nie in MDX nie.

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

Kodeblokke in Markdown wys gewoonlik net die kode. Wanneer jy Styleguidist gebruik, enige blok kode met 'n taalmerker js, jsx of javascript sal as 'n React-komponent weergee. Soos Docz, is die kode redigeerbaar - jy kan eienskappe verander en die resultaat onmiddellik sien.

Styleguidist sal outomaties 'n eiendomsblad skep uit PropTypes, Flow of Typescript verklarings.

Styleguidist ondersteun nou React en Vue.

Storieboek

Storieboek reken homself as 'n "UI-komponent-ontwikkelingsomgewing". In plaas daarvan om komponentvoorbeelde binne Markdown- of MDX-lêers te skryf, skryf jy stories binne Javascript-lêers. Story dokumenteer die spesifieke toestand van 'n komponent. Byvoorbeeld, 'n komponent kan geskiedenisse hê vir 'n laaitoestand en 'n gedeaktiveerde toestand (gestremd).

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

Storieboek is baie meer kompleks as Styleguidist en Docz. Maar terselfdertyd is dit die gewildste opsie, op Github het die projek meer as 36 000 sterre. Dit is 'n oopbronprojek met 657 bydraers en personeelbegeleiding. Dit word gebruik deur Airbnb, Algolia, Atlassian, Lyft en Salesforce. Storieboek ondersteun meer raamwerke as die kompetisie - React, React Native, Vue, Angular, Mithril, Ember, Riot, Svelte en gewone HTML.

In 'n toekomstige vrystelling sal daar skyfies van Docz wees en MDX word bekendgestel.

# Button

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

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

Die nuwe Storybook-kenmerke sal oor die volgende paar maande geleidelik uitrol, en dit lyk of dit 'n groot stap vorentoe sal wees.

Resultate van

Die voordele van die patroonbiblioteek word in miljoene artikels op Medium geprys. As dit goed gedoen word, maak dit dit makliker om verwante produkte te skep en 'n identiteit te handhaaf. Natuurlik sal nie een van hierdie instrumente 'n ontwerpstelsel op magiese wyse skep nie. Dit vereis noukeurige ontwerp en CSS-ontwerp. Maar wanneer dit tyd word om die ontwerpstelsel aan die hele maatskappy beskikbaar te stel, is Docz, Storybook en Styleguidist goeie opsies.

Van 'n vertaler. Dit is my eerste ervaring op Habré. As jy enige onakkuraathede vind, of voorstelle het om die artikel te verbeter - skryf in 'n persoonlike.

Bron: will.com