{"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 \u2014 MDX ja muud raamistikke","gt_translate_keys":[{"key":"rendered","format":"text"}]},"content":{"rendered":"

Teie projekt v\u00f5ib olla parim avatud koodiga, kuid kui sellel puudub korralik dokumentatsioon, on t\u00f5en\u00e4oline, et see ei \u00f5nnestu kunagi. Head dokumentatsioon b\u00fcroos aitab v\u00e4ltida sama k\u00fcsimuse korduvat esitamist. Dokumentatsioon tagab ka, et inimesed saavad projektiga hakkama, isegi kui v\u00f5tmem\u00e4ngijad lahkuvad ettev\u00f5ttest v\u00f5i rollid muutuvad. Elavad juhised aitavad andmete terviklikkust tagada. <\/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. Sel juhul saame selle sees kasutada HTML-i. N\u00e4iteks kohandatud elemendid. Seega, kui ehitate disainis\u00fcsteemi kohalike veebikomponentidega, on neid lihtne lisada tekstidokumentatsiooni. Kui kasutate Reacti (v\u00f5i m\u00f5nda muud JSX raamistiku, nagu Preact v\u00f5i Vue), saate sama teha MDX abil. <\/p>\n

<\/p>\n

See artikkel on ulatuslik \u00fclevaade dokumentatsioonit\u00f6\u00f6riistadest ja juhiste koostamisest. Mitte k\u00f5ik siin loetletud t\u00f6\u00f6riistad ei kasuta MDX-i, kuid see lisandub \u00fcha sagedamini dokumenteerimist\u00f6\u00f6riistadesse.<\/p>\n

<\/p>\n

Mis on MDX?<\/h2>\n

<\/p>\n

File .mdx<\/code> kasutab sama s\u00fcntaksit nagu Markdown, kuid v\u00f5imaldab importida interaktiivseid JSX-komponente ja sisestada neid teie sisusse. Vue komponentide tugi on praegu alfa staadiumis. MDX-iga alustamiseks piisab 'Create React App' installimisest. Olemas on pluginad Next.js ja Gatsby jaoks. Docusauruse j\u00e4rgmine versioon (versioon 2) toetab samuti sisseehitatud tuge.<\/p>\n

<\/p>\n

Dokumentatsiooni kirjutamine Docusaurus'e abil<\/h2>\n

<\/p>\n

Docusaurus'e on kirjutanud Facebook. Nad kasutavad seda igas avatud l\u00e4htekoodiga projektis, v\u00e4lja arvatud React'i puhul. V\u00e4ljaspoole ettev\u00f5tte kasutatakse seda Redux'i, Prettier'i, Gulp'i ja Babel'i jaoks.<\/p>\n

<\/p>\n

\"ElavadProjektid, mis kasutavad Docusaurus'e.<\/em><\/p>\n

<\/p>\n

Docusaurus'e saab kasutada mitte ainult dokumentatsiooni alusena iga\u00fche<\/em> , vaid ka frontendi kirjeldamiseks. Selle all on React, kuid selle kasutamiseks ei ole tingimata vaja sellega tuttav olla. See v\u00f5tab teie Markdown failid, veidi maagiat ja korralik, h\u00e4sti struktureeritud ning loetav dokumentatsioon kauni disainiga on valmis. <\/p>\n

<\/p>\n

\"Elavad
\nRedux'i saidil saab vaadata Docusaurus'e standardset mall.<\/em><\/p>\n

<\/p>\n

Docusaurusega loodud saidid v\u00f5ivad sisaldada ka Markdown-p\u00f5hist p\u00e4eva. S\u00fcnktaksisoni esitlemiseks on kohe \u00fchendatud Prism.js. Kuigi Docusaurus ilmus suhteliselt hiljuti, tunnustati seda 2018. aasta parimaks t\u00f6\u00f6riistaks StackShare'il. <\/p>\n

<\/p>\n

Teised sisu loomise v\u00f5imalused<\/h2>\n

<\/p>\n

Docusaurus on spetsiaalselt v\u00e4lja t\u00f6\u00f6tatud dokumentatsiooni loomiseks. Loomulikult on olemas miljon ja \u00fcks viis saidi loomiseks \u2014 v\u00f5ite installida oma lahenduse mis tahes keeles, CMS-is v\u00f5i kasutada staatilise saidi generaatorit.<\/p>\n

<\/p>\n

N\u00e4iteks kasutavad Reacti dokumentatsioon, IBM-i disainis\u00fcsteem, Apollo ja Ghost CMS Gatsby't \u2014 see on staatiliste veebisaitide generaator, mida sageli kasutatakse blogide jaoks. Kui t\u00f6\u00f6tate Vue'iga, on VuePress teile hea variant. Teine v\u00f5imalus on kasutada Pythonis kirjutatud generaatorit \u2014 MkDocs. See on avatud ja konfigureeritav \u00fche YAML-faili kaudu. GitBook on samuti hea variant, kuid see on tasuta ainult avatud ja mittekaubanduslikele meeskondadele. Veel v\u00f5ite lihtsalt laadida mmarkdown-faile, kasutades giti, ja t\u00f6\u00f6tada nendega GitHubis. <\/p>\n

<\/p>\n

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

<\/p>\n

Guidelines, disainis\u00fcsteemid, komponente teegid \u2014 olenemata sellest, kuidas te neid nimetate, on need viimase ajal v\u00e4ga populaarsed. Komponentide raamistikud, n\u00e4iteks React, ja siinkohal mainitud t\u00f6\u00f6riistad on v\u00f5imaldanud neid tuua uhkete projektide seast kasulikeks t\u00f6\u00f6riistadeks. <\/p>\n

<\/p>\n

Storybook, Docz ja Styleguidist teevad \u00fchte ja sama: nad kuvavad interaktiivseid komponente ja dokumenteerivad nende API. Projekt v\u00f5ib sisaldada k\u00fcmneid v\u00f5i isegi sadu komponente \u2014 k\u00f5ik erinevate olekute ja stiilidega. Kui te soovite, et komponente kasutataks uuesti, peavad inimesed teadma, et need eksisteerivad. Selleks piisab komponentide katalogiseerimisest. G\u00fcdde lainid pakuvad h\u00f5lpsasti otsitavat \u00fclevaadet k\u00f5igist teie komponentidest. See aitab s\u00e4ilitada visuaalset konsistentsi ja v\u00e4ltida korduvat t\u00f6\u00f6d.<\/p>\n

<\/p>\n

Need to know all of your application's states quickly? These tools provide a convenient way to view various states. It can be challenging to recreate every component state in the context of a real application. Instead of clicking through a real app, it's worth developing a separate component. You can simulate hard-to-reach states (like loading state). <\/p>\n

<\/p>\n

In addition to visually demonstrating different states and listing properties, it\u2019s often necessary to write a general description of the content \u2014 design rationales, use cases, or results from user testing. Markdown is very easy to learn \u2014 ideally, the guidelines should be a collaborative resource for designers and developers. Docz, Styleguidist, and Storybook offer a way to easily mix Markdown with components.<\/p>\n

<\/p>\n

Docz<\/h2>\n

<\/p>\n

Currently, Docz only works with React, but active efforts are underway to support Preact, Vue, and web components. Docz is the freshest of the three tools, yet it has managed to gather over 14,000 stars on GitHub. Docz features two components \u2014 <Playground><\/code> ja < Props ><\/code>. They are imported and used in files. .mdx<\/code>. <\/p>\n

<\/p>\n

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