O le ni iṣẹ orisun ṣiṣi ti o dara julọ, ṣugbọn ti ko ba ni iwe ti o dara, awọn aye ni kii yoo gba kuro. Ni ọfiisi, iwe ti o dara yoo ṣe idiwọ fun ọ lati dahun awọn ibeere kanna. Iwe tun ṣe idaniloju pe eniyan le loye iṣẹ akanṣe ti awọn oṣiṣẹ pataki ba lọ kuro ni ile-iṣẹ tabi awọn ipa ti yipada. Awọn itọsọna igbesi aye yoo ṣe iranlọwọ lati rii daju iduroṣinṣin data.
Ti o ba nilo lati kọ ọrọ gigun, Markdown jẹ yiyan nla si HTML. Nigba miran Markdown sintasi ko to. Ni idi eyi a le lo HTML inu rẹ. Fun apẹẹrẹ, awọn eroja aṣa. Nitorinaa, ti o ba n kọ eto apẹrẹ kan pẹlu awọn paati oju opo wẹẹbu abinibi, wọn le ni irọrun wa ninu iwe ọrọ. Ti o ba nlo React (tabi eyikeyi ilana JSX miiran bi Preact tabi Vue), o le ṣe ohun kanna pẹlu MDX.
Nkan yii jẹ akopọ gbooro ti awọn irinṣẹ fun kikọ iwe ati ṣiṣẹda awọn itọsọna. Kii ṣe gbogbo awọn irinṣẹ ti a ṣe akojọ si nibi lo MDX, ṣugbọn o n pọ si ni pẹlu awọn irinṣẹ iwe.
Kini MDX?
Ọna .mdx ni sintasi kanna bi Markdown, ṣugbọn ngbanilaaye lati gbe awọn paati JSX ibaraenisọrọ wọle ati fi sii wọn sinu akoonu rẹ. Atilẹyin fun awọn paati Vue wa ni alfa. Lati bẹrẹ ṣiṣẹ pẹlu MDX, kan fi sori ẹrọ “Ṣẹda Ohun elo React”. Awọn afikun wa fun Next.js ati Gatsby. Ẹya ti o tẹle ti Docusaurus (ẹya 2) yoo tun ni atilẹyin abinibi.
Awọn iwe kikọ pẹlu Docusaurus
Docusaurus kowe lori Facebook. Wọn lo lori gbogbo iṣẹ orisun ṣiṣi ayafi React. Ni ita ile-iṣẹ o jẹ lilo nipasẹ Redux, Prettier, Gulp ati Babel.
Awọn iṣẹ akanṣe ti o lo Docusaurus.
Docusaurus le ṣee lo lati kọ любой iwe, ko nikan lati se apejuwe awọn frontend. O ni React labẹ hood, ṣugbọn o ko ni lati faramọ pẹlu rẹ lati lo. O gba awọn faili Markdown rẹ, fun pọ ti idan ati eto daradara, kika ati iwe kika pẹlu apẹrẹ ẹlẹwa ti ṣetan.
Lori oju opo wẹẹbu Redux o le wo awoṣe Docusaurus boṣewa
Awọn oju opo wẹẹbu ti a ṣe pẹlu Docusaurus tun le pẹlu bulọọgi ti o da lori Markdown. Prism.js ti sopọ lẹsẹkẹsẹ fun fifi aami sintasi. Bi o ti jẹ pe Docusaurus farahan laipẹ, o jẹ idanimọ bi ohun elo ti o dara julọ ti 2018 lori StackShare.
Awọn aṣayan Ṣiṣẹda Akoonu miiran
Docusaurus jẹ apẹrẹ pataki fun ṣiṣẹda iwe. Nitoribẹẹ, awọn miliọnu kan ati awọn ọna kan wa lati ṣe oju opo wẹẹbu kan - o le ran ojutu tirẹ ni eyikeyi ede, CMS, tabi lo olupilẹṣẹ aaye aimi kan.
Fun apẹẹrẹ, awọn iwe-ipamọ fun React, eto apẹrẹ IBM, Apollo ati Ghost CMS lo Gatsby - olupilẹṣẹ aaye aimi kan ti a lo nigbagbogbo fun awọn bulọọgi. Ti o ba ṣiṣẹ pẹlu Vue, lẹhinna VuePress jẹ aṣayan ti o dara fun ọ. Aṣayan miiran ni lati lo olupilẹṣẹ ti a kọ sinu Python - MkDocs. O jẹ orisun ṣiṣi ati tunto nipa lilo faili YAML kan. GitBook tun jẹ aṣayan ti o dara, ṣugbọn o jẹ ọfẹ fun gbogbo eniyan ati awọn ẹgbẹ ti kii ṣe ti owo. O tun le nirọrun gbejade awọn faili ṣoki ni lilo Git ki o ṣiṣẹ pẹlu wọn ni Github.
Awọn nkan kikọ silẹ: Docz, Iwe itan ati Styleguidist
Awọn itọnisọna, apẹrẹ eto, awọn ile-ikawe paati - ohunkohun ti o pe wọn, o ti di olokiki pupọ laipẹ. Wiwa ti awọn ilana paati bii React ati awọn irinṣẹ ti a mẹnuba nibi ti yi wọn pada lati awọn iṣẹ akanṣe sinu awọn irinṣẹ to wulo.
Iwe itan, Docz ati Styleguidist gbogbo wọn ṣe ohun kanna: ṣafihan awọn eroja ibaraenisepo ati ṣe iwe API wọn. Ise agbese kan le ni awọn dosinni tabi paapaa awọn ọgọọgọrun ti awọn paati - gbogbo rẹ pẹlu awọn ipinlẹ oriṣiriṣi ati awọn aza. Ti o ba fẹ awọn paati lati tun lo, eniyan nilo lati mọ pe wọn wa. Lati ṣe eyi, nìkan katalogi awọn irinše. Awọn itọsọna pese ohun rọrun-lati-wa Akopọ ti gbogbo rẹ irinše. Eyi ṣe iranlọwọ lati ṣetọju aitasera wiwo ati yago fun iṣẹ atunwi.
Awọn irinṣẹ wọnyi pese ọna irọrun lati wo awọn ipinlẹ oriṣiriṣi. O le nira lati ṣe ẹda kọọkan ti ẹya paati ni aaye ti ohun elo gidi kan. Dipo ti titẹ lori ohun elo gangan, o tọ lati ṣe agbekalẹ paati lọtọ. Awọn ipinlẹ lile lati de ọdọ (gẹgẹbi awọn ipinlẹ ikojọpọ) le ṣe adaṣe.
Paapọ pẹlu ifihan wiwo ti awọn ipinlẹ pupọ ati atokọ ti awọn ohun-ini, igbagbogbo jẹ pataki lati kọ apejuwe gbogbogbo ti akoonu - awọn idi apẹrẹ, awọn ọran lilo, tabi awọn apejuwe ti awọn abajade idanwo olumulo. Markdown rọrun pupọ lati kọ ẹkọ - ni pipe, awọn itọnisọna yẹ ki o jẹ orisun ti o pin fun awọn apẹẹrẹ ati awọn olupilẹṣẹ. Docz, Styleguidist, ati Iwe itan n funni ni ọna lati ni irọrun dapọ Markdown pẹlu awọn paati.
Docz
Lọwọlọwọ Docz nikan n ṣiṣẹ pẹlu React, ṣugbọn iṣẹ ṣiṣe n lọ lọwọ lati ṣe atilẹyin Preact, Vue ati awọn paati wẹẹbu. Docz jẹ aipẹ julọ ti awọn irinṣẹ mẹta, ṣugbọn o ti ṣakoso lati gba diẹ sii ju awọn irawọ 14 lori Github. Docz ṣafihan awọn paati meji - <Playground> и < Props >. Wọn ti wa ni wole ati ki o lo ninu awọn 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>O le fi ipari si awọn paati React tirẹ pẹlu <Playground>lati ṣẹda afọwọṣe ti CodePen ti a ṣe sinu tabi CodeSandbox - iyẹn ni, o rii paati rẹ ati pe o le ṣatunkọ.
<Playground>
<Button>click</Button>
</Playground><Props> yoo ṣafihan gbogbo awọn ohun-ini to wa fun paati React ti a fun, awọn iye aiyipada, ati boya ohun-ini naa nilo.
<Props of={Button} />Tikalararẹ, Mo rii ọna orisun MDX yii lati rọrun julọ lati ni oye ati rọrun julọ lati ṣiṣẹ pẹlu.
Ti o ba jẹ olufẹ ti olupilẹṣẹ aaye aimi Gatsby, Docz nfunni ni isọpọ nla kan.
Itọsọna Style
Bii Docz, awọn apẹẹrẹ ni a kọ nipa lilo sintasi Markdown. Styleguidist nlo awọn bulọọki koodu Markdown (awọn agbasọ mẹta) ni awọn faili deede .md awọn faili, kii ṣe MDX.
```js
<Button onClick={() => console.log('clicked')>Push Me</Button>Awọn bulọọki koodu ni Markdown nigbagbogbo ṣafihan koodu kan. Nigbati o ba nlo Styleguidist, eyikeyi bulọọki koodu pẹlu aami ede kan js, jsx tabi javascript yoo mu bi a React paati. Bii Docz, koodu naa jẹ atunṣe - o le yi awọn ohun-ini pada ki o rii abajade lẹsẹkẹsẹ.
Styleguidist yoo ṣẹda tabili ohun-ini laifọwọyi lati awọn PropTypes, Sisan tabi awọn ikede Typescript.
Styleguidist lọwọlọwọ ṣe atilẹyin React ati Vue.
Iwe itan
Iwe itan ṣe ipo funrararẹ bi “agbegbe idagbasoke paati UI.” Dipo kikọ awọn paati apẹẹrẹ inu Markdown tabi awọn faili MDX, o kọ itan inu awọn faili Javascript. История iwe awọn kan pato ipinle ti a paati. Fun apẹẹrẹ, paati kan le ni awọn itan-akọọlẹ fun ipinlẹ ti kojọpọ ati ipinlẹ alaabo (alaabo).
storiesOf('Button', module)
.add('disabled', () => (
<Button disabled>lorem ipsum</Button>
))Iwe itan jẹ eka pupọ ju Styleguidist ati Docz lọ. Ṣugbọn ni akoko kanna, eyi ni aṣayan olokiki julọ; iṣẹ akanṣe naa ni diẹ sii ju awọn irawọ 36 lori Github. O jẹ iṣẹ akanṣe orisun ṣiṣi pẹlu awọn oluranlọwọ 000 ati oṣiṣẹ akoko kikun. O jẹ lilo nipasẹ Airbnb, Algolia, Atlassian, Lyft ati Salesforce. Iwe itan ṣe atilẹyin awọn ilana diẹ sii ju awọn oludije lọ - React, React Native, Vue, Angular, Mithril, Ember, Riot, Svelte ati HTML deede.
Ni itusilẹ ọjọ iwaju awọn ẹya yoo wa lati Docz ati MDX yoo ṣafihan.
# Button
Some _notes_ about your button written with **markdown syntax**.
<Story name="disabled">
<Button disabled>lorem ipsum</Button>
</Story>Awọn ẹya tuntun ti Iwe itan yoo jade ni diẹdiẹ ni awọn oṣu diẹ ti n bọ ati pe o dabi pe yoo jẹ igbesẹ nla siwaju.
Awọn esi
Awọn anfani ti ile-ikawe apẹẹrẹ jẹ igbega ni awọn miliọnu awọn nkan lori Alabọde. Nigbati o ba ṣe daradara, wọn jẹ ki o rọrun lati ṣẹda awọn ọja ti o ni ibatan ati ṣetọju idanimọ. Nitoribẹẹ, ko si ọkan ninu awọn irinṣẹ wọnyi ti yoo ṣẹda eto apẹrẹ kan ni idan. Eyi nilo apẹrẹ iṣọra ati CSS. Ṣugbọn nigbati o ba de akoko lati jẹ ki eto apẹrẹ kan wa si gbogbo ile-iṣẹ, Docz, Iwe itan ati Styleguidist jẹ awọn aṣayan nla.
Lati onitumọ. Eyi ni iriri akọkọ mi lori Habré. Ti o ba ri awọn aiṣedeede eyikeyi, tabi ni awọn imọran fun ilọsiwaju nkan naa, kọ si mi ni ifiranṣẹ ti ara ẹni.
orisun: www.habr.com