{"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\/et\/blog\/administrirovanie\/zhivye-gajdlajny-mdx-i-drugie-frejmvorki","title":{"rendered":"Elavad juhised - MDX ja teised raamistikud","gt_translate_keys":[{"key":"rendered","format":"text"}]},"content":{"rendered":"

Teie avatud l\u00e4htekoodiga projekt v\u00f5ib olla suurep\u00e4rane, kuid kui tal puudub hea dokumentatsioon, on t\u00f5en\u00e4olisus, et ta kunagi ei \u00f5nnestu. Hea dokumentatsioon kontoris aitab v\u00e4ltida pidevat samu k\u00fcsimusi. Samuti tagab dokumentatsioon, et inimesed saavad projektist aru, isegi kui v\u00f5tmeisikud lahkuvad ettev\u00f5ttest v\u00f5i rollid muutuvad. Elavad juhised aitavad tagada andmete j\u00e4rjepidevuse. <\/p>\n

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

Kui peate kirjutama pika teksti, on Markdown suurep\u00e4rane alternatiiv HTML-ile. M\u00f5nikord ei piisa Markdowni s\u00fcntaksist. Sellisel juhul saame kasutada HTML-i selle sees. N\u00e4iteks kohandatud elemendid. Seega, kui loote disainis\u00fcsteemi koos natiivsete veebikomponentidega, on neid lihtne oma tekstidokumentatsioonis kasutada. Kui kasutate Reacti (v\u00f5i m\u00f5nda muud JSX raamistikku, n\u00e4iteks Preact v\u00f5i Vue), saate sama teha MDX abil. <\/p>\n

<\/p>\n

See artikkel on lai \u00fclevaade dokumentatsiooni kirjutamise ja juhendite loomiseks m\u00f5eldud t\u00f6\u00f6riistadest. Mitte k\u00f5ik siin loetletud t\u00f6\u00f6riistad ei kasuta MDX-i, kuid see muutub \u00fcha sagedamini dokumenteerimisvahendites.<\/p>\n

<\/p>\n

Mis on MDX?<\/h2>\n

<\/p>\n

Fail .mdx<\/code> \u0438\u043c\u0435\u0435\u0442 \u0442\u043e\u0442 \u0436\u0435 \u0441\u0438\u043d\u0442\u0430\u043a\u0441\u0438\u0441 \u0447\u0442\u043e \u0438 Markdown, \u043d\u043e \u043f\u043e\u0437\u0432\u043e\u043b\u044f\u0435\u0442 \u0438\u043c\u043f\u043e\u0440\u0442\u0438\u0440\u043e\u0432\u0430\u0442\u044c \u0438\u043d\u0442\u0435\u0440\u0430\u043a\u0442\u0438\u0432\u043d\u044b\u0435 \u043a\u043e\u043c\u043f\u043e\u043d\u0435\u043d\u0442\u044b JSX \u0438 \u0432\u0441\u0442\u0440\u0430\u0438\u0432\u0430\u0442\u044c \u0438\u0445 \u0432 \u0432\u0430\u0448 \u043a\u043e\u043d\u0442\u0435\u043d\u0442. \u041f\u043e\u0434\u0434\u0435\u0440\u0436\u043a\u0430 \u043a\u043e\u043c\u043f\u043e\u043d\u0435\u043d\u0442\u043e\u0432 Vue \u043d\u0430\u0445\u043e\u0434\u0438\u0442\u044c\u0441\u044f \u0432 \u0430\u043b\u044c\u0444\u0435. \u0414\u043b\u044f \u0442\u043e\u0433\u043e, \u0447\u0442\u043e\u0431\u044b \u043d\u0430\u0447\u0430\u0442\u044c \u0440\u0430\u0431\u043e\u0442\u0430\u0442\u044c \u0441 MDX, \u0434\u043e\u0441\u0442\u0430\u0442\u043e\u0447\u043d\u043e \u0443\u0441\u0442\u0430\u043d\u043e\u0432\u0438\u0442\u044c «Create React App». \u0415\u0441\u0442\u044c \u043f\u043b\u0430\u0433\u0438\u043d\u044b \u0434\u043b\u044f Next.js \u0438 Gatsby. \u0421\u043b\u0435\u0434\u0443\u044e\u0449\u0430\u044f \u0432\u0435\u0440\u0441\u0438\u044f Docusaurus (\u0432\u0435\u0440\u0441\u0438\u044f 2) \u0442\u0430\u043a\u0436\u0435 \u0431\u0443\u0434\u0435\u0442 \u0438\u043c\u0435\u0442\u044c \u0432\u0441\u0442\u0440\u043e\u0435\u043d\u043d\u0443\u044e \u043f\u043e\u0434\u0434\u0435\u0440\u0436\u043a\u0443.<\/p>\n

<\/p>\n

Dokumentatsiooni kirjutamine Docusaurusega<\/h2>\n

<\/p>\n

Docusauruse l\u00f5i Facebook. Nad kasutavad seda iga avatud l\u00e4htekoodiga projekti puhul, v\u00e4lja arvatud React. V\u00e4ljaspool ettev\u00f5tet kasutavad seda Redux, Prettier, Gulp ja Babel.<\/p>\n

<\/p>\n

\"ElavadProjektid, mis kasutavad Docusaurust.<\/em><\/p>\n

<\/p>\n

Docusaurust saab kasutada dokumentatsiooni kirjutamiseks, mitte ainult frontendi kirjeldamiseks. Selle all on React, kuid selle kasutamiseks ei ole h\u00e4davajalik sellega tuttav olla. See v\u00f5tab teie Markdown-failid, veidi maagiat ja h\u00e4sti struktureeritud, vormindatud ning loetav dokumentatsioon kauni disainiga on valmis. (m\u00f5elgem k\u00f5rgesse ametisse olevatele inimestele), siis on see halb<\/em> Reduxi saidilt saab vaadata Docusauruse standardset \u0161ablooni. <\/p>\n

<\/p>\n

\"Elavad
\nReduxi veebisaidilt on v\u00f5imalik n\u00e4ha Docusauruse standardset \u0161ablooni.<\/em><\/p>\n

<\/p>\n

Docusaurusiga loodud saidid v\u00f5ivad sisaldada ka Markdownip\u00f5hist blogi. S\u00fcntaksi esilet\u00f5stmiseks on juba \u00fchendatud Prism.js. Kuigi Docusaurus on suhteliselt uus, tunnustati seda 2018. aasta parima t\u00f6\u00f6riistana StackShare'is. <\/p>\n

<\/p>\n

Teised sisuloomise v\u00f5imalused<\/h2>\n

<\/p>\n

Docusaurus on spetsiaalselt loodud dokumentatsiooni loomiseks. Loomulikult on miljon ja \u00fcks v\u00f5imalus veebisaidi loomiseks \u2014 saate v\u00e4lja arendada oma lahenduse igasugustes keeltes, CMS-ides v\u00f5i kasutada staatilise saidi genereerijat.<\/p>\n

<\/p>\n

N\u00e4iteks kasutavad Reacti dokumentatsioon, IBM-i disainis\u00fcsteem, Apollo ja Ghost CMS Gatsby't \u2014 see on staatiliste veebisaitide genereerija, mida sageli kasutatakse blogide jaoks. Kui t\u00f6\u00f6tate Vue'iga, on VuePress teile hea valik. Teine variant on kasutada Pythoni kirjutatud genereerijat \u2013 MkDocs. See on avatud ja konfigureeritav \u00fche YAML-failiga. GitBook on samuti hea variant, kuid see on tasuta vaid avatud ja mittetulunduslikele meeskondadele. Samuti saab lihtsalt laadida markdown-failid \u00fcles, kasutades git'i, ja nendega t\u00f6\u00f6tada GitHubis. <\/p>\n

<\/p>\n

Komponentide dokumenteerimine: Docz, Storybook ja Styleguidist<\/h2>\n

<\/p>\n

Juhised, disainis\u00fcsteemid, komponentide raamatukogud \u2014 olenemata sellest, kuidas te neid nimetate, on need viimasel ajal muutunud v\u00e4ga populaarseks. Komponentide raamistike, nagu React, ja siin mainitud t\u00f6\u00f6riistade ilmumine on muutnud need t\u00fchjadesse projektidesse kasulikeks t\u00f6\u00f6riistadeks. <\/p>\n

<\/p>\n

Storybook, Docz ja Styleguidist teevad k\u00f5ik sama: nad kuvavad interaktiivseid elemente ja dokumenteerivad nende API-d. Projekt v\u00f5ib sisaldada k\u00fcmneid v\u00f5i isegi sadu komponente \u2014 k\u00f5ik erinevate olekute ja stiilidega. Kui soovite, et komponente saab uuesti kasutada, peab olema selge, et need eksisteerivad. Selleks piisab komponentide kataloogist. Juhised pakuvad mugavat \u00fclesehitust, et n\u00e4ha k\u00f5iki teie komponente. See aitab s\u00e4ilitada visuaalset j\u00e4rjepidevust ja v\u00e4ltida korduvat t\u00f6\u00f6d.<\/p>\n

<\/p>\n

Need t\u00f6\u00f6riistad pakuvad mugavat viisi erinevate olekute vaatamiseks. Iga komponendi oleku taasilmutamine reaalses rakenduse kontekstis v\u00f5ib olla keeruline. Selle asemel, et kl\u00f5psata reaalses rakenduses, on m\u00f5istlik v\u00e4lja t\u00f6\u00f6tada eraldi komponent. Saate mudelida raskesti ligip\u00e4\u00e4setavaid olekuid (n\u00e4iteks laadimisolekut). <\/p>\n

<\/p>\n

Koos visuaalse esituse erinevate olekute ja omaduste loetelu, on sageli vajalik kirjutada sisu \u00fcldine kirjeldus \u2014 disaini \u00f5igustus, kasutusjuhud v\u00f5i kasutajate testimise tulemuste kirjeldus. Markdown on v\u00e4ga lihtne \u00f5ppida \u2014 ideaalis peaks juhend olema koost\u00f6\u00f6resurss disaineritele ja arendajatele. Docz, Styleguidist ja Storybook pakuvad v\u00f5imalust lihtsalt segada Markdowni komponente.<\/p>\n

<\/p>\n

Docz<\/h2>\n

<\/p>\n

Praegu toetab Docz ainult Reacti, kuid aktiivselt t\u00f6\u00f6tatakse Preacti, Vue ja veebikomponentide toe kallal. Docz on kolmest t\u00f6\u00f6riistast uusim, kuid on GitHubis kogunud \u00fcle 14 000 t\u00e4he. Docz esindab kahte komponenti \u2014 <Playground><\/code> ja < Props ><\/code>. Need imporditakse ja kasutatakse failides .mdx<\/code>. <\/p>\n

<\/p>\n

import { Playground, Props } from \"docz\";\nimport Button from \"..\\\/src\\\/Button\";\n\n## Sa v\u00f5id _kirjutada_ **markdowni**\n### Sa v\u00f5id importida ja kasutada komponente\n\n