{"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\/da\/blog\/administrirovanie\/zhivye-gajdlajny-mdx-i-drugie-frejmvorki","title":{"rendered":"Live retningslinjer \u2014 MDX og andre rammer","gt_translate_keys":[{"key":"rendered","format":"text"}]},"content":{"rendered":"

Du kan have det bedste open source-projekt, men hvis det ikke har en god dokumentation, er der en risiko for, at det aldrig vil f\u00e5 succes. God dokumentation p\u00e5 kontoret g\u00f8r, at du ikke beh\u00f8ver at besvare de samme sp\u00f8rgsm\u00e5l igen og igen. Dokumentationen sikrer ogs\u00e5, at folk kan forst\u00e5 projektet, hvis n\u00f8gleressourcer forlader virksomheden, eller hvis roller \u00e6ndres. Leve-gaitelines hj\u00e6lper med at opretholde dataintegritet. <\/p>\n

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

Hvis du har brug for at skrive en lang tekst, er Markdown et fremragende alternativ til HTML. Nogle gange er syntaksen i Markdown ikke tilstr\u00e6kkelig. I s\u00e5 fald kan vi bruge HTML indeni det. For eksempel, tilpassede elementer. S\u00e5 hvis du bygger et designsystem med native webkomponenter, kan de nemt inkluderes i den tekstlige dokumentation. Hvis du bruger React (eller en anden JSX-ramme som Preact eller Vue), kan du g\u00f8re det samme ved hj\u00e6lp af MDX. <\/p>\n

<\/p>\n

Denne artikel er en bred oversigt over v\u00e6rkt\u00f8jer til at skrive dokumentation og oprette retningslinjer. Ikke alle v\u00e6rkt\u00f8jer, der er n\u00e6vnt her, bruger MDX, men det bliver i stigende grad integreret i dokumentationsv\u00e6rkt\u00f8jer.<\/p>\n

<\/p>\n

Hvad er MDX?<\/h2>\n

<\/p>\n

Fil .mdx<\/code> har det samme syntaks som Markdown, men giver mulighed for at importere interaktive JSX-komponenter og integrere dem i dit indhold. Underst\u00f8ttelse af Vue-komponenter er stadig i alfa. For at komme i gang med MDX er det nok at installere 'Create React App'. Der findes plugins til Next.js og Gatsby. Den n\u00e6ste version af Docusaurus (version 2) vil ogs\u00e5 have indbygget st\u00f8tte.<\/p>\n

<\/p>\n

Skrivning af dokumentation med Docusaurus<\/h2>\n

<\/p>\n

Docusaurus er udviklet af Facebook. De bruger det i hvert open source-projekt undtagen React. Uden for virksomheden bruges det af Redux, Prettier, Gulp og Babel.<\/p>\n

<\/p>\n

\"LiveProjekter der bruger Docusaurus.<\/em><\/p>\n

<\/p>\n

Docusaurus kan bruges til at skrive enhver<\/em> dokumentation, ikke kun til frontend-beskrivelser. Det er bygget p\u00e5 React, men du beh\u00f8ver ikke at v\u00e6re bekendt med det for at bruge det. Det tager dine Markdown-filer, en smule magi, og s\u00e5 er godt struktureret, formateret og l\u00e6sevenlig dokumentation med et smukt design klar. <\/p>\n

<\/p>\n

\"Live
\nP\u00e5 Redux's hjemmeside kan du se den standard Docusaurus skabelon.<\/em><\/p>\n

<\/p>\n

Websites created with Docusaurus can also include a blog based on Markdown. Syntax highlighting is immediately enabled with Prism.js. Although Docusaurus has emerged relatively recently, it was recognized as the best tool of 2018 on StackShare. <\/p>\n

<\/p>\n

Andre muligheder for oprettelse af indhold<\/h2>\n

<\/p>\n

Docusaurus er specifikt designet til at oprette dokumentation. Selvf\u00f8lgelig er der en million og \u00e9n m\u00e5de at lave en hjemmeside p\u00e5 \u2014 du kan implementere din egen l\u00f8sning p\u00e5 ethvert sprog, CMS eller bruge en statisk hjemmesidegenerator.<\/p>\n

<\/p>\n

For eksempel bruger dokumentationen til React, IBMs designsystem, Apollo og Ghost CMS Gatsby \u2014 en statisk hjemmesidegenerator, der ofte anvendes til blogs. Hvis du arbejder med Vue, vil VuePress v\u00e6re et godt valg for dig. En anden mulighed er at bruge en generator skrevet i Python \u2014 MkDocs. Det er open source og konfigureres med en enkelt YAML-fil. GitBook er ogs\u00e5 et godt valg, men er kun gratis for \u00e5bne og ikke-kommercielle teams. Alternativt kan du bare uploade Markdown-filer ved at bruge Git og arbejde med dem i GitHub. <\/p>\n

<\/p>\n

Dokumentering af komponenter: Docz, Storybook og Styleguidist<\/h2>\n

<\/p>\n

Retningslinjer, designsystemer, komponentbiblioteker \u2014 uanset hvad du kalder dem, er de blevet meget popul\u00e6re p\u00e5 det seneste. Fremkomsten af komponentbaserede rammer som React og de v\u00e6rkt\u00f8jer, der er n\u00e6vnt her, har gjort det muligt at forvandle dem fra blot et skud i t\u00e5gen til nyttige v\u00e6rkt\u00f8jer. <\/p>\n

<\/p>\n

Storybook, Docz og Styleguidist g\u00f8r det samme: de viser interaktive elementer og dokumenterer deres API. Et projekt kan have snesevis eller endda hundreder af komponenter \u2014 alle med forskellige tilstande og stilarter. Hvis du \u00f8nsker, at komponenterne skal genbruges, skal folk vide, at de eksisterer. Det er tilstr\u00e6kkeligt at katalogisere komponenterne. Retningslinjerne giver et brugervenligt overblik over alle dine komponenter. Dette hj\u00e6lper med at opretholde visuel konsistens og undg\u00e5 dobbeltarbejde.<\/p>\n

<\/p>\n

Disse v\u00e6rkt\u00f8jer giver en bekvem m\u00e5de at se forskellige tilstande p\u00e5. Det kan v\u00e6re sv\u00e6rt at genskabe hver tilstand af en komponent i konteksten af en reel applikation. I stedet for at klikke rundt i en reel app, b\u00f8r du udvikle en separat komponent. Det er muligt at simulere sv\u00e6re tilstande (f.eks. indl\u00e6sningsstatus). <\/p>\n

<\/p>\n

Sammen med den visuelle demonstration af forskellige tilstande og en liste over egenskaber er det ofte n\u00f8dvendigt at skrive en generel beskrivelse af indholdet \u2014 begrundelse for designet, anvendelsesscenarier eller beskrivelse af resultaterne fra brugertests. Markdown er meget enkelt at l\u00e6re \u2014 ideelt set b\u00f8r retningslinjerne v\u00e6re en f\u00e6lles ressource for designere og udviklere. Docz, Styleguidist og Storybook tilbyder en m\u00e5de at nemt blande Markdown med komponenter.<\/p>\n

<\/p>\n

Docz<\/h2>\n

<\/p>\n

Docz fungerer i \u00f8jeblikket kun med React, men der arbejdes aktivt p\u00e5 at underst\u00f8tte Preact, Vue og webkomponenter. Docz er den nyeste af de tre v\u00e6rkt\u00f8jer, men har form\u00e5et at samle over 14.000 stjerner p\u00e5 GitHub. Docz pr\u00e6senterer to komponenter \u2014 <Playground><\/code> og < Props ><\/code>. De importeres og bruges i filer .mdx<\/code>. <\/p>\n

<\/p>\n

import { Playground, Props } from \"docz\";\nimport Button from \"..\\\/src\\\/Button\";\n\n## Du kan _skrive_ **markdown**\n### Du kan importere og bruge komponenter\n\n