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

Mo\u017eete imati najbolji projekt s otvorenim kodom, ali ako nema dobre dokumentacije, postoji mogu\u0107nost da nikada ne uspe. Dobra dokumentacija u uredu omogu\u0107ava vam da ne odgovarate na ista pitanja iznova. Tako\u0111e osigurava da ljudi mogu razumeti projekat ako klju\u010dni zaposleni napuste kompaniju ili se promene uloge. \u017dive smernice poma\u017eu u o\u010duvanju integriteta podataka. <\/p>\n

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

Ako trebate napisati dugi 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\u0111ene elemente. Stoga, ako gradite dizajn sistem s nativnim web komponentama, lako ih je uklju\u010diti u tekstualnu dokumentaciju. Ako koristite React (ili bilo koji drugi JSX okvir, kao \u0161to su Preact ili Vue), mo\u017eete u\u010diniti isto koriste\u0107i MDX. <\/p>\n

<\/p>\n

Ovo je \u010dlanak \u2014 \u0161irok pregled alata za pisanje dokumentacije i kreiranje smernica. Nisu svi alati navedeni ovde utemeljeni na MDX-u, ali se sve vi\u0161e uklju\u010duju u alate za dokumentaciju.<\/p>\n

<\/p>\n

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

<\/p>\n

Datoteka .mdx<\/code> ima istu sintaksu kao i Markdown, ali omogu\u0107uje uvoz interaktivnih JSX komponenti i njihovo ugra\u0111ivanje u va\u0161 sadr\u017eaj. Podpora za Vue komponente je trenutno u alfa fazi. Da biste zapo\u010deli rad s MDX-om, dovoljno je instalirati «Create React App». Postoje dodaci za Next.js i Gatsby. Sljede\u0107a verzija Docusaurusa (verzija 2) tako\u0111er \u0107e imati ugra\u0111enu podr\u0161ku.<\/p>\n

<\/p>\n

Pisanje dokumentacije s Docusaurus-om<\/h2>\n

<\/p>\n

Docusaurus su razvili u Facebooku. Koriste ga u svakom projektu s otvorenim kodom, osim Reacta. Osim kompanije, koristi ga 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 bilo koje<\/em> dokumentacije, ne samo za opisivanje frontenda. U osnovi ima React, ali nije potrebno biti upoznat s njim da biste ga koristili. Uzimaju va\u0161e Markdown datoteke, prstohvat magije i dobro strukturirana, formatirana i \u010ditljiva dokumentacija s lepim dizajnom je spremna. <\/p>\n

<\/p>\n

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

<\/p>\n

Web stranice stvorene pomo\u0107u Docusaurusa tako\u0111er mogu uklju\u010divati blog temeljen na Markdownu. Za isticanje sintakse odmah je uklju\u010den Prism.js. Iako je Docusaurus relativno nov alat, progla\u0161en je najboljim alatom 2018. godine na StackShareu. <\/p>\n

<\/p>\n

Ostale opcije za izradu sadr\u017eaja<\/h2>\n

<\/p>\n

Docusaurus je posebno dizajniran za izradu dokumentacije. Naravno, postoji milijun i jedan na\u010din za izradu web stranice \u2013 mo\u017eete pokrenuti svoje rje\u0161enje na bilo kojem jeziku, CMS-u ili iskoristiti generator stati\u010dkih stranica.<\/p>\n

<\/p>\n

Na primjer, dokumentacija za React, dizajnerski sustav IBM-a, Apollo i Ghost CMS koriste Gatsby \u2013 to je generator stati\u010dkih stranica koji se \u010desto koristi za blogove. Ako radite s Vue-om, VuePress \u0107e biti dobra opcija za vas. Druga opcija je koristiti generator napisan na Pythonu \u2013 MkDocs. On je otvoren i konfigurira se pomo\u0107u jednog YAML datoteke. GitBook je tako\u0111er dobar izbor, ali je besplatan samo za otvorene i neprofitne timove. Tako\u0111er, mo\u017eete jednostavno u\u010ditati markdown datoteke koriste\u0107i git i raditi s njima na GitHubu. <\/p>\n

<\/p>\n

Dokumentiranje komponenata: Docz, Storybook i Styleguidist<\/h2>\n

<\/p>\n

Smjernice, dizajnerski sustavi, biblioteke komponenti \u2013 bez obzira kako ih nazvali, postali su vrlo popularni u posljednje vrijeme. Pojava komponentnih okvira, poput React-a i alata spomenutih ovdje, omogu\u0107ila je da se oni pretvore iz ispraznih projekata u korisne alate. <\/p>\n

<\/p>\n

Storybook, Docz i Styleguidist rade isto: prikazuju interaktivne elemente i dokumentiraju njihov API. Projekt mo\u017ee imati desetke ili stotine komponenti \u2013 sve s razli\u010ditim stanjem i stilovima. Ako \u017eelite da se komponente ponovno koriste, ljudi moraju znati da postoje. Za to je dovoljno katalogizirati komponente. Smjernice pru\u017eaju pregled svih va\u0161ih komponenti koji se lako pretra\u017euje. To poma\u017ee odr\u017eavanju vizualne dosljednosti i izbjegavanju ponovnog rada.<\/p>\n

<\/p>\n

Ovi alati pru\u017eaju jednostavan na\u010din za pregled razli\u010ditih stanja. Mo\u017ee biti te\u0161ko reproducirati svako stanje komponente u kontekstu stvarne aplikacije. Umjesto da se klik\u0107e po stvarnoj aplikaciji, bolje je razviti posebnu komponentu. Mo\u017ee se simulirati te\u0161ko dostupna stanja (npr. stanje u\u010ditavanja). <\/p>\n

<\/p>\n

Uz vizualnu demonstraciju razli\u010ditih stanja i popis svojstava, \u010desto je potrebno napisati op\u0107e opisno sadr\u017eaj \u2014 opravdanje dizajna, primjere kori\u0161tenja ili opis rezultata korisni\u010dkog testiranja. Markdown je vrlo jednostavan za nau\u010diti \u2014 idealno, smjernice bi trebale biti zajedni\u010dki resurs za dizajnere i programere. Docz, Styleguidist i Storybook nude na\u010din lakog mije\u0161anja Markdowna s komponentama.<\/p>\n

<\/p>\n

Docz<\/h2>\n

<\/p>\n

Trenutno Docz radi samo s React, ali se aktivno radi na podr\u0161ci za Preact, Vue i web komponente. Docz je najnoviji od ta tri alata, no na Githubu je uspio prikupiti vi\u0161e od 14.000 zvijezda. Docz predstavlja dvije komponente \u2014 <Playground><\/code> i < Props ><\/code>. One se uvoze i koriste u datotekama .mdx<\/code>. <\/p>\n

<\/p>\n

import { Playground, Props } from \"docz\";\nimport Button from \"..\\\/src\\\/Button\";\n\n## Mo\u017eete _pisati_ **markdown**\n### Mo\u017eete uvesti i koristiti komponente\n\n