Та хамгийн сайн нээлттэй эхийн төсөлтэй байж болно, гэхдээ энэ нь сайн баримт бичиггүй бол хэзээ ч амжилтад хүрэхгүй байх магадлалтай. Оффисын хувьд сайн бичиг баримт нь таныг ижил асуултанд хариулахад саад болно. Баримт бичиг нь гол ажилтнууд компанийг орхих эсвэл үүрэг нь өөрчлөгдсөн тохиолдолд хүмүүст төслийг ойлгох боломжийг баталгаажуулдаг. Амьд удирдамж нь мэдээллийн бүрэн бүтэн байдлыг хангахад тусална.
Хэрэв та урт текст бичих шаардлагатай бол Markdown бол HTML-ийн гайхалтай хувилбар юм. Заримдаа Markdown синтакс хангалтгүй байдаг. Энэ тохиолдолд бид дотор нь HTML ашиглаж болно. Жишээлбэл, захиалгат элементүүд. Тиймээс, хэрэв та уугуул вэб бүрэлдэхүүн хэсгүүдтэй дизайны системийг барьж байгаа бол тэдгээрийг текстийн баримт бичигт хялбархан оруулах боломжтой. Хэрэв та React (эсвэл Preact эсвэл Vue гэх мэт өөр JSX framework) ашиглаж байгаа бол MDX-тэй ижил зүйлийг хийж болно.
Энэ нийтлэл нь баримт бичиг бичих, зааварчилгааг бий болгох хэрэгслүүдийн өргөн тойм юм. Энд жагсаагдсан бүх хэрэгслүүд MDX ашигладаггүй ч баримтжуулалтын хэрэгслүүдэд улам бүр нэмэгдэж байна.
MDX гэж юу вэ?
файл .mdx нь Markdown-тай ижил синтакстай боловч интерактив JSX бүрэлдэхүүн хэсгүүдийг импортлох, тэдгээрийг агуулгадаа оруулах боломжийг танд олгоно. Vue бүрэлдэхүүн хэсгүүдийн дэмжлэг альфа байна. MDX-тэй ажиллаж эхлэхийн тулд "Create React App" програмыг суулгана уу. Next.js болон Gatsby-д зориулсан залгаасууд байдаг. Docusaurus-ийн дараагийн хувилбар (хувилбар 2) нь мөн төрөлх дэмжлэгтэй байх болно.
Docusaurus ашиглан бичиг баримт бичих
Docusaurus Facebook дээр бичжээ. Тэд үүнийг React-аас бусад бүх нээлттэй эхийн төсөл дээр ашигладаг. Компаниас гадуур Redux, Prettier, Gulp, Babel компаниуд ашигладаг.
Docusaurus ашигладаг төслүүд.
Докузаврыг бичихэд ашиглаж болно ямар ч баримт бичиг, зөвхөн урд талын хэсгийг тайлбарлахаас гадна. Бүрээсний доор React байдаг, гэхдээ үүнийг ашиглахын тулд та үүнийг мэддэг байх шаардлагагүй. Энэ нь таны Markdown файлуудыг авч, ид шидтэй, сайн бүтэцтэй, форматтай, уншихад хялбар, үзэсгэлэнтэй дизайнтай баримт бичиг бэлэн боллоо.
Redux вэбсайтаас та стандарт Docusaurus загварыг харж болно
Docusaurus-аар бүтээгдсэн вэбсайтууд нь Markdown дээр суурилсан блог агуулж болно. Prism.js нь синтаксийг тодруулахын тулд шууд холбогддог. Docusaurus харьцангуй саяхан гарч ирсэн хэдий ч энэ нь StackShare дээр 2018 оны шилдэг хэрэгсэлээр тодорсон.
Бусад контент үүсгэх сонголтууд
Docusaurus нь баримт бичиг үүсгэхэд тусгайлан зориулагдсан. Мэдээжийн хэрэг, вэбсайт хийх сая нэг арга байдаг - та өөрийн шийдлийг ямар ч хэл дээр, CMS-д байршуулах эсвэл статик сайт үүсгэгчийг ашиглаж болно.
Жишээлбэл, React, IBM дизайны систем, Apollo болон Ghost CMS-д зориулсан баримт бичиг нь блогт ихэвчлэн ашиглагддаг статик сайт үүсгэгч Gatsby-ийг ашигладаг. Хэрэв та Vue-тэй ажилладаг бол VuePress бол танд тохиромжтой сонголт юм. Өөр нэг сонголт бол Python - MkDocs дээр бичигдсэн генераторыг ашиглах явдал юм. Энэ нь нээлттэй эх сурвалж бөгөөд нэг YAML файл ашиглан тохируулагдсан. GitBook нь бас сайн сонголт боловч зөвхөн нийтийн болон арилжааны бус багуудад үнэ төлбөргүй байдаг. Та мөн Git ашиглан mardown файлуудыг байршуулж, Github дээр ажиллах боломжтой.
Баримтжуулах бүрэлдэхүүн хэсгүүд: Docz, Storybook болон Styleguidist
Удирдамж, системийн дизайн, бүрэлдэхүүн хэсгүүдийн сангууд - та тэдгээрийг юу гэж нэрлэхээс үл хамааран сүүлийн үед маш их алдартай болсон. React гэх мэт бүрэлдэхүүн хэсгүүд болон энд дурдсан хэрэгслүүд гарч ирснээр тэдгээрийг хоосон төслөөс хэрэгтэй хэрэгсэл болгон өөрчилсөн.
Storybook, Docz болон Styleguidist бүгд ижил зүйлийг хийдэг: интерактив элементүүдийг харуулах, тэдгээрийн API-г баримтжуулах. Төсөл нь олон арван эсвэл бүр хэдэн зуун бүрэлдэхүүн хэсгүүдтэй байж болно - бүгд өөр өөр төлөв, хэв маягтай. Хэрэв та бүрэлдэхүүн хэсгүүдийг дахин ашиглахыг хүсч байвал хүмүүс тэдгээр нь байгаа эсэхийг мэдэх хэрэгтэй. Үүнийг хийхийн тулд зүгээр л бүрэлдэхүүн хэсгүүдийг каталогид оруулаарай. Удирдамжууд нь таны бүх бүрэлдэхүүн хэсгүүдийг олоход хялбар тоймыг өгдөг. Энэ нь харааны тогтвортой байдлыг хадгалж, дахин давтагдах ажил хийхээс зайлсхийхэд тусалдаг.
Эдгээр хэрэгслүүд нь янз бүрийн төлөвийг үзэхэд тохиромжтой арга юм. Бүрэлдэхүүн хэсгийн төлөв бүрийг бодит хэрэглээний хүрээнд хуулбарлахад хэцүү байж болно. Бодит програм дээр дарахын оронд тусдаа бүрэлдэхүүн хэсгийг хөгжүүлэх нь зүйтэй. Хүрэхэд хэцүү төлөвүүдийг (ачаалах төлөв гэх мэт) дуурайж болно.
Төрөл бүрийн төлөв байдал, шинж чанаруудын жагсаалтыг харуулахын зэрэгцээ агуулгын ерөнхий тайлбарыг бичих шаардлагатай байдаг - дизайны үндэслэл, хэрэглээний тохиолдол эсвэл хэрэглэгчийн туршилтын үр дүнгийн тайлбар. Markdown сурахад маш хялбар байдаг - хамгийн тохиромжтой нь удирдамж нь дизайнерууд болон хөгжүүлэгчдэд зориулсан нийтлэг эх сурвалж байх ёстой. Docz, Styleguidist болон Storybook нь Markdown-ыг бүрэлдэхүүн хэсгүүдтэй хялбархан холих аргыг санал болгодог.
Докз
Одоогоор Docz нь зөвхөн React-тэй ажилладаг боловч Preact, Vue болон вэб бүрэлдэхүүн хэсгүүдийг дэмжих идэвхтэй ажил хийгдэж байна. Docz бол гурван хэрэглүүрийн хамгийн сүүлийнх нь боловч Github дээр 14 гаруй од цуглуулж чадсан. Docz нь хоёр бүрэлдэхүүн хэсгийг танилцуулж байна - <Playground> и < Props >. Тэдгээрийг импортлож файлд ашигладаг .mdx.
import { Playground, Props } from "docz";
import Button from "../src/Button";
## You can _write_ **markdown**
### You can import and use components
<Button>click</Button>Та өөрийн React бүрэлдэхүүн хэсгүүдийг боож болно <Playground>суулгасан CodePen эсвэл CodeSandbox-ийн аналогийг үүсгэхийн тулд та өөрийн бүрэлдэхүүн хэсгийг харж, засварлаж болно.
<Playground>
<Button>click</Button>
</Playground><Props> өгөгдсөн React бүрэлдэхүүн хэсгийн бүх боломжит шинж чанарууд, өгөгдмөл утгууд болон өмч шаардлагатай эсэхийг харуулах болно.
<Props of={Button} />Би хувьдаа MDX-д суурилсан энэхүү аргыг ойлгоход хамгийн хялбар, ажиллахад хамгийн хялбар арга гэж би боддог.
Хэрэв та Gatsby статик сайт үүсгэгчийн шүтэн бишрэгч бол Docz гайхалтай интеграцийг санал болгож байна.
Загварын хөтөч
Docz-ийн нэгэн адил жишээг Markdown синтакс ашиглан бичдэг. Styleguidist нь ердийн файлуудад Markdown кодын блокуудыг (гурвалсан хашилт) ашигладаг .md файлууд, MDX биш.
```js
<Button onClick={() => console.log('clicked')>Push Me</Button>Markdown дахь кодын блокууд нь ихэвчлэн кодыг харуулдаг. Styleguidist-ийг ашиглах үед хэлний тагтай кодын дурын блок js, jsx буюу javascript React бүрэлдэхүүн хэсэг болгон үзүүлэх болно. Docz-ийн нэгэн адил кодыг засах боломжтой - та шинж чанарыг өөрчилж, үр дүнг шууд харах боломжтой.
Styleguidist нь PropTypes, Flow эсвэл Typescript мэдэгдлээс өмчийн хүснэгтийг автоматаар үүсгэх болно.
Styleguidist одоогоор React болон Vue-г дэмждэг.
Түүхийн ном
Өгүүллийн ном нь өөрийгөө "UI бүрэлдэхүүн хэсэг хөгжүүлэх орчин" гэж үздэг. Markdown эсвэл MDX файл дотор жишээ бүрэлдэхүүн хэсгүүдийг бичихийн оронд та бичнэ түүхүүд Javascript файл дотор. түүх бүрэлдэхүүн хэсгийн тодорхой төлөвийг баримтжуулах. Жишээлбэл, бүрэлдэхүүн хэсэг нь ачаалагдсан төлөв болон идэвхгүй байдлын түүхтэй байж болно (тахир дутуу).
storiesOf('Button', module)
.add('disabled', () => (
<Button disabled>lorem ipsum</Button>
))Өгүүллийн ном нь Styleguidist, Docz-ээс хамаагүй илүү төвөгтэй юм. Гэхдээ үүнтэй зэрэгцэн энэ бол хамгийн алдартай сонголт бөгөөд төсөл нь Github дээр 36 гаруй одтой. Энэ нь 000 хувь нэмэр оруулагч, орон тооны ажилтантай нээлттэй эхийн төсөл юм. Үүнийг Airbnb, Algolia, Atlassian, Lyft, Salesforce ашигладаг. Storybook нь өрсөлдөгчдөөсөө илүү олон хүрээг дэмждэг - React, React Native, Vue, Angular, Mithril, Ember, Riot, Svelte болон ердийн HTML.
Ирээдүйн хувилбарт Docz-ийн онцлогууд байх бөгөөд MDX-ийг танилцуулах болно.
# Button
Some _notes_ about your button written with **markdown syntax**.
<Story name="disabled">
<Button disabled>lorem ipsum</Button>
</Story>Storybook-ийн шинэ боломжууд дараагийн хэдэн сарын хугацаанд аажмаар гарч ирэх бөгөөд энэ нь урагшлах том алхам байх шиг байна.
Үр дүн
Загварын номын сангийн ашиг тусыг Medium дээрх сая сая нийтлэлд алдаршуулсан байдаг. Сайн хийгдсэн тохиолдолд тэдгээр нь холбогдох бүтээгдэхүүнийг бий болгох, мөн чанарыг хадгалахад хялбар болгодог. Мэдээжийн хэрэг, эдгээр хэрэгслүүдийн аль нь ч дизайны системийг ид шидээр бий болгохгүй. Энэ нь нарийн дизайн, CSS шаарддаг. Гэхдээ дизайны системийг бүх компанид хүртээмжтэй болгох цаг ирэхэд Docz, Storybook, Styleguidist зэрэг нь маш сайн сонголт юм.
Орчуулагчаас. Энэ бол Habré дээр миний анхны туршлага юм. Хэрэв та ямар нэгэн алдаа олж мэдсэн эсвэл нийтлэлийг сайжруулах санал байвал над руу хувийн мессежээр бичээрэй.
Эх сурвалж: www.habr.com