Miongozo ya kuishi - MDX na mifumo mingine

Unaweza kuwa na mradi bora wa chanzo wazi, lakini ikiwa hauna hati nzuri, kuna uwezekano kwamba hautawahi kuanza. Katika ofisi, nyaraka nzuri zitakuzuia kujibu maswali sawa mara kwa mara. Hati pia huhakikisha kuwa watu wanaweza kuelewa mradi ikiwa wafanyikazi wakuu wataacha kampuni au majukumu yatabadilika. Miongozo ya moja kwa moja husaidia kuhakikisha uadilifu wa data.

Ikiwa unahitaji kuandika maandishi marefu, Markdown ni mbadala mzuri kwa HTML. Wakati mwingine syntax ya Markdown haitoshi. Katika kesi hii, tunaweza kutumia HTML ndani yake. Kwa mfano, vipengele maalum. Kwa hiyo, ikiwa unajenga mfumo wa kubuni na vipengele vya asili vya wavuti, ni rahisi kuwajumuisha katika nyaraka za maandishi. Ikiwa unatumia React (au mfumo mwingine wowote wa JSX kama Preact au Vue), unaweza kufanya vivyo hivyo na MDX.

Nakala hii ni muhtasari mpana wa zana za kuandika nyaraka na kuunda mwongozo. Sio zana zote zilizoorodheshwa hapa zinazotumia MDX, lakini inazidi kujumuishwa katika zana za uhifadhi.

MDX ni nini?

file .mdx ina syntax sawa na Markdown lakini hukuruhusu kuagiza vijenzi shirikishi vya JSX na kuvipachika kwenye maudhui yako. Usaidizi wa vipengele vya Vue upo katika alpha. Ili kuanza kufanya kazi na MDX, ingiza tu "Unda Programu ya React". Kuna programu-jalizi za Next.js na Gatsby. Toleo linalofuata la Docusaurus (toleo la 2) pia litakuwa na usaidizi wa ndani.

Kuandika nyaraka na Docusaurus

Docusaurus aliandika kwenye Facebook. Wanaitumia kwenye kila mradi wa chanzo wazi isipokuwa React. Nje ya kampuni, Redux, Prettier, Gulp, na Babeli huitumia.

Miradi inayotumia Docusaurus.

Docusaurus inaweza kutumika kuandika yoyote hati, sio tu kwa kuelezea hali ya mbele. Ina React chini ya kofia, lakini sio lazima uifahamu ili kuitumia. Inachukua faili zako za Markdown, kichache cha uchawi na hati zilizoundwa vizuri, zilizoumbizwa na zinazosomeka zenye muundo mzuri ziko tayari.

Unaweza kuona kiolezo chaguo-msingi cha Docusaurus kwenye tovuti ya Redux.

Tovuti zilizojengwa kwa kutumia Docusaurus zinaweza pia kujumuisha blogu yenye msingi wa Markdown. Kwa kuangazia sintaksia, Prism.js imejumuishwa mara moja. Licha ya ukweli kwamba Docusaurus imeonekana hivi majuzi, ilitambuliwa kama zana bora zaidi ya 2018 kwenye StackShare.

Chaguo Nyingine za Uundaji wa Maudhui

Docusaurus imeundwa mahsusi kwa ajili ya kuunda hati. Bila shaka, kuna njia milioni na moja za kutengeneza tovuti - unaweza kupeleka suluhisho lako mwenyewe katika lugha yoyote, CMS, au kutumia jenereta ya tovuti tuli.

Kwa mfano, hati za React, mfumo wa usanifu wa IBM, Apollo, na Ghost CMS hutumia Gatsby, jenereta tuli ya tovuti inayotumiwa mara nyingi kwa blogu. Ikiwa unafanya kazi na Vue basi VuePress ni chaguo nzuri kwako. Chaguo jingine ni kutumia jenereta iliyoandikwa katika Python - MkDocs. Imefunguliwa na kusanidiwa kwa faili moja ya YAML. GitBook pia ni chaguo nzuri, lakini ni bure tu kwa timu wazi na zisizo za kibiashara. Unaweza pia kupakia faili za mardown kwa kutumia git na kufanya kazi nazo katika Github.

Hati za Kipengele: Docz, Kitabu cha Hadithi na Mwongozo wa Sinema

Miongozo, muundo wa mfumo, maktaba za sehemu, chochote unachotaka kuziita, hizi zimekuwa maarufu sana hivi karibuni. Kuibuka kwa mifumo ya vipengele kama vile React na zana zilizotajwa hapa kumewezesha kuzibadilisha kutoka kwa miradi ya ubatili hadi zana muhimu.

Kitabu cha Hadithi, Docz na Styleguidist hufanya jambo lile lile: onyesha vipengele wasilianifu na kuandika API yao. Mradi unaweza kuwa na kadhaa au hata mamia ya vipengele, vyote vikiwa na hali na mitindo tofauti. Ikiwa ungependa vipengele vitumike tena, watu wanahitaji kujua kuwa vipo. Ili kufanya hivyo, inatosha kuorodhesha vipengele. Miongozo hutoa muhtasari rahisi wa kutafuta wa vipengele vyako vyote. Hii husaidia kudumisha uwiano wa kuona na kuepuka kazi ya kurudia.

Zana hizi hutoa njia rahisi ya kutazama majimbo anuwai. Inaweza kuwa vigumu kuiga kila hali ya kijenzi katika muktadha wa programu halisi. Badala ya kubofya programu halisi, inafaa kukuza sehemu tofauti. Inawezekana kuiga hali ngumu kufikia (kwa mfano, hali ya upakiaji).

Pamoja na maonyesho ya kuona ya majimbo mbalimbali na orodha ya mali, mara nyingi ni muhimu kuandika maelezo ya jumla ya maudhui - hoja za kubuni, kesi za matumizi, au maelezo ya matokeo ya kupima mtumiaji. Markdown ni rahisi sana kujifunza - kwa hakika, miongozo inapaswa kuwa rasilimali iliyoshirikiwa kwa wabunifu na watengenezaji. Docz, Styleguidist, na Storybook hutoa njia ya kuchanganya Markdown na vijenzi kwa urahisi.

Docz

Kwa sasa, Docz inafanya kazi na React pekee, lakini inashughulikia kikamilifu usaidizi wa Preact, Vue, na vipengee vya wavuti. Docz ni zana ya hivi punde zaidi kati ya hizo tatu, lakini imeweza kukusanya zaidi ya nyota 14 kwenye Github. Docz anatanguliza vipengele viwili - <Playground> и < Props >. Zinaingizwa na kutumika katika faili .mdx.

import { Playground, Props } from "docz";
import Button from "../src/Button";

## You can _write_ **markdown**
### You can import and use components

<Button>click</Button>

Unaweza kufunika vipengele vyako vya React kwa kutumia <Playground>kuunda analog ya CodePen iliyojengwa ndani au CodeSandbox - yaani, unaona sehemu yako na unaweza kuihariri.

<Playground>
  <Button>click</Button>
</Playground>

<Props> itaonyesha sifa zote zinazopatikana za kipengele cha React kilichotolewa, thamani chaguo-msingi na kama sifa inahitajika.

<Props of={Button} />

Binafsi, naona mbinu hii ya msingi wa MDX kuwa rahisi kuelewa na rahisi kufanya kazi nayo.

Ikiwa wewe ni shabiki wa jenereta ya tovuti tuli ya Gatsby, Docz inatoa miunganisho mizuri.

mtindo wa mwongozo

Kama ilivyo kwa Docz, mifano imeandikwa kwa kutumia syntax ya Markdown. Styleguidist hutumia vizuizi vya msimbo wa Markdown (nukuu tatu) katika faili za kawaida .md faili, sio kwenye MDX.

```js
<Button onClick={() => console.log('clicked')>Push Me</Button>

Vizuizi vya msimbo katika Markdown kawaida huonyesha nambari tu. Unapotumia Styleguidist, kizuizi chochote cha msimbo kilicho na lebo ya lugha js, jsx au javascript itatoa kama sehemu ya React. Kama Docz, nambari inaweza kuhaririwa - unaweza kubadilisha mali na kuona matokeo mara moja.

Styleguidist itaunda kiotomatiki laha ya sifa kutoka kwa matamko ya PropTypes, Flow au Typescript.

Styleguidist sasa inasaidia React na Vue.

Kitabu cha Hadithi

Bili za kitabu cha hadithi chenyewe kama "mazingira ya ukuzaji wa kipengele cha UI". Badala ya kuandika mifano ya sehemu ndani ya faili za Markdown au MDX, unaandika hadithi ndani ya faili za Javascript. Hadithi hati hali maalum ya sehemu. Kwa mfano, sehemu inaweza kuwa na historia ya hali ya upakiaji na hali ya ulemavu (walemavu).

storiesOf('Button', module)
  .add('disabled', () => (
    <Button disabled>lorem ipsum</Button>
  ))

Kitabu cha hadithi ni ngumu zaidi kuliko Styleguidist na Docz. Lakini wakati huo huo, hii ndiyo chaguo maarufu zaidi, kwenye Github mradi una nyota zaidi ya 36. Huu ni mradi wa chanzo huria na wachangiaji 000 na usaidizi wa wafanyikazi. Inatumiwa na Airbnb, Algolia, Atlassian, Lyft na Salesforce. Kitabu cha Hadithi kinaweza kutumia mifumo mingi kuliko shindano - React, React Asili, Vue, Angular, Mithril, Ember, Riot, Svelte, na HTML tupu.

Katika toleo la baadaye, kutakuwa na chips kutoka Docz na MDX inaletwa.

# Button

Some _notes_ about your button written with **markdown syntax**.

<Story name="disabled">
  <Button disabled>lorem ipsum</Button>
</Story>

Vipengele vipya vya Kitabu cha Hadithi vitatolewa hatua kwa hatua katika miezi michache ijayo, na inaonekana kama itakuwa hatua kubwa mbele.

Matokeo ya

Manufaa ya maktaba ya muundo yanasifiwa katika mamilioni ya makala kwenye Medium. Inapofanywa vizuri, hurahisisha kuunda bidhaa zinazohusiana na kudumisha utambulisho. Bila shaka, hakuna zana hizi zitaunda mfumo wa kubuni kichawi. Hii inahitaji muundo makini na muundo wa CSS. Lakini inapofika wakati wa kufanya mfumo wa kubuni upatikane kwa kampuni nzima, Docz, Storybook na Styleguidist ni chaguo kubwa.

Kutoka kwa mfasiri. Hii ni uzoefu wangu wa kwanza juu ya Habre. Ikiwa unapata usahihi wowote, au una mapendekezo ya kuboresha makala - andika kwa kibinafsi.

Chanzo: mapenzi.com