Docusaurus: วิธีการสร้างเอกสารทางเทคนิคระดับมืออาชีพ

หากคุณมีไลบรารีโค้ด เฟรมเวิร์ก หรือผลิตภัณฑ์ SaaS อยู่ในมือ คุณคงสังเกตเห็นว่า... จัดระเบียบข้อมูล สำหรับผู้ใช้งานแล้ว มันเป็นเรื่องปวดหัวจริงๆ ไม่จำเป็นต้องเสียเวลาหลายสัปดาห์ในการเขียนโปรแกรมระบบตั้งแต่เริ่มต้น หรือต้องมาต่อสู้กับระบบจัดการเนื้อหา (CMS) ที่ยุ่งยาก ในเมื่อมีเครื่องมือที่ออกแบบมาเพื่อสิ่งนี้โดยเฉพาะอยู่แล้ว นี่คือจุดที่ [เครื่องมือ/แอป/อุปกรณ์] เข้ามามีบทบาท โดคูซอรัสเครื่องมือโอเพนซอร์สชั้นเยี่ยมที่สร้างโดยทีมงาน Facebook ซึ่งเปลี่ยนบันทึก Markdown ของคุณให้กลายเป็นเว็บไซต์ระดับมืออาชีพได้ในพริบตา

สิ่งที่ทำให้เครื่องมือนี้ดึงดูดใจคือ มันไม่ได้แค่พิมพ์ข้อความลงบนหน้าจอเท่านั้น แต่มันเป็น... ตัวสร้างเว็บไซต์แบบคงที่ (SSG) มันใช้ React ซึ่งหมายความว่าคุณจะได้ความเร็วของเว็บไซต์แบบคงที่ แต่มีประสิทธิภาพของแอปพลิเคชันสมัยใหม่ครบครัน เหมาะสำหรับผู้ที่มองหาสิ่งที่เบา ปลอดภัย และที่สำคัญที่สุดคือดูแลรักษาง่ายมาก โดยไม่ต้องยุ่งยากกับฐานข้อมูลที่ซับซ้อน

Docusaurus คืออะไรกันแน่ และทำงานอย่างไร?

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

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

การติดตั้งและการทดสอบระบบของโครงการ

เพื่อให้โครงการของคุณมีความน่าเชื่อถือ สิ่งแรกที่คุณต้องทำคือติดตั้งระบบบางอย่างก่อน Node.js (เวอร์ชัน 16.14 หรือสูงกว่า)(แม้ว่าจะแนะนำให้ใช้เวอร์ชัน 20 ขึ้นไปสำหรับ v3 ก็ตาม) เมื่อคุณเตรียมสภาพแวดล้อมพร้อมแล้ว คุณไม่จำเป็นต้องกำหนดค่าแต่ละโฟลเดอร์ทีละรายการ คุณสามารถเรียกใช้คำสั่งได้เลย npx create-docusaurus@latest my-docs classic เพื่อสร้างโครงสร้างพื้นฐาน

บทความที่เกี่ยวข้อง:

วิธีการเพิ่มเครื่องมือค้นหาลงใน Docusaurus และเพิ่มประสิทธิภาพเอกสารของคุณ

ค่าที่ตั้งไว้ล่วงหน้าชื่อ "คลาสสิก" เป็นค่าที่แนะนำมากที่สุด เพราะมันช่วยให้คุณทำเช่นนั้นได้อยู่แล้ว ชุดอุปกรณ์ครบชุดปลั๊กอินเอกสารประกอบ โมดูลบล็อก และธีมภาพที่กลมกลืนกัน เพื่อดูความคืบหน้าของงานแบบเรียลไทม์ เพียงแค่เรียกใช้คำสั่ง npm startขั้นตอนนี้จะตั้งค่าเซิร์ฟเวอร์ภายในเครื่อง หากคุณพร้อมที่จะอัปโหลดไปยังเครือข่าย ให้ใช้คำสั่งต่อไปนี้ npm run build โปรแกรมนี้จะสร้างโฟลเดอร์ที่มีไฟล์ HTML, CSS และ JS พร้อมใช้งานสำหรับเซิร์ฟเวอร์ใดก็ได้

ทำความเข้าใจโครงสร้างไฟล์

เมื่อคุณเปิดโปรเจ็กต์ คุณจะเห็นว่าทุกอย่างถูกจัดระเบียบไว้อย่างดีเยี่ยม คุณจึงไม่หลงทาง โฟลเดอร์นั้น... /docs คือหัวใจหลัก โฟลเดอร์ /src/pages คือโฟลเดอร์หลักของเว็บไซต์ หากคุณต้องการเพิ่มข่าวสารหรือการอัปเดต โฟลเดอร์ /blog คือที่ที่คุณควรไป ในทางกลับกัน หากคุณต้องการสร้างหน้าเว็บเฉพาะ เช่น ส่วน "ติดต่อเรา" หรือหน้า Landing Page คุณควรไปที่ /src/pages

มีไฟล์สองไฟล์ที่คุณควรให้ความสนใจเป็นพิเศษ ไฟล์แรกคือ docusaurus.config.jsซึ่งเปรียบเสมือนสมองของโปรเจ็กต์ จากตรงนี้คุณสามารถเปลี่ยนชื่อเว็บไซต์ สี เมนูนำทาง และส่วนท้ายของเว็บไซต์ได้ ส่วนที่สองคือ sidebars.jsโดยที่คุณกำหนด ลำดับของเอกสาร ในแถบด้านข้าง คุณสามารถเพิ่มได้ด้วยตนเอง หรือปล่อยให้ระบบสร้างโดยอัตโนมัติตามโครงสร้างโฟลเดอร์ของคุณ

พลังของ MDX และการสร้างเนื้อหา

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

เอกสารทุกฉบับเริ่มต้นด้วย ส่วนหน้านี่คือบล็อกเมตาเดตาที่อยู่ตอนต้นไฟล์ ซึ่งคุณใช้กำหนดรหัสหน้า ชื่อเรื่อง และตำแหน่งในแถบด้านข้าง โครงสร้างนี้ช่วยให้ Docusaurus จัดการ URL ได้อย่างชาญฉลาด สร้างเส้นทางที่ชัดเจน เช่น tudominio.com/docs/guia-inicio โดยไม่ต้องตั้งค่าเส้นทางด้วยตนเอง

การปรับแต่งรูปลักษณ์และประสบการณ์ผู้ใช้

หากคุณไม่พอใจกับการออกแบบเริ่มต้น คุณสามารถปรับแต่งได้หลายวิธี วิธีที่ง่ายที่สุดคือการแก้ไขไฟล์ custom.cssDocusaurus ใช้เฟรมเวิร์ก CSS อนันต์ดังนั้น คุณจึงสามารถเปลี่ยนตัวแปรสีหลักหรือขนาดตัวอักษรได้โดยไม่ทำให้ดีไซน์โดยรวมเสียหาย

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

ความท้าทายในการจัดทำเอกสาร API

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

เพื่อแก้ไขปัญหานี้ มีสองแนวทาง แนวทางแรกคือการใช้ปลั๊กอินจากภายนอก หรือผสานรวมเครื่องมือต่างๆ เช่น Redoc หรือ Stoplight Elements แนวทางที่สอง ซึ่งอาจมีประสิทธิภาพมากที่สุดสำหรับทีมขนาดใหญ่ คือการรวม Docusaurus เข้ากับเครื่องมือเฉพาะทาง เช่น อะพิด็อกเครื่องมือเหล่านี้ช่วยให้คุณสามารถนำเข้าข้อมูลจำเพาะของ OpenAPI หรือ Swagger และสร้างเอกสารทางเทคนิคโดยอัตโนมัติ ซึ่งสามารถผสานรวมเข้ากับระบบนิเวศของ Docusaurus ได้อย่างราบรื่น เพื่อมอบประสบการณ์การพัฒนาที่สมบูรณ์แบบ

การค้นหา การกำหนดเวอร์ชัน และการปรับใช้ขั้นสุดท้าย

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

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

เมื่อพูดถึงการเผยแพร่ คุณมีตัวเลือกมากมาย เนื่องจากเป็นเว็บไซต์แบบคงที่ คุณจึงสามารถใช้ Vercel, Netlify, GitHub Pages หรือแม้แต่บริการโฮสติ้งเฉพาะทางอย่าง Kinsta คุณเพียงแค่เชื่อมต่อ Git repository ของคุณและระบุคำสั่ง build เท่านั้น npm run build และกำหนดโฟลเดอร์เอาต์พุตเป็น build.

Docusaurus วางตำแหน่งตัวเองเป็นโซลูชันที่แข็งแกร่งซึ่งผสมผสานความเรียบง่ายของการเขียนด้วย Markdown เข้ากับความยืดหยุ่นของ React ทำให้ผู้พัฒนาทุกคนสามารถสร้างพอร์ทัลช่วยเหลือระดับมืออาชีพที่ปรับให้เหมาะสมกับ SEO และทำงานได้อย่างรวดเร็วเป็นพิเศษ โดยไม่มีความซับซ้อนทางเทคนิคมากเกินไป

แดเนียล เทอร์ราซา

บรรณาธิการเชี่ยวชาญด้านเทคโนโลยีและอินเทอร์เน็ตด้วยประสบการณ์มากกว่าสิบปีในสื่อดิจิทัลต่างๆ ฉันทำงานเป็นบรรณาธิการและผู้สร้างเนื้อหาให้กับบริษัทอีคอมเมิร์ซ การสื่อสาร การตลาดออนไลน์ และการโฆษณา ฉันยังได้เขียนไว้ในเว็บไซต์เศรษฐศาสตร์ การเงิน และภาคส่วนอื่นๆ ด้วย งานของฉันก็คือความหลงใหลของฉันเช่นกัน ตอนนี้ผ่านบทความของฉันใน Tecnobitsฉันพยายามสำรวจข่าวสารและโอกาสใหม่ ๆ ที่โลกแห่งเทคโนโลยีมอบให้เราทุกวันเพื่อปรับปรุงชีวิตของเรา