Sizda yaxshiroq ochiq kodli loyiha bo'lishi mumkin, lekin agar u yaxshi hujjatlarga ega bo'lmasa, u hech qachon ishlamaydi. Ofisda yaxshi hujjatlar sizni bir xil savollarga qayta-qayta javob berishdan saqlaydi. Hujjatlar, shuningdek, agar asosiy xodimlar kompaniyani tark etsa yoki rollar o'zgarsa, odamlar loyihani tushunishlarini ta'minlaydi. Jonli ko'rsatmalar ma'lumotlar yaxlitligini ta'minlashga yordam beradi.
Agar siz uzun matn yozishingiz kerak bo'lsa, Markdown HTMLga ajoyib muqobildir. Ba'zan Markdown sintaksisi etarli emas. Bunday holda biz uning ichida HTML dan foydalanishimiz mumkin. Masalan, maxsus elementlar. Shuning uchun, agar siz mahalliy veb-komponentlar bilan dizayn tizimini qurayotgan bo'lsangiz, ularni matn hujjatlariga kiritish oson. Agar siz React (yoki Preact yoki Vue kabi boshqa JSX ramkalar) dan foydalansangiz, MDX bilan ham xuddi shunday qilishingiz mumkin.
Ushbu maqola hujjatlarni yozish va yo'riqnoma yaratish vositalarining keng ko'lami. Bu erda sanab o'tilgan barcha vositalar MDX dan foydalanmaydi, lekin u hujjatlar vositalariga tobora ko'proq kiritilmoqda.
MDX nima?
Fayl .mdx Markdown bilan bir xil sintaksisga ega, lekin interaktiv JSX komponentlarini import qilish va ularni tarkibingizga joylashtirish imkonini beradi. Vue komponentlarini qo'llab-quvvatlash alfada. MDX bilan ishlashni boshlash uchun "React ilovasini yaratish" ni o'rnatish kifoya. Next.js va Gatsby uchun plaginlar mavjud. Docusaurusning keyingi versiyasi (2-versiya) ham o'rnatilgan qo'llab-quvvatlashga ega bo'ladi.
Docusaurus bilan hujjatlar yozish
Bu haqda Docusaurus Facebook’da yozgan. Ular Reactdan tashqari barcha ochiq manbali loyihalarda foydalanadilar. Kompaniyadan tashqarida Redux, Prettier, Gulp va Babel undan foydalanadi.
Docusaurus ishlatadigan loyihalar.
Docusaurus yozish uchun ishlatilishi mumkin har qanday faqat frontendni tavsiflash uchun emas, balki hujjatlar. Uning ostida React mavjud, lekin undan foydalanish uchun uni bilish shart emas. Bu sizning Markdown fayllaringizni oladi, bir chimdim sehrli va yaxshi tuzilgan, formatlangan va o'qilishi mumkin bo'lgan chiroyli dizaynga ega hujjatlar tayyor.
Standart Docusaurus shablonini Redux veb-saytida ko'rishingiz mumkin.
Docusaurus bilan yaratilgan saytlar Markdown-ga asoslangan blogni ham o'z ichiga olishi mumkin. Sintaksisni ta'kidlash uchun Prism.js darhol kiritilgan. Docusaurus nisbatan yaqinda paydo bo'lganiga qaramay, u StackShare-da 2018 yilning eng yaxshi vositasi deb topildi.
Boshqa kontent yaratish imkoniyatlari
Docusaurus hujjat yaratish uchun maxsus mo'ljallangan. Albatta, veb-sayt yaratishning millionlab usullari mavjud - siz o'zingizning yechimingizni istalgan tilda, CMSda joylashtirishingiz yoki statik sayt generatoridan foydalanishingiz mumkin.
Masalan, React uchun hujjatlar, IBM dizayn tizimi, Apollo va Ghost CMS bloglar uchun tez-tez ishlatiladigan statik sayt generatori Gatsby-dan foydalanadi. Agar siz Vue bilan ishlayotgan bo'lsangiz, VuePress siz uchun yaxshi tanlovdir. Yana bir variant - Python - MkDocs-da yozilgan generatordan foydalanish. U ochiq va bitta YAML fayli bilan tuzilgan. GitBook ham yaxshi variant, lekin u faqat ochiq va notijorat jamoalar uchun bepul. Siz shunchaki git yordamida mardown fayllarini yuklashingiz va ular bilan Githubda ishlashingiz mumkin.
Komponent hujjatlari: Docz, Storybook va Styleguidist
Yo'riqnomalar, tizim dizayni, komponentlar kutubxonalari, ularni nima demoqchi bo'lsangiz, so'nggi paytlarda juda mashhur bo'ldi. React va bu yerda eslatib o'tilgan vositalar kabi komponentli ramkalarning paydo bo'lishi ularni bema'ni loyihalardan foydali vositalarga aylantirish imkonini berdi.
Hikoyalar kitobi, Docz va Styleguidist xuddi shunday qiladi: interaktiv elementlarni ko'rsatish va ularning API-larini hujjatlash. Loyiha o'nlab yoki hatto yuzlab komponentlarga ega bo'lishi mumkin, ularning barchasi turli holatlar va uslublarga ega. Agar siz komponentlarni qayta ishlatishni istasangiz, odamlar ular mavjudligini bilishlari kerak. Buning uchun komponentlarni kataloglash kifoya. Yo'riqnomalar barcha komponentlaringiz haqida osongina qidirishni ta'minlaydi. Bu vizual mustahkamlikni saqlashga va takroriy ishlarni oldini olishga yordam beradi.
Ushbu vositalar turli holatlarni ko'rishning qulay usulini ta'minlaydi. Haqiqiy dastur kontekstida komponentning har bir holatini takrorlash qiyin bo'lishi mumkin. Haqiqiy dasturni bosish o'rniga, alohida komponentni ishlab chiqishga arziydi. Erish qiyin bo'lgan holatlarni modellashtirish mumkin (masalan, yuklanish holati).
Turli holatlarning vizual namoyishi va xususiyatlar ro'yxati bilan bir qatorda, ko'pincha tarkibning umumiy tavsifini yozish kerak - dizayn asoslari, foydalanish holatlari yoki foydalanuvchi testi natijalarining tavsifi. Markdownni o'rganish juda oson - ideal holda, ko'rsatmalar dizaynerlar va ishlab chiquvchilar uchun umumiy manba bo'lishi kerak. Docz, Styleguidist va Storybook Markdownni komponentlar bilan osongina aralashtirish usulini taklif qiladi.
Docz
Hozirda Docz faqat React bilan ishlaydi, lekin Preact, Vue va veb komponentlarini qo‘llab-quvvatlash ustida faol ishlamoqda. Docz uchta vositaning eng oxirgisi, ammo Github-da 14 000 dan ortiq yulduzlarni to'plashga muvaffaq bo'ldi. Docz ikkita komponentni taqdim etadi - <Playground> и < Props >. Ular import qilinadi va fayllarda ishlatiladi .mdx.
import { Playground, Props } from "docz";
import Button from "../src/Button";
## You can _write_ **markdown**
### You can import and use components
<Button>click</Button>Siz o'zingizning React komponentlaringizni o'rashingiz mumkin <Playground>o'rnatilgan CodePen yoki CodeSandbox analogini yaratish uchun - ya'ni siz o'z komponentingizni ko'rasiz va uni tahrirlashingiz mumkin.
<Playground>
<Button>click</Button>
</Playground><Props> berilgan React komponenti uchun barcha mavjud xususiyatlarni, standart qiymatlarni va xususiyat zarurligini ko'rsatadi.
<Props of={Button} />Shaxsan men ushbu MDX-ga asoslangan yondashuvni tushunish va ishlash uchun eng oson deb bilaman.
Agar siz Gatsby-ning statik sayt generatorining muxlisi bo'lsangiz, Docz ajoyib integratsiyalarni taklif qiladi.
uslub bo'yicha mutaxassis
Docz-da bo'lgani kabi, misollar Markdown sintaksisi yordamida yoziladi. Styleguidist oddiy fayllarda Markdown kod bloklaridan (uchta tirnoq) foydalanadi .md fayllar, MDX da emas.
```js
<Button onClick={() => console.log('clicked')>Push Me</Button>Markdown-dagi kod bloklari odatda kodni ko'rsatadi. Styleguidist-dan foydalanilganda, til yorlig'i bilan har qanday kod bloki js, jsx yoki javascript React komponenti sifatida taqdim etiladi. Docz singari, kodni tahrirlash mumkin - siz xususiyatlarni o'zgartirishingiz va natijani darhol ko'rishingiz mumkin.
Styleguidist avtomatik ravishda PropTypes, Flow yoki Typescript deklaratsiyalaridan xossalar varag'ini yaratadi.
Styleguidist endi React va Vue-ni qo'llab-quvvatlaydi.
Hikoyalar kitobi
Hikoyalar kitobi o'zini "UI komponentlarini ishlab chiqish muhiti" deb biladi. Markdown yoki MDX fayllari ichida komponent misollarini yozish o'rniga, siz yozasiz tarix Javascript fayllari ichida. История komponentning o'ziga xos holatini hujjatlashtirish. Misol uchun, komponentda yuklanish holati va o'chirilgan holat uchun tarix bo'lishi mumkin (o'chirilgan).
storiesOf('Button', module)
.add('disabled', () => (
<Button disabled>lorem ipsum</Button>
))Hikoyalar kitobi Styleguidist va Docz ga qaraganda ancha murakkab. Ammo shu bilan birga, bu eng mashhur variant, Github-da loyihada 36 000 dan ortiq yulduzlar mavjud. Bu 657 ta ishtirokchi va xodimlar hamrohligidagi ochiq manbali loyiha. U Airbnb, Algolia, Atlassian, Lyft va Salesforce tomonidan qo'llaniladi. Hikoyalar kitobi raqobatchilardan ko'ra ko'proq ramkalarni qo'llab-quvvatlaydi - React, React Native, Vue, Angular, Mithril, Ember, Riot, Svelte va oddiy HTML.
Kelgusi versiyada Docz chiplari bo'ladi va MDX joriy etilmoqda.
# Button
Some _notes_ about your button written with **markdown syntax**.
<Story name="disabled">
<Button disabled>lorem ipsum</Button>
</Story>Yangi Hikoyalar kitobi xususiyatlari keyingi bir necha oy ichida asta-sekin paydo bo'ladi va bu oldinga katta qadam bo'ladi.
natijalar
Naqshlar kutubxonasining afzalliklari Medium-dagi millionlab maqolalarda maqtovga sazovor. Yaxshi bajarilganda, ular tegishli mahsulotlarni yaratish va shaxsiyatni saqlab qolishni osonlashtiradi. Albatta, ushbu vositalarning hech biri sehrli tarzda dizayn tizimini yaratmaydi. Bu ehtiyotkorlik bilan dizayn va CSS dizaynini talab qiladi. Ammo dizayn tizimini butun kompaniya uchun mavjud qilish vaqti kelganda, Docz, Storybook va Styleguidist ajoyib tanlovdir.
Tarjimondan. Bu mening Habrédagi birinchi tajribam. Agar siz biron bir noaniqlik topsangiz yoki maqolani yaxshilash bo'yicha takliflaringiz bo'lsa - shaxsiy yozing.
Manba: www.habr.com