{"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\/sv\/blog\/administrirovanie\/zhivye-gajdlajny-mdx-i-drugie-frejmvorki","title":{"rendered":"Levande riktlinjer - MDX och andra ramverk","gt_translate_keys":[{"key":"rendered","format":"text"}]},"content":{"rendered":"

Du kan ha det b\u00e4sta projektet med \u00f6ppen k\u00e4llkod, men om det inte finns bra dokumentation finns det en risk att det aldrig f\u00e5r fart. God dokumentation p\u00e5 kontoret g\u00f6r att du slipper svara p\u00e5 samma fr\u00e5gor om och om igen. Dokumentationen s\u00e4kerst\u00e4ller ocks\u00e5 att m\u00e4nniskor kan f\u00f6rst\u00e5 projektet om nyckelpersoner l\u00e4mnar f\u00f6retaget eller roller \u00e4ndras. Levande riktlinjer hj\u00e4lper till att s\u00e4kerst\u00e4lla dataintegritet. <\/p>\n

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

Om du beh\u00f6ver skriva en l\u00e5ng text \u00e4r Markdown ett utm\u00e4rkt alternativ till HTML. Ibland r\u00e4cker inte Markdown-syntaxen till. I s\u00e5 fall kan vi anv\u00e4nda HTML inuti den. Till exempel anpassade element. Om du bygger ett designsystem med inbyggda webbkomponenter \u00e4r det enkelt att inkludera dem i dokumenttexten. Om du anv\u00e4nder React (eller n\u00e5got annat JSX-ramverk, som Preact eller Vue), kan du g\u00f6ra samma sak med MDX. <\/p>\n

<\/p>\n

Denna artikel \u00e4r en \u00f6versikt \u00f6ver verktyg f\u00f6r att skriva dokumentation och skapa riktlinjer. Inte alla verktyg som n\u00e4mns h\u00e4r anv\u00e4nder MDX, men det blir alltmer vanligt i dokumentationsverktyg.<\/p>\n

<\/p>\n

Vad \u00e4r MDX?<\/h2>\n

<\/p>\n

Fil .mdx<\/code> har samma syntax som Markdown, men l\u00e5ter dig importera interaktiva JSX-komponenter och b\u00e4dda in dem i ditt inneh\u00e5ll. St\u00f6d f\u00f6r Vue-komponenter \u00e4r fortfarande i alpha. F\u00f6r att b\u00f6rja anv\u00e4nda MDX r\u00e4cker det med att installera \u00abCreate React App\u00bb. Det finns plugins f\u00f6r Next.js och Gatsby. N\u00e4sta version av Docusaurus (version 2) kommer ocks\u00e5 att ha inbyggt st\u00f6d.<\/p>\n

<\/p>\n

Skriva dokumentation med Docusaurus<\/h2>\n

<\/p>\n

Docusaurus skapades av Facebook. De anv\u00e4nder det i varje projekt med \u00f6ppen k\u00e4llkod, utom f\u00f6r React. Utanf\u00f6r f\u00f6retaget anv\u00e4nds det av Redux, Prettier, Gulp och Babel.<\/p>\n

<\/p>\n

\"LevandeProjekt som anv\u00e4nder Docusaurus.<\/em><\/p>\n

<\/p>\n

Docusaurus kan anv\u00e4ndas f\u00f6r att skriva n\u00e5gon<\/em> dokumentation, inte bara f\u00f6r att beskriva frontend. Den bygger p\u00e5 React, men f\u00f6r att anv\u00e4nda den beh\u00f6ver du inte vara bekant med den. Den tar dina Markdown-filer, en gnutta magi och s\u00e5 \u00e4r v\u00e4lstrukturerad, formaterad och l\u00e4sbar dokumentation med vacker design klar. <\/p>\n

<\/p>\n

\"Levande
\nP\u00e5 Redux-webbplatsen kan du se den standardmall som Docusaurus anv\u00e4nder.<\/em><\/p>\n

<\/p>\n

Webbplatser som skapats med Docusaurus kan \u00e4ven inkludera en blogg baserad p\u00e5 Markdown. F\u00f6r syntaxmarkering \u00e4r Prism.js direkt integrerat. Trots att Docusaurus \u00e4r relativt nytt har det erk\u00e4nds som det b\u00e4sta verktyget 2018 p\u00e5 StackShare. <\/p>\n

<\/p>\n

Andra alternativ f\u00f6r att skapa inneh\u00e5ll<\/h2>\n

<\/p>\n

Docusaurus \u00e4r speciellt utformat f\u00f6r att skapa dokumentation. Sj\u00e4lvklart finns det miljoner s\u00e4tt att skapa en webbplats \u2014 du kan drifts\u00e4tta din egen l\u00f6sning i valfritt spr\u00e5k, CMS eller anv\u00e4nda en statisk webbplatsgenerator.<\/p>\n

<\/p>\n

Till exempel anv\u00e4nder dokumentationen f\u00f6r React, design systemet IBM, Apollo och Ghost CMS Gatsby \u2014 en statisk webbplatsgenerator som ofta anv\u00e4nds f\u00f6r bloggar. Om du arbetar med Vue kan VuePress vara ett bra alternativ f\u00f6r dig. Ett annat alternativ \u00e4r att anv\u00e4nda en generator skriven i Python \u2014 MkDocs. Den \u00e4r \u00f6ppen och konfigureras med en enda YAML-fil. GitBook \u00e4r ocks\u00e5 ett bra alternativ, men det \u00e4r gratis endast f\u00f6r \u00f6ppna och ideella team. Du kan \u00e4ven helt enkelt ladda upp Markdown-filer med hj\u00e4lp av git och arbeta med dem i GitHub. <\/p>\n

<\/p>\n

Dokumentera komponenter: Docz, Storybook och Styleguidist<\/h2>\n

<\/p>\n

Riktlinjer, designsystem, komponentbibliotek \u2014 vad du \u00e4n kallar dem, s\u00e5 har de blivit mycket popul\u00e4ra p\u00e5 sistone. Framv\u00e4xten av komponentramverk som React och verktygen som n\u00e4mns h\u00e4r har m\u00f6jliggjort att de kan omvandlas fr\u00e5n f\u00e5f\u00e4nga projekt till anv\u00e4ndbara verktyg. <\/p>\n

<\/p>\n

Storybook, Docz och Styleguidist g\u00f6r i princip samma sak: de visar interaktivaelement och dokumenterar deras API. Ett projekt kan ha tiotals eller till och med hundratals komponenter \u2014 alla med olika tillst\u00e5nd och stilar. Om du vill att komponenterna ska \u00e5teranv\u00e4ndas, m\u00e5ste m\u00e4nniskor veta att de finns. F\u00f6r det r\u00e4cker det med att katalogisera komponenterna. Riktlinjer ger en l\u00e4ttillg\u00e4nglig \u00f6versikt \u00f6ver alla dina komponenter. Detta hj\u00e4lper till att uppr\u00e4tth\u00e5lla visuell konsekvens och undvika duplicerat arbete.<\/p>\n

<\/p>\n

Dessa verktyg erbjuder ett bekv\u00e4mt s\u00e4tt att visa olika tillst\u00e5nd. Det kan vara sv\u00e5rt att \u00e5terskapa varje komponenttillst\u00e5nd i kontexten av en verklig applikation. Ist\u00e4llet f\u00f6r att klicka kring i en verklig applikation \u00e4r det b\u00e4ttre att utveckla en separat komponent. Du kan modellera sv\u00e5r\u00e5tkomliga tillst\u00e5nd (t.ex. laddningstillst\u00e5nd). <\/p>\n

<\/p>\n

I takt med den visuella visningen av olika tillst\u00e5nd och en lista \u00f6ver egenskaper \u00e4r det ofta n\u00f6dv\u00e4ndigt att skriva en allm\u00e4n beskrivning av inneh\u00e5llet \u2014 designmotiveringar, anv\u00e4ndningsfall eller beskrivningar av resultat fr\u00e5n anv\u00e4ndartester. Markdown \u00e4r mycket enkelt att l\u00e4ra sig \u2014 idealiskt sett b\u00f6r riktlinjer vara en gemensam resurs f\u00f6r designers och utvecklare. Docz, Styleguidist och Storybook erbjuder ett s\u00e4tt att enkelt blanda Markdown med komponenter.<\/p>\n

<\/p>\n

Docz<\/h2>\n

<\/p>\n

Just nu fungerar Docz endast med React, men arbete p\u00e5g\u00e5r aktivt f\u00f6r att st\u00f6dja Preact, Vue och webbkomponenter. Docz \u00e4r det senaste av de tre verktygen, men har samlat mer \u00e4n 14 000 stj\u00e4rnor p\u00e5 Github. Docz presenterar tv\u00e5 komponenter \u2014 <Playground><\/code> och < Props ><\/code>. De importeras och anv\u00e4nds i filer .mdx<\/code>. <\/p>\n

<\/p>\n

import { Playground, Props } from \"docz\";\nimport Button from \"..\\\/src\\\/Button\";\n\n## Du kan _skriva_ **markdown**\n### Du kan importera och anv\u00e4nda komponenter\n\n