គោលការណ៍ណែនាំនៃការរស់នៅ - 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 design system, 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 ដំណើរការតែជាមួយ 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>ដើម្បីបង្កើត analogue នៃ 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 នឹងបង្ហាញជាសមាសធាតុប្រតិកម្ម។ ដូច 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 គឺជាជម្រើសដ៏ល្អ។

ពីអ្នកបកប្រែ។ នេះជាបទពិសោធន៍ដំបូងរបស់ខ្ញុំនៅលើ Habre ។ ប្រសិនបើអ្នករកឃើញភាពមិនត្រឹមត្រូវ ឬមានការណែនាំសម្រាប់កែលម្អអត្ថបទ សូមសរសេរមកខ្ញុំក្នុងសារផ្ទាល់ខ្លួន។

ប្រភព: www.habr.com