{"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\/cs\/blog\/administrirovanie\/zhivye-gajdlajny-mdx-i-drugie-frejmvorki","title":{"rendered":"\u017div\u00e9 sm\u011brnice - MDX a dal\u0161\u00ed r\u00e1mce","gt_translate_keys":[{"key":"rendered","format":"text"}]},"content":{"rendered":"

M\u016f\u017eete m\u00edt nejlep\u0161\u00ed projekt s otev\u0159en\u00fdm zdrojov\u00fdm k\u00f3dem, ale pokud nem\u00e1 dobrou dokumentaci, je pravd\u011bpodobn\u00e9, \u017ee nikdy neusp\u011bje. Dobr\u00e1 dokumentace v kancel\u00e1\u0159i v\u00e1m umo\u017en\u00ed neodpov\u00eddat na stejn\u00e9 ot\u00e1zky znovu a znovu. Dokumentace tak\u00e9 zaji\u0161\u0165uje, \u017ee lid\u00e9 mohou pochopit projekt, pokud kl\u00ed\u010dov\u00ed zam\u011bstnanci odejdou nebo se zm\u011bn\u00ed role. \u017div\u00e9 pokyny pomohou zajistit integritu dat. <\/p>\n

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

Pokud pot\u0159ebujete napsat dlouh\u00fd text, Markdown je skv\u011blou alternativou k HTML. N\u011bkdy v\u0161ak syntaxe Markdown nesta\u010d\u00ed. V takov\u00e9m p\u0159\u00edpad\u011b m\u016f\u017eeme uvnit\u0159 n\u011bj pou\u017e\u00edt HTML. Nap\u0159\u00edklad vlastn\u00ed prvky. Pokud tedy vytv\u00e1\u0159\u00edte designov\u00fd syst\u00e9m s nativn\u00edmi webov\u00fdmi komponenty, je snadn\u00e9 je zahrnout do textov\u00e9 dokumentace. Pokud pou\u017e\u00edv\u00e1te React (nebo jak\u00fdkoli jin\u00fd framework JSX, jako je Preact nebo Vue), m\u016f\u017eete to stejn\u00e9 ud\u011blat pomoc\u00ed MDX. <\/p>\n

<\/p>\n

Tento \u010dl\u00e1nek je \u0161irok\u00fdm p\u0159ehledem n\u00e1stroj\u016f pro psan\u00ed dokumentace a vytv\u00e1\u0159en\u00ed pokyn\u016f. Ne v\u0161echny zde uveden\u00e9 n\u00e1stroje pou\u017e\u00edvaj\u00ed MDX, ale st\u00e1le \u010dast\u011bji je za\u010dle\u0148ov\u00e1no do dokumenta\u010dn\u00edch n\u00e1stroj\u016f.<\/p>\n

<\/p>\n

Co je to MDX?<\/h2>\n

<\/p>\n

Soubor .mdx<\/code> m\u00e1 stejnou strukturu jako Markdown, ale umo\u017e\u0148uje importovat interaktivn\u00ed komponenty JSX a integrovat je do va\u0161eho obsahu. Podpora komponent Vue je ve f\u00e1zi alfa. Pro za\u010d\u00e1tek pr\u00e1ce s MDX sta\u010d\u00ed nainstalovat \u201eCreate React App\u201c. Existuj\u00ed pluginy pro Next.js a Gatsby. N\u00e1sleduj\u00edc\u00ed verze Docusaurus (verze 2) tak\u00e9 bude m\u00edt vestav\u011bnou podporu.<\/p>\n

<\/p>\n

Psan\u00ed dokumentace s Docusaurus<\/h2>\n

<\/p>\n

Docusaurus napsal Facebook. Pou\u017e\u00edvaj\u00ed ho u ka\u017ed\u00e9ho projektu s otev\u0159en\u00fdm zdrojov\u00fdm k\u00f3dem krom\u011b Reactu. Mimo spole\u010dnost jej pou\u017e\u00edvaj\u00ed Redux, Prettier, Gulp a Babel.<\/p>\n

<\/p>\n

\"\u017div\u00e9Projekty, kter\u00e9 pou\u017e\u00edvaj\u00ed Docusaurus.<\/em><\/p>\n

<\/p>\n

Docusaurus lze pou\u017e\u00edt k psan\u00ed kdokoliv<\/em> dokumenatce, nejen k popisu frontendu. Pod pokli\u010dkou m\u00e1 React, ale nemus\u00edte b\u00fdt s n\u00edm obezn\u00e1men\u00ed, abyste ho pou\u017eili. Berou va\u0161e Markdown soubory, s trochou magie a dob\u0159e strukturovan\u00e1, form\u00e1tovan\u00e1 a \u010diteln\u00e1 dokumentace s kr\u00e1sn\u00fdm designem je hotov\u00e1. <\/p>\n

<\/p>\n

\"\u017div\u00e9
\nNa webu Redux m\u016f\u017eete vid\u011bt standardn\u00ed \u0161ablonu Docusaurus<\/em><\/p>\n

<\/p>\n

Webov\u00e9 str\u00e1nky vytvo\u0159en\u00e9 pomoc\u00ed Docusaurus mohou tak\u00e9 zahrnovat blog zalo\u017een\u00fd na Markdownech. Pro zv\u00fdrazn\u011bn\u00ed syntaxe je hned p\u0159ipojen Prism.js. I kdy\u017e Docusaurus vznikl pom\u011brn\u011b ned\u00e1vno, byl v roce 2018 uzn\u00e1n jako nejlep\u0161\u00ed n\u00e1stroj na StackShare. <\/p>\n

<\/p>\n

Dal\u0161\u00ed mo\u017enosti pro vytv\u00e1\u0159en\u00ed obsahu<\/h2>\n

<\/p>\n

Docusaurus je speci\u00e1ln\u011b navr\u017een pro vytv\u00e1\u0159en\u00ed dokumentace. Samoz\u0159ejm\u011b existuje milion a jeden zp\u016fsob, jak vytvo\u0159it web \u2014 m\u016f\u017eete nasadit sv\u00e9 vlastn\u00ed \u0159e\u0161en\u00ed v jak\u00e9mkoli jazyce, CMS, nebo pou\u017e\u00edt gener\u00e1tor statick\u00fdch str\u00e1nek.<\/p>\n

<\/p>\n

Nap\u0159\u00edklad dokumentace pro React, designov\u00fd syst\u00e9m IBM, Apollo a Ghost CMS pou\u017e\u00edvaj\u00ed Gatsby \u2014 to je gener\u00e1tor statick\u00fdch str\u00e1nek, kter\u00fd se \u010dasto pou\u017e\u00edv\u00e1 pro blogy. Pokud pracujete s Vue, VuePress bude pro v\u00e1s dobrou volbou. Dal\u0161\u00ed mo\u017enost\u00ed je pou\u017e\u00edt gener\u00e1tor napsan\u00fd v Pythonu \u2014 MkDocs. Je otev\u0159en\u00fd a konfiguruje se pomoc\u00ed jednoho souboru YAML. GitBook je tak\u00e9 slu\u0161n\u00e1 volba, ale je zdarma pouze pro otev\u0159en\u00e9 a nekomer\u010dn\u00ed t\u00fdmy. A tak\u00e9 lze jednodu\u0161e nahr\u00e1vat markdownov\u00e9 soubory pomoc\u00ed gitu a pracovat s nimi na GitHubu. <\/p>\n

<\/p>\n

Dokumentace komponent: Docz, Storybook a Styleguidist<\/h2>\n

<\/p>\n

Sm\u011brnice, designov\u00e9 syst\u00e9my, knihovny komponent \u2014 a\u0165 u\u017e je naz\u00fdv\u00e1te jakkoli, staly se v posledn\u00ed dob\u011b velmi popul\u00e1rn\u00edmi. Vznik komponentov\u00fdch framework\u016f, jako je React a n\u00e1stroje zm\u00edn\u011bn\u00e9 zde \u2014 umo\u017enily je prom\u011bnit z marniv\u00fdch projekt\u016f na u\u017eite\u010dn\u00e9 n\u00e1stroje. <\/p>\n

<\/p>\n

Storybook, Docz a Styleguidist d\u011blaj\u00ed tot\u00e9\u017e: zobrazuj\u00ed interaktivn\u00ed prvky a dokumentuj\u00ed jejich API. Projekt m\u016f\u017ee m\u00edt des\u00edtky nebo dokonce stovky komponent \u2014 v\u0161echny s r\u016fzn\u00fdmi stavy a styly. Pokud chcete, aby se komponenty pou\u017e\u00edvaly opakovan\u011b, lid\u00e9 mus\u00ed v\u011bd\u011bt, \u017ee existuj\u00ed. K tomu sta\u010d\u00ed katalogizovat komponenty. Sm\u011brnice poskytuj\u00ed snadno vyhledateln\u00fd p\u0159ehled v\u0161ech va\u0161ich komponent. To pom\u00e1h\u00e1 udr\u017eovat vizu\u00e1ln\u00ed konzistenci a vyhnout se opakovan\u00e9 pr\u00e1ci.<\/p>\n

<\/p>\n

Tyto n\u00e1stroje poskytuj\u00ed pohodln\u00fd zp\u016fsob, jak prohl\u00ed\u017eet r\u016fzn\u00e9 stavy. M\u016f\u017ee b\u00fdt obt\u00ed\u017en\u00e9 reprodukovat ka\u017ed\u00fd stav komponenty v kontextu skute\u010dn\u00e9 aplikace. M\u00edsto prokliku p\u0159es skute\u010dnou aplikaci je lep\u0161\u00ed vyvinout samostatnou komponentu. Lze modelovat obt\u00ed\u017en\u011b p\u0159\u00edstupn\u00e9 stavy (nap\u0159\u00edklad stav na\u010d\u00edt\u00e1n\u00ed). <\/p>\n

<\/p>\n

Vedle vizu\u00e1ln\u00edho zobrazen\u00ed r\u016fzn\u00fdch stav\u016f a seznamu vlastnost\u00ed je \u010dasto nutn\u00e9 napsat obecn\u00fd popis obsahu \u2014 od\u016fvodn\u011bn\u00ed designu, p\u0159\u00edpady pou\u017eit\u00ed nebo popis v\u00fdsledk\u016f u\u017eivatelsk\u00e9ho testov\u00e1n\u00ed. Markdown je velmi snadn\u00fd na nau\u010den\u00ed \u2014 ide\u00e1ln\u011b by m\u011bl b\u00fdt pr\u016fvodce spole\u010dn\u00fdm zdrojem pro design\u00e9ry a v\u00fdvoj\u00e1\u0159e. Docz, Styleguidist a Storybook nab\u00edzej\u00ed zp\u016fsob snadn\u00e9ho m\u00edch\u00e1n\u00ed Markdownu s komponenty.<\/p>\n

<\/p>\n

Docz<\/h2>\n

<\/p>\n

Moment\u00e1ln\u011b Docz pracuje pouze s React, ale prob\u00edh\u00e1 aktivn\u00ed v\u00fdvoj podpory pro Preact, Vue a webov\u00e9 komponenty. Docz je nejnov\u011bj\u0161\u00ed z t\u011bchto t\u0159\u00ed n\u00e1stroj\u016f, ale na Githubu z\u00edskal v\u00edce ne\u017e 14 000 hv\u011bzdi\u010dek. Docz p\u0159edstavuje dva komponenty \u2014 <Playground><\/code> a < Props ><\/code>. Tyto komponenty se importuj\u00ed a pou\u017e\u00edvaj\u00ed v souborech .mdx<\/code>. <\/p>\n

<\/p>\n

import { Playground, Props } from \"docz\";\nimport Button from \"..\\\/src\\\/Button\";\n\n## M\u016f\u017eete _ps\u00e1t_ **markdown**\n### M\u016f\u017eete importovat a pou\u017e\u00edvat komponenty\n\n