Hiki iā ʻoe ke loaʻa i ka papahana open source maikaʻi loa, akā inā ʻaʻohe palapala maikaʻi, ʻaʻole loa e hemo. Ma ke keʻena, nā palapala maikaʻi e pale iā ʻoe mai ka pane ʻana i nā nīnau like. Hoʻomaopopo pū ka palapala i hiki i nā poʻe ke hoʻomaopopo i ka papahana inā haʻalele nā limahana koʻikoʻi i ka hui a i ʻole nā hana. E kōkua nā alakaʻi ola e hōʻoia i ka pono o ka ʻikepili.
Inā pono ʻoe e kākau i kahi kikokikona lōʻihi, ʻo Markdown kahi koho maikaʻi loa i HTML. I kekahi manawa ʻaʻole lawa ka syntax Markdown. I kēia hihia hiki iā mākou ke hoʻohana i ka HTML i loko. Eia kekahi laʻana, nā mea maʻamau. No laila, inā ʻoe e kūkulu nei i kahi ʻōnaehana hoʻolālā me nā ʻāpana pūnaewele maoli, hiki ke maʻalahi ke hoʻokomo ʻia i loko o nā palapala kikokikona. Inā ʻoe e hoʻohana nei i React (a i ʻole kekahi ʻano JSX e like me Preact a i ʻole Vue), hiki iā ʻoe ke hana like me ka hoʻohana ʻana iā MDX.
He ʻatikala ākea kēia o nā mea hana no ke kākau ʻana i nā palapala a me ka hana ʻana i nā alakaʻi. ʻAʻole nā mea hana a pau i helu ʻia ma ʻaneʻi e hoʻohana i ka MDX, akā ke hoʻohui ʻia nei i loko o nā mea hana palapala.
He aha ka MDX?
waihona .mdx loaʻa ka syntax like me Markdown, akā hiki iā ʻoe ke hoʻokomo i nā mea JSX pili a hoʻokomo iā lākou i kāu ʻike. Aia ke kākoʻo no nā ʻāpana Vue i ka alpha. No ka hoʻomaka ʻana e hana me MDX, e hoʻokomo wale i ka "Create React App". Aia nā plugins no Next.js a me Gatsby. Loaʻa i ka mana hou o Docusaurus (version 2) ke kākoʻo maoli.
Ke kākau ʻana i nā palapala me Docusaurus
Ua kākau ʻo Docusaurus ma Facebook. Hoʻohana lākou iā ia ma kēlā me kēia papahana open source koe React. Ma waho o ka hui e hoʻohana ʻia e Redux, Prettier, Gulp a me Babel.
Nā papahana e hoʻohana ana iā Docusaurus.
Hiki ke hoʻohana ʻia ʻo Docusaurus e kākau kekahi palapala, ʻaʻole wale e wehewehe i ka frontend. Loaʻa iā React ma lalo o ka puʻu, akā ʻaʻole pono ʻoe e kamaʻāina me ia e hoʻohana ai. Lawe ʻo ia i kāu mau faila Markdown, kahi kiʻi kilokilo a hoʻonohonoho maikaʻi ʻia, ʻano a heluhelu ʻia nā palapala me kahi hoʻolālā nani.
Ma ka pūnaewele Redux hiki iā ʻoe ke ʻike i ka maʻamau Docusaurus template
Hiki i nā pūnaewele i kūkulu ʻia me Docusaurus ke komo pū me kahi blog e pili ana iā Markdown. Hoʻopili koke ʻia ʻo Prism.js no ka hōʻailona syntax. ʻOiai ke ʻike ʻia nei ʻo Docusaurus i kēia manawa, ua ʻike ʻia ʻo ia ka mea hana maikaʻi loa o 2018 ma StackShare.
Nā koho hana maʻiʻo ʻē aʻe
Hoʻolālā kūikawā ʻia ʻo Docusaurus no ka hana ʻana i nā palapala. ʻOiaʻiʻo, aia he miliona a hoʻokahi ala e hana ai i kahi pūnaewele - hiki iā ʻoe ke kau i kāu hoʻonā ponoʻī ma kekahi ʻōlelo, CMS, a i ʻole e hoʻohana i kahi mea hoʻoheheʻe pūnaewele static.
No ka laʻana, hoʻohana nā palapala no React, ʻōnaehana hoʻolālā IBM, Apollo a me Ghost CMS iā Gatsby - kahi mea hoʻomohala pūnaewele static i hoʻohana pinepine ʻia no nā blog. Inā hana ʻoe me Vue, a laila he koho maikaʻi ʻo VuePress iā ʻoe. ʻO kahi koho ʻē aʻe e hoʻohana i kahi generator i kākau ʻia ma Python - MkDocs. He kumu wehe a hoʻonohonoho ʻia me ka hoʻohana ʻana i hoʻokahi faila YAML. He koho maikaʻi nō hoʻi ʻo GitBook, akā manuahi wale ia no nā hui lehulehu a me nā hui ʻaʻole kālepa. Hiki iā ʻoe ke hoʻouka wale i nā faila mardown me ka hoʻohana ʻana iā Git a hana pū me lākou ma Github.
Nā ʻāpana palapala: Docz, Storybook a me Styleguidist
Nā alakaʻi, ka hoʻolālā ʻōnaehana, nā hale waihona puke - ʻo nā mea āu i kapa ai iā lākou, ua kaulana loa ia i kēia mau lā. ʻO ka hiki ʻana mai o nā ʻāpana hana e like me React a me nā mea hana i ʻōlelo ʻia ma ʻaneʻi ua hoʻololi iā lākou mai nā hana lapuwale i mea pono.
Hana like ka puke moʻolelo, Docz a me Styleguidist: hōʻike i nā mea pili a kākau i kā lākou API. Hiki i kahi papahana ke loaʻa i nā ʻāpana he mau haneli a i ʻole haneli - me nā mokuʻāina a me nā ʻano like ʻole. Inā makemake ʻoe e hoʻohana hou ʻia nā ʻāpana, pono e ʻike nā kānaka aia lākou. No ka hana ʻana i kēia, e helu wale i nā ʻāpana. Hāʻawi nā alakaʻi i kahi hiʻohiʻona maʻalahi o kāu mau ʻāpana āpau. Kōkua kēia i ka mālama ʻana i ka ʻike like ʻole a pale i ka hana hou.
Hāʻawi kēia mau mea hana i kahi ala kūpono e nānā i nā mokuʻāina like ʻole. Hiki ke paʻakikī ke hana hou i kēlā me kēia mokuʻāina o kahi ʻāpana i ka pōʻaiapili o kahi noi maoli. Ma kahi o ke kaomi ʻana i ka noi maoli, pono ke kūkulu ʻana i kahi ʻāpana ʻokoʻa. Hiki ke hoʻohālikelike ʻia nā mokuʻāina paʻakikī (e like me ka hoʻouka ʻana).
Me ka hōʻike ʻike maka o nā mokuʻāina like ʻole a me kahi papa inoa o nā waiwai, pono pinepine e kākau i kahi wehewehe ākea o ka ʻike - nā kumu hoʻolālā, nā hihia hoʻohana, a i ʻole nā wehewehe o nā hopena hoʻāʻo mea hoʻohana. He maʻalahi loa ke aʻo ʻana ʻo Markdown - ʻo ka mea maikaʻi loa, pono nā alakaʻi i kahi kumu waiwai no nā mea hoʻolālā a me nā mea hoʻomohala. Hāʻawi ʻo Docz, Styleguidist, a me Storybook i kahi ala e hoʻohui maʻalahi iā Markdown me nā ʻāpana.
ʻO Docz
I kēia manawa, hana wale ʻo Docz me React, akā ke hoʻomaka nei ka hana ikaika e kākoʻo iā Preact, Vue a me nā ʻāpana pūnaewele. ʻO Docz ka mea hou loa o nā mea hana ʻekolu, akā ua hiki iā ia ke hōʻiliʻili ma luna o 14 mau hōkū ma Github. Hoʻokomo ʻo Docz i ʻelua ʻāpana − <Playground> и < Props >. Lawe ʻia lākou a hoʻohana ʻia i nā faila .mdx.
import { Playground, Props } from "docz";
import Button from "../src/Button";
## You can _write_ **markdown**
### You can import and use components
<Button>click</Button>Hiki iā ʻoe ke kāʻei i kāu ʻāpana React ponoʻī me <Playground>e hana i kahi analogue o ka CodePen i kūkulu ʻia a i ʻole CodeSandbox - ʻo ia hoʻi, ʻike ʻoe i kāu ʻāpana a hiki ke hoʻoponopono.
<Playground>
<Button>click</Button>
</Playground><Props> e hōʻike i nā waiwai āpau i loaʻa no kahi ʻāpana React i hāʻawi ʻia, nā waiwai paʻamau, a inā makemake ʻia ka waiwai.
<Props of={Button} />ʻO wau iho, ʻike wau ʻo kēia ala MDX ka mea maʻalahi loa e hoʻomaopopo a maʻalahi hoʻi e hana pū me.
Inā makemake ʻoe i ka Gatsby static site generator, hāʻawi ʻo Docz i kahi hoʻohui maikaʻi.
Kaila alakai
E like me Docz, kākau ʻia nā hiʻohiʻona me ka hoʻohana ʻana i ka syntax Markdown. Hoʻohana ʻo Styleguidist i nā poloka code Markdown (ʻekolu puʻupuʻu) i nā faila maʻamau .md faila, ʻaʻole MDX.
```js
<Button onClick={() => console.log('clicked')>Push Me</Button>Hōʻike pinepine nā poloka code ma Markdown i ke code. Ke hoʻohana nei ʻo Styleguidist, kekahi poloka o ke code me kahi ʻōlelo leo js, jsx ai ole ia, javascript e hāʻawi ʻia ma ke ʻano he ʻāpana React. E like me Docz, hiki ke hoʻoponopono ke code - hiki iā ʻoe ke hoʻololi i nā waiwai a ʻike koke i ka hopena.
E hana 'akomi 'o Styleguidist i papa waiwai mai PropTypes, Flow a i 'ole Typescript declarations.
Kākoʻo ʻo Styleguidist iā React a me Vue.
Puke moʻolelo
Hoʻonoho ʻia ka puke moʻolelo iā ia iho ma ke ʻano he "kaiapuni hoʻomohala ʻāpana UI." Ma kahi o ke kākau ʻana i nā mea hoʻohālike i loko o nā faila Markdown a i ʻole MDX, kākau ʻoe moʻolelo mōʻaukala i loko o nā faila Javascript. История palapala i ke kūlana kiko'ī o kekahi mea. No ka laʻana, loaʻa paha i kekahi ʻāpana nā moʻolelo no kahi mokuʻāina i hoʻouka ʻia a me kahi mokuʻāina kīnā (pilikia).
storiesOf('Button', module)
.add('disabled', () => (
<Button disabled>lorem ipsum</Button>
))ʻOi aku ka paʻakikī o ka puke moʻolelo ma mua o Styleguidist a me Docz. Akā i ka manawa like, ʻo kēia ka koho kaulana loa; ʻoi aku ka nui o ka papahana ma mua o 36 mau hōkū ma Github. He papahana hāmama me nā mea kōkua 000 a me nā limahana manawa piha. Hoʻohana ʻia e Airbnb, Algolia, Atlassian, Lyft a me Salesforce. Kākoʻo ka moʻolelo moʻolelo i nā framework ʻoi aku ma mua o nā mea hoʻokūkū - React, React Native, Vue, Angular, Mithril, Ember, Riot, Svelte a me HTML maʻamau.
Ma kahi hoʻokuʻu e hiki mai ana e hōʻike ʻia nā hiʻohiʻona mai Docz a me MDX.
# Button
Some _notes_ about your button written with **markdown syntax**.
<Story name="disabled">
<Button disabled>lorem ipsum</Button>
</Story>E holo mālie ana nā hiʻohiʻona hou o ka puke moʻolelo i nā mahina e hiki mai ana a me he mea lā he pae nui ia i mua.
Nā hopena
Hoʻohanohano ʻia nā pōmaikaʻi o kahi waihona kumu ma nā miliona o nā ʻatikala ma Medium. Ke hana maikaʻi ʻia, maʻalahi lākou e hana i nā huahana pili a mālama i ka ʻike. ʻOiaʻiʻo, ʻaʻohe o kēia mau mea hana e hoʻokumu i kahi ʻōnaehana hoʻolālā. Pono kēia i ka hoʻolālā akahele a me CSS. Akā ke hiki mai ka manawa e hiki ai i ka hui holoʻokoʻa kahi ʻōnaehana hoʻolālā, Docz, Storybook a me Styleguidist nā koho maikaʻi loa.
Mai ka mea unuhi. ʻO kēia kaʻu ʻike mua ma Habré. Inā ʻike ʻoe i nā hemahema, a i ʻole he mau manaʻo no ka hoʻomaikaʻi ʻana i ka ʻatikala, e kākau mai iaʻu i kahi leka pilikino.
Source: www.habr.com