Kuna iya samun mafi kyawun aikin tushen buɗaɗɗen, amma idan ba shi da kyawawan takardu, daman ba zai taɓa tashi ba. A cikin ofishin, kyawawan takardu za su hana ku amsa tambayoyin iri ɗaya. Takaddun bayanai sun kuma tabbatar da cewa mutane za su iya fahimtar aikin idan manyan ma'aikata suka bar kamfanin ko matsayinsu ya canza. Jagororin rayuwa zasu taimaka tabbatar da amincin bayanai.
Idan kana buƙatar rubuta dogon rubutu, Markdown babban madadin HTML ne. Wani lokaci Markdown syntax bai isa ba. A wannan yanayin za mu iya amfani da HTML a ciki. Misali, abubuwan al'ada. Don haka, idan kuna gina tsarin ƙira tare da abubuwan haɗin yanar gizo na asali, ana iya haɗa su cikin sauƙi cikin takaddun rubutu. Idan kuna amfani da React (ko kowane tsarin JSX kamar Preact ko Vue), zaku iya yin abu iri ɗaya ta amfani da MDX.
Wannan labarin babban bayyani ne na kayan aikin rubuta takardu da ƙirƙirar jagororin. Ba duk kayan aikin da aka jera anan suna amfani da MDX ba, amma ana ƙara haɗa shi cikin kayan aikin tattara bayanai.
Menene MDX?
fayil .mdx yana da tsari iri ɗaya da Markdown, amma yana ba ku damar shigo da abubuwan haɗin gwiwar JSX da saka su cikin abubuwan ku. Goyon bayan abubuwan Vue yana cikin alpha. Don fara aiki tare da MDX, kawai shigar da "Create React App". Akwai plugins don Next.js da Gatsby. Siga na gaba na Docusaurus (version 2) shima zai sami goyon baya na asali.
Rubutun takardu tare da Docusaurus
Docusaurus ya rubuta a Facebook. Suna amfani da shi akan kowane buɗaɗɗen aikin tushen sai dai React. A wajen kamfanin ana amfani da ita ta Redux, Prettier, Gulp da Babel.
Ayyukan da ke amfani da Docusaurus.
Ana iya amfani da Docusaurus don rubutawa wani takardun, ba kawai don bayyana gaban gaba ba. Yana da React a ƙarƙashin murfin, amma ba dole ba ne ka saba da shi don amfani da shi. Yana ɗaukar fayilolin Markdown ɗinku, ɗanɗano na sihiri da ingantaccen tsari, tsararru da takaddun karatu tare da kyakkyawan ƙira an shirya.
A kan gidan yanar gizon Redux zaka iya ganin daidaitaccen samfurin Docusaurus
Shafukan da aka gina tare da Docusaurus kuma na iya haɗawa da bulogi na Markdown. An haɗa Prism.js nan da nan don nuna alama. Duk da cewa Docusaurus ya bayyana kwanan nan, an gane shi azaman kayan aiki mafi kyau na 2018 akan StackShare.
Sauran Zaɓuɓɓukan Ƙirƙirar Abun ciki
Docusaurus an tsara shi musamman don ƙirƙirar takardu. Tabbas, akwai hanyoyi miliyan da ɗaya don yin gidan yanar gizo - zaku iya tura naku mafita a kowane harshe, CMS, ko amfani da janareta na rukunin yanar gizo.
Misali, takaddun don React, tsarin ƙira na IBM, Apollo da Ghost CMS suna amfani da Gatsby - janareta na rukunin yanar gizo wanda galibi ana amfani da shi don bulogi. Idan kuna aiki tare da Vue, to VuePress zaɓi ne mai kyau a gare ku. Wani zaɓi kuma shine amfani da janareta da aka rubuta a cikin Python - MkDocs. Buɗaɗɗen tushe ne kuma an saita shi ta amfani da fayil ɗin YAML guda ɗaya. GitBook shima zaɓi ne mai kyau, amma kyauta ne kawai ga ƙungiyoyin jama'a da waɗanda ba na kasuwanci ba. Hakanan zaka iya kawai loda fayilolin ɓarna ta amfani da Git kuma kuyi aiki tare da su a Github.
Abubuwan da aka tattara: Docz, Littafin Labari da Mai Salon Salon
Sharuɗɗa, ƙirar tsarin, ɗakunan karatu - duk abin da kuka kira su, ya zama sananne sosai kwanan nan. Zuwan tsarin sassa kamar React da kayan aikin da aka ambata anan sun canza su daga ayyukan banza zuwa kayan aiki masu amfani.
Littafin labari, Docz da Styleguidist duk suna yin abu iri ɗaya: suna nuna abubuwan hulɗa da rubuta API ɗin su. Aiki na iya samun da dama ko ma ɗaruruwan sassa - duk tare da jihohi da salo daban-daban. Idan kana son a sake amfani da kayan aikin, mutane suna buƙatar sanin akwai su. Don yin wannan, kawai katange abubuwan da aka gyara. Sharuɗɗa suna ba da taƙaitaccen bayani mai sauƙi na duk abubuwan haɗin ku. Wannan yana taimakawa kiyaye daidaito na gani da kuma guje wa maimaita aiki.
Waɗannan kayan aikin suna ba da hanya mai dacewa don duba jihohi daban-daban. Zai iya zama da wahala a sake haifar da kowane yanayi na wani yanki a cikin mahallin aikace-aikacen gaske. Maimakon danna ainihin aikace-aikacen, yana da daraja haɓaka wani ɓangaren daban. Jihohi masu wuyar isa (kamar jihohin lodawa) ana iya kwaikwayar su.
Tare da nunin gani na jihohi daban-daban da jerin kaddarorin, sau da yawa ya zama dole a rubuta cikakken bayanin abubuwan da ke ciki - dalilan ƙira, lokuta masu amfani, ko kwatancen sakamakon gwajin mai amfani. Markdown yana da sauƙin koyo - a zahiri, jagororin yakamata su zama hanyar haɗin gwiwa don masu ƙira da masu haɓakawa. Docz, Styleguidist, da Littafin Labari suna ba da hanya don sauƙaƙe haɗe Markdown tare da abubuwan haɗin gwiwa.
Docz
A halin yanzu Docz kawai yana aiki tare da React, amma ana kan aiki mai aiki don tallafawa Preact, Vue da abubuwan haɗin yanar gizo. Docz shine mafi kwanan nan na kayan aikin guda uku, amma ya sami nasarar tattara sama da taurari 14 akan Github. Docz ya gabatar da abubuwa biyu - <Playground> и < Props >. Ana shigo da su kuma ana amfani da su a cikin fayiloli .mdx.
import { Playground, Props } from "docz";
import Button from "../src/Button";
## You can _write_ **markdown**
### You can import and use components
<Button>click</Button>Kuna iya nannade abubuwan React naku da <Playground>don ƙirƙirar analog na ginannen CodePen ko CodeSandbox - wato, kuna ganin ɓangaren ku kuma kuna iya gyara shi.
<Playground>
<Button>click</Button>
</Playground><Props> zai nuna duk kaddarorin da ke akwai don ɓangaren React ɗin da aka bayar, ƙimar tsoho, da ko ana buƙatar kadarar.
<Props of={Button} />Da kaina, na sami wannan tsarin tushen MDX ya zama mafi sauƙin fahimta kuma mafi sauƙin aiki tare.
Idan kun kasance mai goyon bayan Gatsby static site janareta, Docz yana ba da babban haɗin kai.
Jagoran salo
Kamar Docz, ana rubuta misalai ta amfani da tsarin Markdown. Styleguidist yana amfani da tubalan lambar Markdown (ƙididdigar ƙididdiga uku) a cikin fayiloli na yau da kullun .md fayiloli, ba MDX.
```js
<Button onClick={() => console.log('clicked')>Push Me</Button>Tubalan lamba a Markdown yawanci suna nuna lamba kawai. Lokacin amfani da Styleguidist, kowane toshe lamba tare da alamar harshe js, jsx ko javascript zai bayar azaman bangaren React. Kamar Docz, lambar tana iya daidaitawa - zaku iya canza kaddarorin kuma ku ga sakamakon nan take.
Styleguidist zai ƙirƙiri teburin kadara ta atomatik daga bayanin PropTypes, Flow ko Typescript.
Styleguidist a halin yanzu yana goyan bayan React da Vue.
Littafin labari
Littafin labari ya sanya kansa a matsayin "yanayin ci gaban bangaren UI." Maimakon rubuta abubuwan misali a cikin fayilolin Markdown ko MDX, kuna rubutawa labaru cikin fayilolin Javascript. История rubuta takamaiman yanayin wani sashi. Misali, wani sashi na iya samun tarihin jihar da aka ɗora nauyi da naƙasassun jihar (an kashe su).
storiesOf('Button', module)
.add('disabled', () => (
<Button disabled>lorem ipsum</Button>
))Littafin labari ya fi rikitarwa fiye da Styleguidist da Docz. Amma a lokaci guda, wannan shine zaɓi mafi shahara; aikin yana da taurari sama da 36 akan Github. Yana da buɗaɗɗen tushen aikin tare da masu ba da gudummawa 000 da ma'aikata na cikakken lokaci. Yana amfani da Airbnb, Algolia, Atlassian, Lyft da Salesforce. Littafin labari yana goyan bayan tsarin tsarin fiye da masu fafatawa - React, React Native, Vue, Angular, Mithril, Ember, Riot, Svelte da HTML na yau da kullun.
A cikin sakin gaba za a sami fasali daga Docz kuma za a gabatar da MDX.
# Button
Some _notes_ about your button written with **markdown syntax**.
<Story name="disabled">
<Button disabled>lorem ipsum</Button>
</Story>Sabbin fasalulluka na littafin Labari za su fara fitowa a hankali cikin ƴan watanni masu zuwa kuma yana kama da zai zama babban ci gaba.
Sakamakon
Ana ɗaukaka fa'idodin ɗakin karatu na ƙira a cikin miliyoyin labarai akan Matsakaici. Lokacin da aka yi da kyau, suna sauƙaƙe ƙirƙirar samfuran da ke da alaƙa da kiyaye ainihi. Tabbas, babu ɗayan waɗannan kayan aikin da zai haifar da tsarin ƙira da sihiri. Wannan yana buƙatar ƙira a hankali da CSS. Amma lokacin da ya zo lokacin da za a yi tsarin ƙira zuwa ga kamfanin gaba ɗaya, Docz, Littafin Labari da Styleguidist babban zaɓi ne.
Daga mai fassara. Wannan shine gwanina na farko akan Habré. Idan kun sami wasu kurakurai, ko kuna da shawarwari don inganta labarin, ku rubuto mani cikin saƙo na sirri.
source: www.habr.com