{"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\/pl\/blog\/administrirovanie\/zhivye-gajdlajny-mdx-i-drugie-frejmvorki","title":{"rendered":"\u017bywe wytyczne \u2014 MDX i inne frameworki","gt_translate_keys":[{"key":"rendered","format":"text"}]},"content":{"rendered":"

Mo\u017cesz mie\u0107 najlepszy projekt z otwartym kodem \u017ar\u00f3d\u0142owym, ale je\u015bli nie ma on dobrej dokumentacji, istnieje ryzyko, \u017ce nigdy nie odniesie sukcesu. Dobra dokumentacja w biurze pozwoli unikn\u0105\u0107 zadawania tych samych pyta\u0144. Dokumentacja gwarantuje r\u00f3wnie\u017c, \u017ce ludzie mog\u0105 zrozumie\u0107 projekt, nawet je\u015bli kluczowi pracownicy opuszcz\u0105 firm\u0119 lub zmieni\u0105 si\u0119 role. \u017bywe wytyczne pomog\u0105 zapewni\u0107 integralno\u015b\u0107 danych. <\/p>\n

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

Je\u015bli musisz napisa\u0107 d\u0142ugi tekst, Markdown to doskona\u0142a alternatywa dla HTML. Czasami sk\u0142adni Markdown mo\u017ce by\u0107 za ma\u0142o. W takim przypadku mo\u017cemy u\u017cywa\u0107 HTML wewn\u0105trz niego. Na przyk\u0142ad, niestandardowe elementy. Dlatego, je\u015bli tworzysz system projektowania z natywnymi komponentami webowymi, \u0142atwo je w\u0142\u0105czy\u0107 do tekstowej dokumentacji. Je\u015bli u\u017cywasz React (lub jakiegokolwiek innego frameworka JSX, takiego jak Preact czy Vue), mo\u017cesz zrobi\u0107 to samo za pomoc\u0105 MDX. <\/p>\n

<\/p>\n

Ten artyku\u0142 to szeroki przegl\u0105d narz\u0119dzi do pisania dokumentacji i tworzenia wytycznych. Nie wszystkie narz\u0119dzia wymienione tutaj korzystaj\u0105 z MDX, ale jest on coraz cz\u0119\u015bciej w\u0142\u0105czany w narz\u0119dzia dokumentacyjne.<\/p>\n

<\/p>\n

Czym jest MDX?<\/h2>\n

<\/p>\n

Plik .mdx<\/code> ma taki sam\u0105 sk\u0142adni\u0119 jak Markdown, ale umo\u017cliwia importowanie interaktywnych komponent\u00f3w JSX i wbudowywanie ich w tre\u015b\u0107. Wsparcie dla komponent\u00f3w Vue znajduje si\u0119 w fazie alfa. Aby rozpocz\u0105\u0107 prac\u0119 z MDX, wystarczy zainstalowa\u0107 «Create React App». S\u0105 dost\u0119pne wtyczki do Next.js i Gatsby. Nast\u0119pna wersja Docusaurus (wersja 2) r\u00f3wnie\u017c b\u0119dzie mia\u0142a wbudowane wsparcie.<\/p>\n

<\/p>\n

Pisanie dokumentacji z Docusaurus<\/h2>\n

<\/p>\n

Docusaurus zosta\u0142 napisany przez Facebook. U\u017cywaj\u0105 go w ka\u017cdym projekcie z otwartym kodem \u017ar\u00f3d\u0142owym poza React. Poza firm\u0105 korzysta z niego Redux, Prettier, Gulp i Babel.<\/p>\n

<\/p>\n

\"\u017byweProjekty, kt\u00f3re u\u017cywaj\u0105 Docusaurus.<\/em><\/p>\n

<\/p>\n

Docusaurus mo\u017cna u\u017cywa\u0107 do pisania przez kogokolwiek<\/em> dokumentacji, nie tylko do opisu front-endu. Ma pod mask\u0105 React, ale nie trzeba mie\u0107 z nim styczno\u015bci, aby go u\u017cywa\u0107. Przekszta\u0142ca Twoje pliki Markdown, dodaje troch\u0119 magii i gotowa jest dobrze zorganizowana, sformatowana i czytelna dokumentacja z pi\u0119knym designem. <\/p>\n

<\/p>\n

\"\u017bywe
\nNa stronie Redux mo\u017cna zobaczy\u0107 standardowy szablon Docusaurus.<\/em><\/p>\n

<\/p>\n

Strony stworzone za pomoc\u0105 Docusaurus mog\u0105 r\u00f3wnie\u017c obejmowa\u0107 bloga opartego na Markdown. Do pod\u015bwietlania sk\u0142adni od razu zainstalowano Prism.js. Mimo \u017ce Docusaurus pojawi\u0142 si\u0119 stosunkowo niedawno, zosta\u0142 uznany za najlepsze narz\u0119dzie 2018 roku na StackShare. <\/p>\n

<\/p>\n

Inne opcje tworzenia tre\u015bci<\/h2>\n

<\/p>\n

Docusaurus zosta\u0142 specjalnie zaprojektowany do tworzenia dokumentacji. Oczywi\u015bcie istnieje milion i jeden spos\u00f3b na stworzenie strony \u2014 mo\u017cesz wdro\u017cy\u0107 w\u0142asne rozwi\u0105zanie w dowolnym j\u0119zyku, CMS lub skorzysta\u0107 z generatora statycznych stron.<\/p>\n

<\/p>\n

Na przyk\u0142ad dokumentacja dla React, system designu IBM, Apollo i Ghost CMS korzystaj\u0105 z Gatsby \u2014 to generator statycznych stron, kt\u00f3ry cz\u0119sto jest u\u017cywany do blog\u00f3w. Je\u015bli pracujesz z Vue, VuePress b\u0119dzie dobrym wyborem. Inn\u0105 opcj\u0105 jest u\u017cycie generatora napisanego w Pythonie \u2014 MkDocs. Jest to rozwi\u0105zanie otwarte i konfigurowane za pomoc\u0105 jednego pliku YAML. GitBook r\u00f3wnie\u017c jest niez\u0142ym rozwi\u0105zaniem, ale jest bezp\u0142atny tylko dla otwartych i niekomercyjnych zespo\u0142\u00f3w. Mo\u017cna r\u00f3wnie\u017c po prostu przesy\u0142a\u0107 pliki markdown, korzystaj\u0105c z gita, i pracowa\u0107 z nimi w Githubie. <\/p>\n

<\/p>\n

Dokumentowanie komponent\u00f3w: Docz, Storybook i Styleguidist<\/h2>\n

<\/p>\n

Wytyczne, systemy designu, biblioteki komponent\u00f3w \u2014 niezale\u017cnie od tego, jak je nazwiesz, sta\u0142y si\u0119 one ostatnio bardzo popularne. Pojawienie si\u0119 komponentowych framework\u00f3w, takich jak React, oraz narz\u0119dzi wymienionych tutaj, pozwoli\u0142o przekszta\u0142ci\u0107 je z pr\u00f3\u017cno\u015bciowych projekt\u00f3w w u\u017cyteczne narz\u0119dzia. <\/p>\n

<\/p>\n

Storybook, Docz i Styleguidist robi\u0105 to samo: wy\u015bwietlaj\u0105 interaktywne elementy i dokumentuj\u0105 ich API. Projekt mo\u017ce mie\u0107 dziesi\u0105tki, a mo\u017ce nawet setki komponent\u00f3w \u2014 ka\u017cdy z r\u00f3\u017cnymi stanami i stylami. Je\u015bli chcesz, aby komponenty by\u0142y u\u017cywane wielokrotnie, ludzie musz\u0105 wiedzie\u0107, \u017ce istniej\u0105. Wystarczy zinwentaryzowa\u0107 komponenty. Wytyczne zapewniaj\u0105 \u0142atwy do przeszukiwania przegl\u0105d wszystkich twoich komponent\u00f3w. Pomaga to w utrzymaniu wizualnej sp\u00f3jno\u015bci i unikaniu ponownej pracy.<\/p>\n

<\/p>\n

Te narz\u0119dzia oferuj\u0105 wygodny spos\u00f3b przegl\u0105dania r\u00f3\u017cnych stan\u00f3w. Mo\u017ce by\u0107 trudno odtworzy\u0107 ka\u017cde wyst\u0105pienie komponentu w kontek\u015bcie rzeczywistej aplikacji. Zamiast klika\u0107 w rzeczywiste aplikacje, warto zaprojektowa\u0107 osobny komponent. Mo\u017cna modelowa\u0107 trudne do uchwycenia stany (na przyk\u0142ad stan \u0142adowania). <\/p>\n

<\/p>\n

Wraz z wizualn\u0105 prezentacj\u0105 r\u00f3\u017cnych stan\u00f3w oraz list\u0105 w\u0142a\u015bciwo\u015bci, cz\u0119sto konieczne jest napisanie og\u00f3lnego opisu tre\u015bci \u2013 uzasadnienia designu, przypadk\u00f3w u\u017cycia lub opisu wynik\u00f3w test\u00f3w u\u017cytkownik\u00f3w. Markdown jest bardzo prosty do nauki \u2013 idealnie, gdyby wytyczne by\u0142y wsp\u00f3lnym zasobem dla projektant\u00f3w i deweloper\u00f3w. Docz, Styleguidist oraz Storybook oferuj\u0105 mo\u017cliwo\u015b\u0107 \u0142atwego \u0142\u0105czenia Markdown z komponentami.<\/p>\n

<\/p>\n

Docz<\/h2>\n

<\/p>\n

Docz obecnie dzia\u0142a tylko z React, ale s\u0105 aktywne prace nad wsparciem dla Preact, Vue oraz komponent\u00f3w webowych. Docz jest najnowszym z trzech narz\u0119dzi, ale na Githubie zdoby\u0142 ponad 14 000 gwiazdek. Docz reprezentuje dwa komponenty \u2014 <Playground><\/code> i < Props ><\/code>. S\u0105 one importowane i u\u017cywane w plikach .mdx<\/code>. <\/p>\n

<\/p>\n

import { Playground, Props } from \"docz\";\nimport Button from \"..\\\/src\\\/Button\";\n\n## Mo\u017cesz _pisa\u0107_ **markdown**\n### Mo\u017cesz importowa\u0107 i u\u017cywa\u0107 komponent\u00f3w\n\n