แนวทางการใช้ชีวิต - MDX และเฟรมเวิร์กอื่นๆ

คุณอาจมีโครงการโอเพ่นซอร์สที่ดีกว่า แต่ถ้าไม่มีเอกสารประกอบที่ดี โอกาสที่โครงการจะไม่มีวันหมดไป ในสำนักงาน เอกสารที่ดีจะทำให้คุณไม่ต้องตอบคำถามเดิมๆ ซ้ำแล้วซ้ำเล่า การจัดทำเอกสารยังช่วยให้แน่ใจว่าผู้คนสามารถเข้าใจโครงการได้หากพนักงานหลักออกจากบริษัทหรือมีการเปลี่ยนแปลงบทบาท หลักเกณฑ์แบบสดช่วยให้มั่นใจได้ถึงความสมบูรณ์ของข้อมูล

หากคุณต้องการเขียนข้อความยาวๆ Markdown เป็นทางเลือกที่ยอดเยี่ยมแทน HTML บางครั้งไวยากรณ์ Markdown ไม่เพียงพอ ในกรณีนี้ เราสามารถใช้ HTML ข้างในได้ ตัวอย่างเช่น องค์ประกอบที่กำหนดเอง ดังนั้น หากคุณกำลังสร้างระบบการออกแบบที่มีส่วนประกอบของเว็บแบบเนทีฟ การรวมส่วนประกอบเหล่านั้นไว้ในเอกสารข้อความจึงเป็นเรื่องง่าย หากคุณใช้ React (หรือเฟรมเวิร์ก JSX อื่นๆ เช่น Preact หรือ Vue) คุณก็สามารถทำได้เช่นเดียวกันกับ MDX

บทความนี้เป็นภาพรวมกว้างๆ ของเครื่องมือสำหรับการเขียนเอกสารและการสร้างแนวปฏิบัติ ไม่ใช่เครื่องมือทั้งหมดที่แสดงรายการที่นี่ใช้ MDX แต่เครื่องมือดังกล่าวจะรวมอยู่ในเครื่องมือเอกสารมากขึ้นเรื่อยๆ

MDX คืออะไร?

ไฟล์ .mdx มีไวยากรณ์เหมือนกับ Markdown แต่อนุญาตให้คุณนำเข้าส่วนประกอบ JSX แบบโต้ตอบและฝังลงในเนื้อหาของคุณ การรองรับคอมโพเนนต์ Vue อยู่ในอัลฟ่า ในการเริ่มทำงานกับ MDX เพียงติดตั้ง "สร้างแอป React" มีปลั๊กอินสำหรับ Next.js และ Gatsby Docusaurus เวอร์ชันถัดไป (เวอร์ชัน 2) จะมีการสนับสนุนในตัวด้วย

การเขียนเอกสารด้วย Docusaurus

Docusaurus เขียนบน Facebook พวกเขาใช้มันในทุกโครงการโอเพ่นซอร์สยกเว้น React นอกบริษัท Redux, Prettier, Gulp และ Babel ใช้มัน

โครงการที่ใช้ Docusaurus

Docusaurus สามารถใช้ในการเขียน ใด เอกสาร ไม่ใช่แค่อธิบายส่วนหน้าเท่านั้น มี React อยู่ใต้ฝากระโปรง แต่คุณไม่จำเป็นต้องคุ้นเคยกับมันเพื่อใช้งาน ใช้ไฟล์ Markdown ของคุณ เพียงเล็กน้อยของเวทมนตร์และเอกสารที่มีโครงสร้างดี จัดรูปแบบและอ่านง่ายพร้อมการออกแบบที่สวยงามก็พร้อมแล้ว

คุณสามารถดูเทมเพลต Docusaurus เริ่มต้นได้ที่เว็บไซต์ Redux

ไซต์ที่สร้างด้วย 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>เพื่อสร้างอะนาล็อกของ 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 มาก แต่ในขณะเดียวกันนี่เป็นตัวเลือกที่ได้รับความนิยมมากที่สุดใน Github โครงการนี้มีดาวมากกว่า 36 ดวง นี่เป็นโครงการโอเพ่นซอร์สที่มีผู้ร่วมให้ข้อมูล 000 คนและพนักงานติดตาม ใช้โดย Airbnb, Algolia, Atlassian, Lyft และ Salesforce หนังสือนิทานรองรับเฟรมเวิร์กมากกว่าคู่แข่ง - 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 จะค่อยๆ ทยอยเปิดตัวในอีกไม่กี่เดือนข้างหน้า และดูเหมือนว่านี่จะเป็นการก้าวไปข้างหน้าครั้งใหญ่

ผลของการ

ประโยชน์ของไลบรารีรูปแบบได้รับการยกย่องในบทความนับล้านบนสื่อ เมื่อทำได้ดีจะทำให้ง่ายต่อการสร้างผลิตภัณฑ์ที่เกี่ยวข้องและรักษาเอกลักษณ์ แน่นอนว่าไม่มีเครื่องมือใดที่จะสร้างระบบการออกแบบได้อย่างน่าอัศจรรย์ สิ่งนี้ต้องการการออกแบบอย่างระมัดระวังและการออกแบบ CSS แต่เมื่อถึงเวลาต้องทำให้ระบบการออกแบบพร้อมใช้งานสำหรับทั้งบริษัท Docz, Storybook และ Styleguidist เป็นตัวเลือกที่ยอดเยี่ยม

จากนักแปล นี่เป็นประสบการณ์ครั้งแรกของฉันเกี่ยวกับHabré หากคุณพบข้อผิดพลาดใด ๆ หรือมีคำแนะนำในการปรับปรุงบทความ - เขียนในส่วนบุคคล

ที่มา: will.com