AsciiDoc : Découvrir et maîtriser la syntaxe pour une documentation efficace
เผยแพร่เมื่อ 20 June 2025
บทนำ
AsciiDoc เป็นภาษามาร์กอัปแบบน้ำหนักเบา (lightweight markup language) ที่ออกแบบมาเพื่อเขียนเอกสารทางเทคนิคที่มีโครงสร้าง บทความ หนังสือ หรือแม้แต่การนำเสนอ โดยมีความโดดเด่นในด้านความอ่านง่าย ไวยากรณ์ที่หลากหลาย และความสามารถในการแปลงเป็นรูปแบบต่างๆ (HTML, PDF, DocBook และอื่นๆ) ในบทความนี้ เราจะสำรวจไวยากรณ์ที่จำเป็นของ AsciiDoc พร้อมนำเสนอเคล็ดลับเพื่อให้เริ่มต้นใช้งานได้อย่างรวดเร็ว
AsciiDoc คืออะไร?
AsciiDoc คือภาษาสำหรับคำอธิบายเอกสาร ซึ่งคล้ายกับ Markdown แต่มีประสิทธิภาพมากกว่า ช่วยให้สามารถจัดโครงสร้างข้อความ หัวข้อ รายการ ตาราง บล็อกโค้ด และอื่นๆ ได้อย่างมีประสิทธิภาพ ความเอนกประสงค์นี้ทำให้มันเป็นตัวเลือกยอดนิยมสำหรับการทำเอกสารโครงการโอเพนซอร์ส การเขียนหนังสือ และการเผยแพร่บนเว็บ
ทำไมต้องเลือก AsciiDoc?
-
ไวยากรณ์ที่อ่านง่ายและใช้งานได้ intuitive
-
รองรับโครงสร้างที่ซับซ้อนแบบเนทีฟ (เช่น
tableaux,notes,admonitionsและอื่นๆ) -
การสร้างหลายรูปแบบ (HTML, PDF, ePub, DocBook…)
-
ผสานการทำงานได้ง่ายกับเครื่องมือสร้างไซต์แบบสแตติก เช่น
JBakeหรือ `Antora -
การปรับแต่งขั้นสูงด้วยแอตทริบิวต์และส่วนขยาย
แผนภาพยูสเคส (Use Case Diagram)
แผนภาพยูสเคส (Use Case Diagram) ช่วยให้นำเสนอการโต้ตอบหลักระหว่างผู้ใช้และระบบ นี่คือตัวอย่างง่ายๆ สำหรับระบบเอกสาร:
@startuml :Utilisateur: --> (Rédiger documentation) :Utilisateur: --> (Générer PDF) :Utilisateur: --> (Publier sur site web) (Rédiger documentation) ..> (Générer PDF) : inclut @enduml
แผนผัง Mind Map
Mind map (แผนผังความคิด) นั้นเหมาะอย่างยิ่งสำหรับการสำรวจแนวคิดที่เกี่ยวข้องกับ AsciiDoc และความสัมพันธ์ระหว่างแนวคิดเหล่านั้น:
@startmindmap * AsciiDoc ** Syntaxe *** Titres *** Listes *** Blocs de code *** Tableaux ** Extensions *** PlantUML *** MathJax ** Export *** HTML *** PDF *** EPUB @endmindmap
ผังงาน (Flowchart)
แผนภาพลำดับขั้นตอน (flow diagram) ช่วยให้สามารถอธิบายกระบวนการสร้างเอกสาร AsciiDoc ได้ดังนี้:
@startuml start :Écrire fichier .adoc; :Ajouter images et diagrammes; if (Valider la syntaxe ?) then (oui) :Générer HTML/PDF; :Publier ou partager; else (non) :Corriger erreurs; :back to start; endif stop @enduml
โครงสร้างพื้นฐานของไฟล์ AsciiDoc
ไฟล์ AsciiDoc มักจะเริ่มต้นด้วยชื่อเรื่อง, แอตทริบิวต์ทางเลือก จากนั้นจึงตามด้วยเนื้อหาที่มีโครงสร้าง นี่คือตัวอย่างแบบย่อ:
= Titre Principal
Auteur
2024-09-03
:toc:
:icons: font
Votre contenu commence ici...ไวยากรณ์พื้นฐาน
หัวข้อและส่วนต่างๆ
AsciiDoc รองรับหัวข้อหลายระดับ:
= Titre de niveau 1
== Titre de niveau 2
=== Titre de niveau 3
==== Titre de niveau 4ข้อความตัวหนา ตัวเอียง และตัวพิมพ์แบบ monospace
*gras* _italique_ `monospace`รายการแบบสัญลักษณ์และแบบเลขลำดับ
* Élément 1
* Élément 2
. Premier
. Deuxième
. Troisièmeลิงก์และรูปภาพ
Lien standard : https://asciidoc.org[AsciiDoc]
Image : image::images/logo.png[AsciiDoc Logo]บล็อกโค้ด
[source,python]def hello(): print("Bonjour AsciiDoc !")
ตาราง
|===
| Colonne 1 | Colonne 2
| Valeur A
| Valeur B
| Valeur C
| Valeur D
|===บันทึกและคำเตือน
AsciiDoc มีบล็อกข้อมูลทางสายตาให้ใช้งานดังนี้:
NOTE: Ceci est une note importante.
TIP: Conseil utile pour l’utilisateur.
WARNING: Attention à ce point.การใช้งานแอตทริบิวต์และตัวแปร
แอตทริบิวต์ที่กำหนดเองช่วยให้สามารถนำค่ากลับมาใช้ใหม่หรือกำหนดค่าพฤติกรรมต่างๆ ได้:
:project-name: AsciiDoc Explorer
Le projet s’appelle {project-name}.กรณีการใช้งานทั่วไป
-
เอกสารโครงการโอเพนซอร์ส (README, คู่มือทางเทคนิค) - การเขียนหนังสือและอีบุ๊ก - การสร้างเว็บไซต์แบบสแตติกโดยอัตโนมัติ (JBake, Antora) - การนำเสนอทางเทคนิค
แนวทางปฏิบัติที่ดีที่สุด
-
ใช้หัวข้อที่สอดคล้องกันและสารบัญอัตโนมัติ (:toc:) - ให้ใช้คำเตือน (admonitions) เพื่อดึงดูดความสนใจไปยังจุดสำคัญต่างๆ จัดโครงสร้างไฟล์ของคุณเพื่อให้ง่ายต่อการบำรุงรักษา - ใช้ประโยชน์จากบล็อกโค้ดที่มีคำอธิบายประกอบเพื่อแสดงตัวอย่าง
บทสรุป
AsciiDoc เป็นเครื่องมือที่ทรงพลังและเข้าถึงได้ง่ายสำหรับการเขียนเอกสารทางเทคนิคหรือบทความที่มีโครงสร้าง ไวยากรณ์ที่หลากหลายเมื่อรวมกับการสร้างผลลัพธ์ได้หลายรูปแบบ ทำให้เป็นตัวเลือกที่ยอดเยี่ยมสำหรับนักพัฒนาและนักเขียนที่ต้องการความละเอียดรอบคอบ ลองใช้ AsciiDoc ในโปรเจกต์ถัดไปของคุณ แล้วคุณจะพบกับความแตกต่าง!
เพื่อศึกษาเพิ่มเติม
-
เอกสารอย่างเป็นทางการ: https://asciidoc.org - Asciidoctor : https://asciidoctor.org - JBake และ AsciiDoc : https://jbake.org/docs/2.6.4/#asciidoc_support
แบ่งปันประสบการณ์และเคล็ดลับของคุณในคอมเมนต์ได้เลย!