{"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\/sl\/blog\/administrirovanie\/zhivye-gajdlajny-mdx-i-drugie-frejmvorki","title":{"rendered":"\u017divi smernice \u2014 MDX in drugi okviri","gt_translate_keys":[{"key":"rendered","format":"text"}]},"content":{"rendered":"

Mo\u017eete imati najbolji projekat sa otvorenim kodom, ali ako nema dobre dokumentacije, postoji rizik da nikada ne uspe. U kancelariji, dobra dokumentacija omogu\u0107ava vam da ne odgovarate na ista pitanja iznova. Dokumentacija tako\u0111e garantuje da ljudi mogu razumeti projekat, \u010dak i ako klju\u010dni zaposleni napuste kompaniju ili se uloge promene. \u017divi vodi\u010di poma\u017eu da se osigura integritet podataka. <\/p>\n

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

Ako morate da napi\u0161ete du\u017ei tekst, Markdown je odli\u010dna alternativa HTML-u. Ponekad Markdown sintaksa nije dovoljna. U tom slu\u010daju mo\u017eemo koristiti HTML unutar njega. Na primer, prilago\u0111eni elementi. Tako da, ako gradite dizajn sistem sa nativnim web komponentama, lako ih je uklju\u010diti u tekstualnu dokumentaciju. Ako koristite React (ili bilo koji drugi JSX okvir, poput Preact ili Vue), mo\u017eete u\u010diniti isto pomo\u0107u MDX-a. <\/p>\n

<\/p>\n

Ovaj \u010dlanak je \u0161irok pregled alata za pisanje dokumentacije i izradu vodi\u010da. Nisu svi alati navedeni ovde koristili MDX, ali se sve vi\u0161e uklju\u010duje u alate za dokumentovanje.<\/p>\n

<\/p>\n

\u0160ta je MDX?<\/h2>\n

<\/p>\n

unutar svakog kontejnera prema zadanim postavkama \u0107e izgledati ovako: .mdx<\/code> ima enak sintaksis kot Markdown, vendar omogo\u010da uvoz interaktivnih komponent JSX in njihovo vklju\u010ditev v va\u0161o vsebino. Podpora za komponente Vue je \u0161e v alfa fazi. Da za\u010dnete delati z MDX, preprosto namestite \u201eCreate React App\u201c. Obstajajo tudi vti\u010dniki za Next.js in Gatsby. Naslednja razli\u010dica Docusaurus (razli\u010dica 2) bo imela tudi vgrajeno podporo.<\/p>\n

<\/p>\n

Pisanje dokumentacije sa Docusaurusom<\/h2>\n

<\/p>\n

Docusaurus je razvijen u Facebooku. Koriste ga u svakom projektu sa otvorenim kodom, osim u Reactu. Van kompanije ga koriste Redux, Prettier, Gulp i Babel.<\/p>\n

<\/p>\n

\"\u017diviProjekti koji koriste Docusaurus.<\/em><\/p>\n

<\/p>\n

Docusaurus se mo\u017ee koristiti za pisanje katerikoli<\/em> dokumentacije, ne samo za opis frontenda. Ispod haube se nalazi React, ali nije potrebno biti upoznat s njim da biste ga koristili. Uzimaju\u0107i va\u0161e Markdown fajlove, uz malu dozu magije, dobro strukturirana, formatirana i \u010ditka dokumentacija sa lepim dizajnom je spremna. <\/p>\n

<\/p>\n

\"\u017divi
\nNa sajtu Redux mo\u017eete videti standardni \u0161ablon Docusaurus.<\/em><\/p>\n

<\/p>\n

Spletne strani, ustvarjene z Docusaurusom, lahko vklju\u010dujejo tudi blog, ki temelji na Markdownu. Za poudarjanje sintakse je takoj povezan Prism.js. \u010ceprav se je Docusaurus pojavila razmeroma nedavno, so ga na StackShareu priznali za najbolj\u0161e orodje leta 2018. <\/p>\n

<\/p>\n

Druge mo\u017enosti za ustvarjanje vsebine<\/h2>\n

<\/p>\n

Docusaurus je posebej zasnovan za izdelavo dokumentacije. Seveda obstaja milijon in en na\u010din za izdelavo spletne strani \u2014 lahko zgradite svojo re\u0161itev v katerem koli jeziku, CMS-ju ali uporabite generator stati\u010dnih spletnih strani.<\/p>\n

<\/p>\n

Na primer, dokumentacija za React, oblikovna sistema IBM, Apollo in Ghost CMS uporabljajo Gatsby \u2014 to je generator stati\u010dnih spletnih strani, ki se pogosto uporablja za bloge. \u010ce delate z Vue, bo VuePress dobra izbira za vas. Druga mo\u017enost je uporaba generatorja, napisanega v Pythonu \u2014 MkDocs. Ta je odprtokoden in ga konfigurirate s pomo\u010djo enega YAML datoteke. GitBook je prav tako dobra izbira, a je brezpla\u010den le za odprte in nekomercialne ekipe. Lahko tudi preprosto nalo\u017eite markdown datoteke, uporabite git in z njimi delate na Githubu. <\/p>\n

<\/p>\n

Dokumentiranje komponent: Docz, Storybook in Styleguidist<\/h2>\n

<\/p>\n

Smernice, oblikovne sisteme, knji\u017enice komponent \u2014 kako koli jih poimenujete, so v zadnjem \u010dasu postale zelo priljubljene. Pojav komponentnih okvirjev, kot je React, in tu omenjenih orodij \u2014 je omogo\u010dil, da so se spremenili iz praznovalnih projektov v koristna orodja. <\/p>\n

<\/p>\n

Storybook, Docz in Styleguidist \u2014 delujejo na enak na\u010din: prikazujejo interaktivne elemente in dokumentirajo njihovo API. Projekt ima lahko na desetine ali celo stotine komponent \u2014 vse z razli\u010dnimi stanji in slogi. \u010ce \u017eelite, da se komponente ponovno uporabljajo, morajo ljudje vedeti, da obstajajo. Za to je dovolj, da katalogizirate komponente. Smernice ponujajo enostaven pregled vseh va\u0161ih komponent, kar pomaga pri ohranjanju vizualne doslednosti in izogibanju ponovnemu delu.<\/p>\n

<\/p>\n

Ta orodja ponujajo enostaven na\u010din za ogled razli\u010dnih stanj. Morda je te\u017eko reproducirati vsako stanje komponente v kontekstu prave aplikacije. Namesto da bi klikali po pravi aplikaciji, je bolje razviti lo\u010deno komponento. Lahko modelirate te\u017eko dostopna stanja (na primer stanje nalaganja). <\/p>\n

<\/p>\n

Poleg vizualne predstavitve razli\u010dnih stanj in seznama lastnosti je pogosto potrebno napisati splo\u0161ni opis vsebine - utemeljitev za oblikovanje, primere uporabe ali opis rezultatov uporabni\u0161kega testiranja. Markdown je zelo enostaven za u\u010denje - idealno bi morali biti smernice skupni vir za oblikovalce in razvijalce. Docz, Styleguidist in Storybook ponujajo na\u010din enostavnega me\u0161anja Markdowna s komponentami.<\/p>\n

<\/p>\n

Docz<\/h2>\n

<\/p>\n

Trenutno Docz deluje samo z Reactom, vendar so v teku intenzivna dela za podporo Preactu, Vueu in spletnim komponentam. Docz je najnovej\u0161i od treh orodij, a je na Githubu uspel zbrati ve\u010d kot 14.000 zvezdic. Docz predstavlja dve komponenti - <Playground><\/code> in < Props ><\/code>. Importe in se uporabljajo v datotekah .mdx<\/code>. <\/p>\n

<\/p>\n

import { Playground, Props } from \"docz\";\nimport Button from \"..\\\/src\\\/Button\";\n\n## You can _write_ **markdown**\n### You can import and use components\n\n