ຄໍາແນະນໍາສົດ - MDX ແລະກອບອື່ນໆ

ທ່ານສາມາດມີໂຄງການແຫຼ່ງເປີດທີ່ດີທີ່ສຸດ, ແຕ່ຖ້າມັນບໍ່ມີເອກະສານທີ່ດີ, ໂອກາດທີ່ມັນຈະບໍ່ມີວັນອອກ. ໃນຫ້ອງການ, ເອກະສານທີ່ດີຈະປ້ອງກັນບໍ່ໃຫ້ເຈົ້າຕອບຄໍາຖາມດຽວກັນ. ເອກະສານຍັງຮັບປະກັນວ່າປະຊາຊົນສາມາດເຂົ້າໃຈໂຄງການຖ້າຫາກວ່າພະນັກງານທີ່ສໍາຄັນອອກຈາກບໍລິສັດຫຼືການປ່ຽນແປງພາລະບົດບາດ. ຂໍ້ແນະນຳການດຳລົງຊີວິດຈະຊ່ວຍຮັບປະກັນຄວາມສົມບູນຂອງຂໍ້ມູນ.

ຖ້າທ່ານຕ້ອງການຂຽນຂໍ້ຄວາມຍາວ, Markdown ແມ່ນທາງເລືອກທີ່ດີກັບ HTML. ບາງຄັ້ງ syntax Markdown ແມ່ນບໍ່ພຽງພໍ. ໃນກໍລະນີນີ້ພວກເຮົາສາມາດນໍາໃຊ້ HTML ພາຍໃນມັນ. ຕົວຢ່າງ, ອົງປະກອບທີ່ກໍາຫນົດເອງ. ດັ່ງນັ້ນ, ຖ້າທ່ານກໍາລັງສ້າງລະບົບການອອກແບບທີ່ມີອົງປະກອບເວັບພື້ນເມືອງ, ພວກເຂົາສາມາດຖືກລວມເຂົ້າໃນເອກະສານຂໍ້ຄວາມໄດ້ງ່າຍ. ຖ້າທ່ານກໍາລັງໃຊ້ React (ຫຼືກອບ JSX ອື່ນໆເຊັ່ນ Preact ຫຼື Vue), ທ່ານສາມາດເຮັດສິ່ງດຽວກັນໂດຍໃຊ້ MDX.

ບົດຄວາມນີ້ເປັນພາບລວມຢ່າງກວ້າງຂວາງຂອງເຄື່ອງມືສໍາລັບການຂຽນເອກະສານແລະການສ້າງຄໍາແນະນໍາ. ບໍ່ແມ່ນເຄື່ອງມືທັງຫມົດທີ່ລະບຸໄວ້ຢູ່ທີ່ນີ້ໃຊ້ MDX, ແຕ່ມັນໄດ້ຖືກລວມເຂົ້າໃນເຄື່ອງມືເອກະສານຫຼາຍຂຶ້ນ.

MDX ແມ່ນຫຍັງ?

ເອກະສານ .mdx ມີ syntax ດຽວກັນກັບ Markdown, ແຕ່ອະນຸຍາດໃຫ້ທ່ານນໍາເຂົ້າອົງປະກອບ JSX ແບບໂຕ້ຕອບແລະຝັງພວກມັນເຂົ້າໄປໃນເນື້ອຫາຂອງທ່ານ. ຮອງຮັບອົງປະກອບ Vue ຢູ່ໃນອັນຟາ. ເພື່ອເລີ່ມຕົ້ນການເຮັດວຽກກັບ MDX, ພຽງແຕ່ຕິດຕັ້ງ "Create React App". ມີ plugins ສໍາລັບ Next.js ແລະ Gatsby. ສະບັບຕໍ່ໄປຂອງ Docusaurus (ຮຸ່ນ 2) ຍັງຈະມີການສະຫນັບສະຫນູນພື້ນເມືອງ.

ການຂຽນເອກະສານກັບ Docusaurus

Docusaurus ຂຽນໃນ Facebook. ພວກເຂົາໃຊ້ມັນໃນທຸກໆໂຄງການແຫຼ່ງເປີດຍົກເວັ້ນ React. ພາຍນອກບໍລິສັດມັນຖືກນໍາໃຊ້ໂດຍ Redux, Prettier, Gulp ແລະ Babel.

ໂຄງການທີ່ໃຊ້ Docusaurus.

Docusaurus ສາມາດຖືກນໍາໃຊ້ເພື່ອຂຽນ ທຸກໆ ເອກະສານ, ບໍ່ພຽງແຕ່ອະທິບາຍ frontend. ມັນມີ React ພາຍໃຕ້ຝາປິດ, ແຕ່ທ່ານບໍ່ ຈຳ ເປັນຕ້ອງຄຸ້ນເຄີຍກັບມັນເພື່ອໃຊ້ມັນ. ມັນໃຊ້ເວລາໄຟລ໌ Markdown ຂອງທ່ານ, pinch ຂອງ magic ແລະເອກະສານທີ່ມີໂຄງສ້າງທີ່ດີ, ຮູບແບບແລະສາມາດອ່ານໄດ້ດ້ວຍການອອກແບບທີ່ສວຍງາມແມ່ນກຽມພ້ອມ.

ຢູ່ໃນເວັບໄຊທ໌ Redux ທ່ານສາມາດເບິ່ງແມ່ແບບ Docusaurus ມາດຕະຖານ

ເວັບໄຊທ໌ທີ່ສ້າງຂຶ້ນດ້ວຍ Docusaurus ຍັງສາມາດປະກອບມີ blog ທີ່ອີງໃສ່ Markdown. Prism.js ຖືກເຊື່ອມຕໍ່ທັນທີສໍາລັບການເນັ້ນໃສ່ syntax. ເຖິງວ່າຈະມີຄວາມຈິງທີ່ວ່າ Docusaurus ປະກົດວ່າຂ້ອນຂ້າງບໍ່ດົນມານີ້, ມັນໄດ້ຖືກຮັບຮູ້ວ່າເປັນເຄື່ອງມືທີ່ດີທີ່ສຸດຂອງ 2018 ໃນ StackShare.

ຕົວເລືອກການສ້າງເນື້ອຫາອື່ນໆ

Docusaurus ຖືກອອກແບບໂດຍສະເພາະສໍາລັບການສ້າງເອກະສານ. ແນ່ນອນ, ມີວິທີການຫນຶ່ງລ້ານແລະວິທີການສ້າງເວັບໄຊທ໌ - ທ່ານສາມາດປະຕິບັດການແກ້ໄຂຂອງທ່ານເອງໃນພາສາໃດກໍ່ຕາມ, CMS, ຫຼືໃຊ້ເຄື່ອງສ້າງເວັບໄຊທ໌ແບບຄົງທີ່.

ຕົວຢ່າງ, ເອກະສານສໍາລັບ React, ລະບົບການອອກແບບ IBM, Apollo ແລະ Ghost CMS ໃຊ້ Gatsby - ເຄື່ອງຈັກສ້າງສະຖານທີ່ແບບຄົງທີ່ທີ່ມັກຈະໃຊ້ສໍາລັບ blogs. ຖ້າທ່ານເຮັດວຽກກັບ Vue, ຫຼັງຈາກນັ້ນ VuePress ເປັນທາງເລືອກທີ່ດີສໍາລັບທ່ານ. ທາງເລືອກອື່ນແມ່ນໃຊ້ເຄື່ອງກໍາເນີດໄຟຟ້າທີ່ຂຽນໃນ Python - MkDocs. ມັນເປັນແຫຼ່ງເປີດແລະກໍາຫນົດຄ່າໂດຍໃຊ້ໄຟລ໌ YAML ດຽວ. GitBook ຍັງເປັນທາງເລືອກທີ່ດີ, ແຕ່ມັນບໍ່ເສຍຄ່າສໍາລັບທີມງານສາທາລະນະແລະບໍ່ແມ່ນການຄ້າເທົ່ານັ້ນ. ທ່ານຍັງສາມາດອັບໂຫລດໄຟລ໌ mardown ໂດຍໃຊ້ Git ແລະເຮັດວຽກກັບພວກມັນໃນ Github.

ອົງປະກອບຂອງເອກະສານ: Docz, Storybook ແລະ Styleguidist

ຄໍາແນະນໍາ, ການອອກແບບລະບົບ, ຫ້ອງສະຫມຸດອົງປະກອບ - ສິ່ງໃດກໍ່ຕາມທີ່ທ່ານໂທຫາພວກເຂົາ, ມັນໄດ້ກາຍເປັນທີ່ນິຍົມຫຼາຍໃນບໍ່ດົນມານີ້. ການມາເຖິງຂອງກອບອົງປະກອບເຊັ່ນ React ແລະເຄື່ອງມືທີ່ໄດ້ກ່າວມານີ້ໄດ້ປ່ຽນພວກມັນຈາກໂຄງການ vanity ໄປສູ່ເຄື່ອງມືທີ່ເປັນປະໂຫຍດ.

Storybook, Docz ແລະ Styleguidist ທັງຫມົດເຮັດສິ່ງດຽວກັນ: ສະແດງອົງປະກອບການໂຕ້ຕອບແລະບັນທຶກ API ຂອງພວກເຂົາ. ໂຄງ​ການ​ຫນຶ່ງ​ສາ​ມາດ​ມີ​ຫຼາຍ​ສິບ​ຫຼື​ແມ່ນ​ແຕ່​ຫຼາຍ​ຮ້ອຍ​ຄົນ​ຂອງ​ອົງ​ປະ​ກອບ - ທັງ​ຫມົດ​ທີ່​ມີ​ລັດ​ແລະ​ຮູບ​ແບບ​ທີ່​ແຕກ​ຕ່າງ​ກັນ​. ຖ້າທ່ານຕ້ອງການໃຫ້ອົງປະກອບຖືກນໍາມາໃຊ້ໃຫມ່, ປະຊາຊົນຈໍາເປັນຕ້ອງຮູ້ວ່າມັນມີຢູ່. ເພື່ອເຮັດສິ່ງນີ້, ພຽງແຕ່ຈັດລາຍການອົງປະກອບ. ຂໍ້ແນະນຳໃຫ້ພາບລວມທີ່ຊອກຫາໄດ້ງ່າຍຂອງອົງປະກອບທັງໝົດຂອງເຈົ້າ. ນີ້ຊ່ວຍຮັກສາຄວາມສອດຄ່ອງຂອງສາຍຕາແລະຫຼີກເວັ້ນການເຮັດວຽກຊ້ໍາຊ້ອນ.

ເຄື່ອງມືເຫຼົ່ານີ້ສະຫນອງວິທີທີ່ສະດວກໃນການເບິ່ງລັດທີ່ແຕກຕ່າງກັນ. ມັນສາມາດເປັນການຍາກທີ່ຈະແຜ່ພັນແຕ່ລະລັດຂອງອົງປະກອບໃນສະພາບການຂອງຄໍາຮ້ອງສະຫມັກທີ່ແທ້ຈິງ. ແທນທີ່ຈະຄລິກໃສ່ຄໍາຮ້ອງສະຫມັກຕົວຈິງ, ມັນເປັນມູນຄ່າທີ່ຈະພັດທະນາອົງປະກອບແຍກຕ່າງຫາກ. ສະຖານະການທີ່ຍາກທີ່ຈະເຂົ້າເຖິງ (ເຊັ່ນ: ສະຖານະໂຫຼດ) ສາມາດຈໍາລອງໄດ້.

ຄຽງຄູ່ກັບການສະແດງພາບຂອງລັດຕ່າງໆແລະບັນຊີລາຍຊື່ຂອງຄຸນສົມບັດ, ມັນມັກຈະຈໍາເປັນຕ້ອງຂຽນຄໍາອະທິບາຍທົ່ວໄປຂອງເນື້ອຫາ - design rationales, use case, or descriptions of user testing results . 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 site static generator, Docz ສະເຫນີການເຊື່ອມໂຍງທີ່ດີ.

ຄູ່ມືແບບ

ເຊັ່ນດຽວກັນກັບ Docz, ຕົວຢ່າງຖືກຂຽນໂດຍໃຊ້ syntax Markdown. Styleguidist ໃຊ້ລະຫັດ Markdown blocks (triple quotes) ໃນໄຟລ໌ປົກກະຕິ .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. ເລື່ອງ ບັນທຶກສະຖານະສະເພາະຂອງອົງປະກອບໃດໜຶ່ງ. ຕົວຢ່າງ, ອົງປະກອບໃດໜຶ່ງອາດມີປະຫວັດສຳລັບສະຖານະທີ່ໂຫຼດແລ້ວ ແລະສະຖານະທີ່ຖືກປິດການນຳໃຊ້ (disabled).

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 ຈະເປີດຕົວເທື່ອລະກ້າວໃນສອງສາມເດືອນຂ້າງໜ້າ ແລະເບິ່ງຄືວ່າມັນຈະເປັນບາດກ້າວອັນໃຫຍ່ຫຼວງ.

ຜົນໄດ້ຮັບ

ຜົນປະໂຫຍດຂອງຫ້ອງສະຫມຸດຮູບແບບແມ່ນ extolled ໃນລ້ານບົດຄວາມໃນຂະຫນາດກາງ. ເມື່ອເຮັດໄດ້ດີ, ພວກເຂົາເຮັດໃຫ້ມັນງ່າຍຕໍ່ການສ້າງຜະລິດຕະພັນທີ່ກ່ຽວຂ້ອງແລະຮັກສາຕົວຕົນ. ແນ່ນອນ, ບໍ່ມີເຄື່ອງມືເຫຼົ່ານີ້ຈະສ້າງລະບົບການອອກແບບຢ່າງມະຫັດສະຈັນ. ນີ້ຮຽກຮ້ອງໃຫ້ມີການອອກແບບລະມັດລະວັງແລະ CSS. ແຕ່ໃນເວລາທີ່ມັນມາເຖິງເວລາທີ່ຈະເຮັດໃຫ້ລະບົບການອອກແບບສາມາດເຂົ້າເຖິງບໍລິສັດທັງຫມົດ, Docz, Storybook ແລະ Styleguidist ແມ່ນທາງເລືອກທີ່ດີ.

ຈາກນັກແປ. ນີ້ແມ່ນປະສົບການທໍາອິດຂອງຂ້ອຍກ່ຽວກັບ Habre. ຖ້າ​ຫາກ​ທ່ານ​ພົບ​ເຫັນ​ຄວາມ​ບໍ່​ຖືກ​ຕ້ອງ​, ຫຼື​ມີ​ຄໍາ​ແນະ​ນໍາ​ສໍາ​ລັບ​ການ​ປັບ​ປຸງ​ບົດ​ຄວາມ​, ຂຽນ​ໃຫ້​ຂ້າ​ພະ​ເຈົ້າ​ໃນ​ຂໍ້​ຄວາມ​ສ່ວນ​ບຸກ​ຄົນ​.

ແຫຼ່ງຂໍ້ມູນ: www.habr.com