{"id":34791,"date":"2019-10-31T22:00:25","date_gmt":"2019-10-31T19:00:25","guid":{"rendered":"https:\/\/prohoster.info\/blog\/zhivye-gajdlajny-mdx-i-drugie-frejmvorki\/"},"modified":"2019-10-31T22:00:25","modified_gmt":"2019-10-31T19:00:25","slug":"zhivye-gajdlajny-mdx-i-drugie-frejmvorki","status":"publish","type":"post","link":"https:\/\/prohoster.info\/nl\/blog\/administrirovanie\/zhivye-gajdlajny-mdx-i-drugie-frejmvorki","title":{"rendered":"Live richtlijnen - MDX en andere frameworks","gt_translate_keys":[{"key":"rendered","format":"text"}]},"content":{"rendered":"

Je kunt een geweldig open-source project hebben, maar als het geen goede documentatie heeft, is de kans groot dat het nooit zal slagen. Goede documentatie op kantoor voorkomt dat je steeds dezelfde vragen moet beantwoorden. Documentatie zorgt er ook voor dat mensen het project kunnen begrijpen, zelfs als sleutelfiguren het bedrijf verlaten of rollen veranderen. Leefrichtlijnen helpen de integriteit van de gegevens te waarborgen. <\/p>\n

<\/a><\/noindex><\/p>\n

Als je een lange tekst moet schrijven, is Markdown een uitstekend alternatief voor HTML. Soms is de syntaxis van Markdown niet voldoende. In dat geval kunnen we HTML binnen Markdown gebruiken. Bijv. op maat gemaakte elementen. Dus als je een ontwerpsysteem bouwt met native webcomponenten, is het eenvoudig om deze in de tekstdocumentatie op te nemen. Als je React (of een andere JSX-framework zoals Preact of Vue) gebruikt, kun je hetzelfde doen met MDX. <\/p>\n

<\/p>\n

Dit artikel is een brede overzicht van tools voor het schrijven van documentatie en het cre\u00ebren van richtlijnen. Niet alle tools die hier worden genoemd, gebruiken MDX, maar het wordt steeds vaker opgenomen in documentatietools.<\/p>\n

<\/p>\n

Wat is MDX?<\/h2>\n

<\/p>\n

Bestand .mdx<\/code> heeft dezelfde syntaxis als Markdown, maar maakt het mogelijk om interactieve JSX-componenten te importeren en in uw content in te bedden. Ondersteuning voor Vue-componenten bevindt zich in de alfa-fase. Om te beginnen met werken met MDX, hoeft u alleen maar «Create React App» te installeren. Er zijn plugins voor Next.js en Gatsby. De volgende versie van Docusaurus (versie 2) zal ook ingebouwde ondersteuning hebben.<\/p>\n

<\/p>\n

Documentatie schrijven met Docusaurus<\/h2>\n

<\/p>\n

Docusaurus is ontwikkeld door Facebook. Ze gebruiken het voor elk open-source project, behalve React. Buiten het bedrijf wordt het gebruikt door Redux, Prettier, Gulp en Babel.<\/p>\n

<\/p>\n

\"LiveProjecten die Docusaurus gebruiken.<\/em><\/p>\n

<\/p>\n

Docusaurus kan worden gebruikt voor het schrijven van elk<\/em> documentatie, niet alleen voor de front-end beschrijving. Het heeft React onder de motorkap, maar je hoeft niet bekend te zijn met React om het te gebruiken. Het pakt je Markdown-bestanden, een snufje magie en goed gestructureerde, opgemaakte en leesbare documentatie met een mooi ontwerp is klaar. <\/p>\n

<\/p>\n

\"Live
\nOp de Redux-website kun je de standaard sjabloon van Docusaurus bekijken.<\/em><\/p>\n

<\/p>\n

Sites die zijn gemaakt met Docusaurus kunnen ook een blog gebaseerd op Markdown bevatten. Voor syntax highlighting is Prism.js direct ge\u00efntegreerd. Hoewel Docusaurus relatief recent is verschenen, werd het uitgeroepen tot het beste hulpmiddel van 2018 op StackShare. <\/p>\n

<\/p>\n

Andere manieren om content te cre\u00ebren<\/h2>\n

<\/p>\n

Docusaurus is speciaal ontworpen voor het maken van documentatie. Er zijn natuurlijk miljoenen manieren om een website te maken \u2014 je kunt je eigen oplossing op elke taal of CMS opzetten of gebruik maken van een statische sitegenerator.<\/p>\n

<\/p>\n

Bijvoorbeeld, de documentatie voor React, het IBM design systeem, Apollo en Ghost CMS gebruiken Gatsby \u2014 een statische sitegenerator die vaak voor blogs wordt gebruikt. Als je met Vue werkt, is VuePress een goed alternatief voor jou. Een andere optie is om een generator te gebruiken die in Python is geschreven \u2014 MkDocs. Dit is open-source en kan worden geconfigureerd met \u00e9\u00e9n YAML-bestand. GitBook is ook een goede optie, maar het is gratis alleen voor open en niet-commerci\u00eble teams. En je kunt eenvoudig Markdown-bestanden uploaden met Git en ermee werken in Github. <\/p>\n

<\/p>\n

Documentatie van componenten: Docz, Storybook en Styleguidist<\/h2>\n

<\/p>\n

Richtlijnen, design systemen, componentbibliotheken \u2014 hoe je ze ook noemt, ze zijn de laatste tijd erg populair geworden. De opkomst van componentframeworks zoals React en de tools die hier worden genoemd, heeft ervoor gezorgd dat ze zijn ge\u00ebvolueerd van ijdelheidsprojecten naar nuttige hulpmiddelen. <\/p>\n

<\/p>\n

Storybook, Docz en Styleguidist doen allemaal hetzelfde: ze tonen interactieve elementen en documenteren hun API. Een project kan tientallen of zelfs honderden componenten hebben \u2014 allemaal met verschillende toestanden en stijlen. Als je wilt dat componenten hergebruikt worden, moeten mensen weten dat ze bestaan. Het is voldoende om de componenten te catalogiseren. Richtlijnen bieden een gemakkelijk doorzoekbaar overzicht van al je componenten. Dit helpt om visuele consistentie te behouden en dubbele inspanningen te vermijden.<\/p>\n

<\/p>\n

Deze tools bieden een gemakkelijke manier om verschillende toestanden te bekijken. Het kan moeilijk zijn om elke toestand van een component in de context van een echte applicatie na te bootsen. In plaats van door een echte applicatie te klikken, is het beter om een aparte component te ontwikkelen. Je kunt moeilijk bereikbare toestanden modelleren (bijvoorbeeld een laadstatus). <\/p>\n

<\/p>\n

Naast de visuele demonstratie van verschillende toestanden en de lijst met eigenschappen is het vaak nodig om een algemene beschrijving van de inhoud te schrijven \u2014 ontwerpverantwoording, gebruikscases of de resultaten van gebruikerstests. Markdown is heel eenvoudig te leren \u2014 idealiter moet de richtlijn een gezamenlijke bron zijn voor ontwerpers en ontwikkelaars. Docz, Styleguidist en Storybook bieden een manier om eenvoudig Markdown met componenten te mengen.<\/p>\n

<\/p>\n

Docz<\/h2>\n

<\/p>\n

Momenteel werkt Docz alleen met React, maar er wordt hard gewerkt aan ondersteuning voor Preact, Vue en webcomponenten. Docz is het nieuwste van de drie tools, maar heeft op Github meer dan 14.000 sterren verzameld. Docz introduceert twee componenten \u2014 <Playground><\/code> en < Props ><\/code>. Ze worden ge\u00efmporteerd en gebruikt in bestanden .mdx<\/code>. <\/p>\n

<\/p>\n

import { Playground, Props } from \"docz\";\nimport Button from \"..\\\/src\\\/Button\";\n\n## Je kunt _schrijven_ **markdown**\n### Je kunt componenten importeren en gebruiken\n\n