Live ուղեցույցներ - MDX և այլ շրջանակներ

Դուք կարող եք ունենալ լավագույն բաց կոդով նախագիծը, բայց եթե այն չունենա լավ փաստաթղթեր, հավանական է, որ այն երբեք չի գործի: Գրասենյակում լավ փաստաթղթերը կխանգարեն ձեզ պատասխանել նույն հարցերին: Փաստաթղթերը նաև ապահովում են, որ մարդիկ կարող են հասկանալ նախագիծը, եթե հիմնական աշխատակիցները լքեն ընկերությունը կամ փոխվեն դերերը: Կենցաղային ուղեցույցները կօգնեն ապահովել տվյալների ամբողջականությունը:

Եթե ​​Ձեզ անհրաժեշտ է երկար տեքստ գրել, Markdown-ը հիանալի այլընտրանք է HTML-ին: Երբեմն Markdown-ի շարահյուսությունը բավարար չէ: Այս դեպքում մենք կարող ենք օգտագործել HTML դրա ներսում։ Օրինակ՝ մաքսային տարրեր։ Հետևաբար, եթե դուք դիզայնի համակարգ եք կառուցում հայրենի վեբ բաղադրիչներով, դրանք հեշտությամբ կարող են ներառվել տեքստային փաստաթղթերում: Եթե ​​դուք օգտագործում եք React (կամ որևէ այլ JSX շրջանակ, ինչպիսին Preact-ը կամ Vue-ն է), կարող եք նույն բանն անել 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:

Docusaurus-ը կարող է օգտագործվել գրելու համար որեւէ փաստաթղթեր, ոչ միայն ճակատը նկարագրելու համար: Այն ունի React ծածկույթի տակ, բայց այն օգտագործելու համար պարտադիր չէ ծանոթ լինել դրան: Այն վերցնում է ձեր Markdown ֆայլերը, պատրաստ է մի փոքր կախարդական և լավ կառուցվածքային, ձևաչափված և ընթեռնելի փաստաթղթեր՝ գեղեցիկ դիզայնով:

Redux-ի կայքում դուք կարող եք տեսնել ստանդարտ Docusaurus կաղապարը

Docusaurus-ով կառուցված կայքերը կարող են ներառել նաև Markdown-ի վրա հիմնված բլոգ: Prism.js-ն անմիջապես միացված է շարահյուսության ընդգծման համար: Չնայած այն հանգամանքին, որ Docusaurus-ը հայտնվեց համեմատաբար վերջերս, այն ճանաչվեց որպես 2018 թվականի լավագույն գործիք StackShare-ում։

Բովանդակության ստեղծման այլ ընտրանքներ

Docusaurus-ը հատուկ նախագծված է փաստաթղթեր ստեղծելու համար: Իհարկե, կայք ստեղծելու միլիոն ու մեկ եղանակ կա՝ դուք կարող եք տեղադրել ձեր սեփական լուծումը ցանկացած լեզվով, CMS-ով կամ օգտագործել ստատիկ կայքի գեներատոր:

Օրինակ, React-ի, IBM-ի նախագծման համակարգի, Apollo-ի և Ghost CMS-ի փաստաթղթերը օգտագործում են Gatsby-ն՝ ստատիկ կայքի գեներատոր, որը հաճախ օգտագործվում է բլոգների համար: Եթե ​​աշխատում եք Vue-ի հետ, ապա VuePress-ը լավ տարբերակ է ձեզ համար: Մեկ այլ տարբերակ է օգտագործել Python-ով գրված գեներատոր՝ MkDocs: Այն բաց կոդով է և կազմաձևված է մեկ YAML ֆայլի միջոցով: GitBook-ը նույնպես լավ տարբերակ է, բայց այն անվճար է միայն հանրային և ոչ առևտրային թիմերի համար: Կարող եք նաև պարզապես վերբեռնել mardown ֆայլեր՝ օգտագործելով Git-ը և աշխատել դրանց հետ Github-ում:

Փաստաթղթավորման բաղադրիչներ՝ Docz, Storybook և Styleguidist

Ուղեցույցներ, համակարգի ձևավորում, բաղադրիչների գրադարաններ. ինչպես էլ կոչեք դրանք, վերջին շրջանում այն ​​շատ տարածված է դարձել: React-ի նման բաղադրիչ շրջանակների հայտնվելը և այստեղ նշված գործիքները դրանք ունայն նախագծերից վերածել են օգտակար գործիքների:

Storybook-ը, Docz-ը և Styleguidist-ը նույն բանն են անում՝ ցուցադրում են ինտերակտիվ տարրեր և փաստաթղթավորում իրենց API-ն: Նախագիծը կարող է ունենալ տասնյակ կամ նույնիսկ հարյուրավոր բաղադրիչներ՝ բոլորը տարբեր վիճակներով և ոճերով: Եթե ​​ցանկանում եք, որ բաղադրիչները նորից օգտագործվեն, մարդիկ պետք է իմանան, որ դրանք գոյություն ունեն: Դա անելու համար պարզապես կատալոգավորեք բաղադրիչները: Ուղեցույցները ապահովում են ձեր բոլոր բաղադրիչների հեշտ գտնելու ակնարկ: Սա օգնում է պահպանել տեսողական հետևողականությունը և խուսափել կրկնվող աշխատանքից:

Այս գործիքները տարբեր վիճակներ դիտելու հարմար միջոց են ապահովում: Կարող է դժվար լինել բաղադրիչի յուրաքանչյուր վիճակ վերարտադրել իրական կիրառման համատեքստում: Փաստացի հավելվածի վրա սեղմելու փոխարեն արժե առանձին բաղադրիչ մշակել: Դժվար հասանելի վիճակները (օրինակ՝ բեռնման վիճակները) կարող են մոդելավորվել:

Տարբեր վիճակների տեսողական ցուցադրման և հատկությունների ցանկի հետ մեկտեղ հաճախ անհրաժեշտ է գրել բովանդակության ընդհանուր նկարագրություն՝ դիզայնի հիմնավորումներ, օգտագործման դեպքեր կամ օգտագործողների թեստավորման արդյունքների նկարագրություններ: Markdown-ը շատ հեշտ է սովորել. իդեալական տարբերակում ուղեցույցները պետք է լինեն ընդհանուր ռեսուրս դիզայներների և մշակողների համար: Docz-ը, Styleguidist-ը և Storybook-ը առաջարկում են Markdown-ը բաղադրիչների հետ հեշտությամբ խառնելու միջոց:

Docz

Ներկայումս Docz-ն աշխատում է միայն React-ի հետ, սակայն ակտիվ աշխատանք է ընթանում Preact, Vue և վեբ բաղադրիչներին աջակցելու համար: Docz-ը երեք գործիքներից ամենավերջինն է, սակայն այն կարողացել է հավաքել ավելի քան 14 աստղ Github-ում: 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-ին:

Պատմագիրք

Storybook-ը իրեն ներկայացնում է որպես «UI բաղադրիչի մշակման միջավայր»: Markdown կամ MDX ֆայլերի ներսում օրինակ բաղադրիչներ գրելու փոխարեն, դուք գրում եք Պահեստավորված նյութեր Javascript ֆայլերի ներսում: Պատմություն փաստագրել բաղադրիչի կոնկրետ վիճակը. Օրինակ, բաղադրիչը կարող է ունենալ բեռնված վիճակի և անջատված վիճակի պատմություններ (անաշխատունակ).

storiesOf('Button', module)
  .add('disabled', () => (
    <Button disabled>lorem ipsum</Button>
  ))

Storybook-ը շատ ավելի բարդ է, քան Styleguidist-ը և Docz-ը: Բայց միևնույն ժամանակ սա ամենահայտնի տարբերակն է՝ նախագիծն ունի ավելի քան 36 աստղ Github-ում: Այն բաց կոդով նախագիծ է, որն ունի 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é-ում: Եթե ​​որևէ անճշտություն եք գտնում, կամ հոդվածը բարելավելու առաջարկներ ունեք, գրեք ինձ անձնական նամակով։

Source: www.habr.com