Tilmaamaha nolosha - MDX iyo qaabab kale

Waxaa laga yaabaa inaad haysatid mashruuc il furan oo wanaagsan, laakiin haddii aysan haysan dukumeenti wanaagsan, waxay u badan tahay inaysan waligeed furmi doonin. Xafiiska dhexdiisa, dukumeenti wanaagsan ayaa kaa ilaalin doona inaad ka jawaabto isla su'aalaha marar badan. Dukumeentiyadu waxay sidoo kale hubinayaan in dadku ay macno samayn karaan mashruuca haddii shaqaalaha muhiimka ah ay ka tagaan shirkadda ama doorarka ay isbeddelaan. Tilmaamaha tooska ah waxay caawiyaan hubinta daacadnimada xogta.

Haddii aad u baahan tahay inaad qorto qoraal dheer, Markdown waa beddel weyn oo HTML ah. Mararka qaarkood ereyga Markdown kuma filna. Xaaladdan oo kale, waxaan ku isticmaali karnaa gudaha HTML. Tusaale ahaan, walxaha gaarka ah. Sidaa darteed, haddii aad dhiseyso nidaamka naqshadeynta oo leh qaybaha shabakadda ee asalka ah, way fududahay in lagu daro dukumeenti qoraal ah. Haddii aad isticmaalayso React (ama qaab dhismeedka kale ee JSX sida Preact ama Vue), waxaad ku samayn kartaa MDX la mid ah.

Maqaalkani waa dulmar ballaadhan oo ku saabsan qalabka lagu qoro dukumeentiyada iyo abuurista hage. Dhammaan agabyada halkan ku taxan ma isticmaalaan MDX, laakiin waxa si isa soo taraysa loogu darayaa agabka dukumeentiyada.

Waa maxay MDX?

file .mdx wuxuu leeyahay isku mid ah sida Markdown laakiin wuxuu kuu ogolaanayaa inaad soo dejiso qaybaha isdhexgalka ee JSX oo aad geliso macluumaadkaaga. Taageerada qaybaha Vue waxay ku jirtaa alfa. Si aad u bilowdo la shaqaynta MDX, kaliya ku rakib "Create React App". Waxaa jira plugins loogu talagalay Next.js iyo Gatsby. Nooca xiga ee Docusaurus (nooca 2) wuxuu sidoo kale yeelan doonaa taageero ku dhex dhisan.

Ku qoritaanka dukumentiyada Docusaurus

Docusaurus ayaa ku soo qoray Facebook. Waxay u isticmaalaan mashruuc kasta oo il furan marka laga reebo React. Ka baxsan shirkadda, Redux, Prettier, Gulp, iyo Babel ayaa isticmaala.

Mashruucyada isticmaala Docusaurus.

Docusaurus waxa loo isticmaali karaa in wax lagu qoro mid kasta dukumeenti, ma aha oo kaliya in lagu qeexo dhinaca hore. Waxay leedahay React hoostiisa, laakiin uma baahnid inaad taqaanid si aad u isticmaasho. Waxay qaadanaysaa faylalkaaga Markdown, xoogaa sixir ah oo si wanaagsan loo habeeyey, la habeeyey oo dukumeenti la akhriyi karo oo leh nakhshad qurux badan waa diyaar.

Waxaad ku arki kartaa qaabka Docusaurus ee caadiga ah ee shabakada Redux.

Goobaha lagu dhisay Docusaurus waxa kale oo ku jiri kara baloog ku salaysan Markdown. Muujinta syntax, Prism.js isla markiiba waa lagu daray. Inkastoo xaqiiqda ah in Docusaurus uu soo muuqday dhawaanahan, waxaa loo aqoonsaday inuu yahay qalabka ugu fiican ee 2018 ee StackShare.

Ikhtiyaarada kale ee Abuurista Mawduuca

Docusaurus waxaa si gaar ah loogu talagalay abuurista dukumeenti Dabcan, waxaa jira hal milyan iyo hal dariiqo oo lagu sameeyo degel - waxaad geyn kartaa xalkaaga luqad kasta, CMS, ama isticmaal koronto-dhaliye taagan.

Tusaale ahaan, dukumeentiyada React, nidaamka naqshadaynta IBM, Apollo, iyo Ghost CMS waxay isticmaalaan Gatsby, koronto-dhaliyaha goobta taagan inta badan loo isticmaalo blogyada. Haddii aad la shaqaynayso Vue markaas VuePress ayaa kuu fiican. Doorasho kale ayaa ah in la isticmaalo koronto-dhaliye ku qoran Python - MkDocs. Way furan tahay oo lagu habeeyey hal fayl oo YAML ah. GitBook sidoo kale waa ikhtiyaar wanaagsan, laakiin kaliya waa u bilaash kooxaha furan iyo kuwa aan ganacsiga ahayn. Waxa kale oo aad kaliya geli kartaa faylasha mardown adiga oo isticmaalaya git oo kala shaqee Github.

Dukumentiga Qaybaha: Docz, Buug Sheeko iyo Hab-yaqaan

Tilmaamaha, naqshadeynta nidaamka, maktabadaha qaybaha, wax kasta oo aad rabto inaad u wacdo, kuwani waxay noqdeen kuwo aad loo jecel yahay waayadan. Soo ifbaxa qaab-dhismeedka qaybaha sida React iyo aaladaha halkan lagu sheegay ayaa suurtageliyay in laga beddelo mashaariicda aan waxtarka lahayn loona beddelo qalab waxtar leh.

Buuga sheekada, Docz iyo Styleguidist waxay sameeyaan wax la mid ah: soo bandhig walxaha isdhexgalka oo dukumeenti APIkooda. Mashruucu wuxuu yeelan karaa daraasiin ama xitaa boqollaal qaybood, dhammaantoodna leh gobollo iyo qaabab kala duwan. Haddii aad rabto in qaybaha dib loo isticmaalo, dadku waxay u baahan yihiin inay ogaadaan inay jiraan. Si taas loo sameeyo, waa ku filan in la qoro qaybaha. Tilmaamuhu waxay bixiyaan dulmar sahlan oo si sahlan loo baadho dhammaan qaybahaaga. Tani waxay gacan ka geysaneysaa ilaalinta joogteynta muuqaalka oo iska ilaali shaqada soo noqnoqda.

Qalabyadani waxay bixiyaan hab ku habboon oo lagu eego gobollo kala duwan. Way adkaan kartaa in lagu celceliyo xaalad kasta oo ka mid ah qayb ka mid ah macnaha codsiga dhabta ah. Halkii aad gujin lahayd codsiga dhabta ah, waxaa habboon in la sameeyo qayb gaar ah. Waa suurtogal in la qaabeeyo gobolo adag in la gaadho (tusaale ahaan, gobolka loading).

Iyada oo ay weheliso bandhig muuqaal ah oo gobolo kala duwan ah iyo liiska guryaha, inta badan waa lagama maarmaan in la qoro sharaxaad guud oo ku saabsan nuxurka - fikradaha naqshadeynta, kiisaska isticmaalka, ama sharaxaadda natiijooyinka baaritaanka isticmaalaha. Markdown aad bay u fududahay in la barto - sida ugu habboon, tilmaamaha waa inay noqdaan kheyraad la wadaago naqshadeeyayaasha iyo horumariyeyaal. Docz, Styleguidist, iyo Bookbook waxay bixiyaan hab si fudud loogu qaso Markdown iyo qaybaha.

Docz

Hadda, Docz kaliya waxa uu la shaqeeyaa React, laakiin waxa uu si firfircoon uga shaqaynayaa taageerada Preact, Vue, iyo qaybaha shabakada. Docz waa kii ugu dambeeyay ee saddexda qalab, laakiin wuxuu awooday inuu ku ururiyo in ka badan 14 oo xiddigood Github. Docz wuxuu soo bandhigayaa laba qaybood - <Playground> и < Props >. Waa la soo dejiyaa oo loo isticmaalaa faylalka .mdx.

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

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

<Button>click</Button>

Waxaad ku duubi kartaa qaybahaaga falcelinta <Playground>si aad u abuurto analooga ku dhex jira CodePen ama CodeSandbox - taasi waa, waxaad arkaysaa qaybtaada oo aad wax ka beddeli kartaa.

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

<Props> waxay tusi doontaa dhammaan guryaha la heli karo ee qaybta falcelinta la bixiyay, qiimayaasha caadiga ah iyo haddii hantida loo baahan yahay.

<Props of={Button} />

Shakhsi ahaan, waxaan u arkaa habkan ku saleysan MDX kan ugu fudud in la fahmo iyo sida ugu fudud ee lagula shaqeeyo.

Haddii aad taageere u tahay koronto-dhaliyaha goobta taagan ee Gatsby, Docz wuxuu bixiyaa is-dhexgalka weyn.

hagaha style

Sida Docz, tusaalooyin ayaa lagu qoraa iyadoo la isticmaalayo Markdown syntax. Styleguidist waxay isticmaashaa xidhmooyinka koodka Markdown (saddex xigasho) faylasha caadiga ah .md faylasha, kuma jiraan MDX.

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

Xirmooyinka koodka ee ku yaal Markdown badanaa waxay muujiyaan koodka. Markaad isticmaalayso Styleguidist, qayb kasta oo kood ah oo leh sumad luqadeed js, jsx ama javascript waxay noqon doontaa qayb falcelin ahaan. Sida Docz, koodka waa la tafatiri karaa - waxaad bedeli kartaa guryaha oo isla markiiba waxaad arki kartaa natiijada.

Styleguidist waxa uu si toos ah uga samayn doonaa xaashida hantida ee PropTypes, Socodka ama caddaynta Nooca Qoraalka.

Styleguidist hadda waxay taageertaa React iyo Vue.

Buugga sheekada

Buuga sheekada laftiisa waxa uu biilasha u bixiyaa sidii "bay'adda horumarinta qaybaha UI". Halkii aad ku qori lahayd tusaalooyinka qaybaha gudaha Markdown ama MDX, waxaad qortaa sheekooyinka gudaha faylasha Javascript. История diiwaan geli xaaladda gaarka ah ee qayb ka mid ah. Tusaale ahaan, qayb ayaa laga yaabaa in ay taariikh u leedahay gobolka rarida iyo gobolka naafada ah (naafo ah).

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

Buuga sheekada aad ayuu uga adag yahay Styleguidist iyo Docz. Laakiin isla mar ahaantaana, tani waa ikhtiyaarka ugu caansan, Github mashruucu wuxuu leeyahay in ka badan 36 oo xiddigood. Kani waa mashruuc il furan oo leh 000 ka qaybqaatayaal iyo wehel shaqaale. Waxaa isticmaala Airbnb, Algolia, Atlassian, Lyft iyo Salesforce. Buuga sheekada waxa uu taageeraa habab ka badan tartanka - React, React Native, Vue, Angular, Mithril, Ember, Riot, Svelte, iyo HTML cad.

Siideynta mustaqbalka, waxaa jiri doona chips ka Docz iyo MDX ayaa la soo bandhigayaa.

# Button

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

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

Tilmaamaha Buugga Sheekada cusub ayaa si tartiib tartiib ah u soo bixi doona dhowrka bilood ee soo socda, waxayna u egtahay inay noqon doonto tallaabo weyn oo hore loo qaaday.

Natiijooyinka

Faa'iidooyinka maktabadda naqshadda waxaa lagu ammaanaa malaayiin maqaallo ah oo ku saabsan Dhexdhexaadka. Marka si fiican loo sameeyo, waxay fududeeyaan abuurista alaabada la xidhiidha oo ay ilaaliyaan aqoonsiga. Dabcan, mid ka mid ah qalabkan midkoodna sixir ma abuuri doono nidaamka naqshadeynta. Tani waxay u baahan tahay naqshad taxadar leh iyo naqshadeynta CSS. Laakiin marka ay timaado wakhtiga lagu samaynayo nidaamka naqshadaynta ee ay heli karaan shirkadda oo dhan, Docz, Storybook iyo Styleguidist waa xulashooyin weyn.

Ka yimid turjumaan. Tani waa waayo-aragnimadayda ugu horreysay ee Habré. Haddii aad aragto wax khalad ah, ama aad hayso talooyin lagu hagaajinayo maqaalka - ku qor shakhsi ahaan.

Source: www.habr.com