GitHub รองรับการแสดงแผนภาพบนไฟล์ Markdown ด้วย Mermaid แล้วนะ

ในเมื่อภาพและแผนภาพเพียงภาพเดียว สามารถสื่อความหมายได้ดีกว่าคำเป็นสิบ ๆ ร้อย ๆ คำ แล้วทำไมเราไม่เอาภาพมาอธิบายซะเลยล่ะ

แสดงแผนภาพบนไฟล์ Markdown บน GitHub

แนวทางในการทำเอกสารผ่านทางไฟล์ Markdown ก็เป็นที่นิยมมากขึ้นเรื่อย ๆ เนื่องจาก เราสามารถเอาไฟล์ Markdown มารวมใน Repo ได้ (มันก็ไฟล์ Text ธรรมดานี่นา) แล้วเราได้ประโยชน์จากการใช้ Git ช่วยในการ Track การเปลี่ยนแปลง ทีนี้เราก็จะเห็นได้ว่ามีใครแก้ Code แต่ไม่ยอมแก้ Doc ตาม หรือไม่

แต่การใช้ Markdown ก็จะเจอปัญหาอยู่บ้าง เช่น การทำแผนภาพ (Diagram) ต่าง ๆ เพื่อประกอบการอธิบาย ความลำบากที่น่าจะเจอกันบ่อย ๆ ก็คือ เราต้องไปวาดแผนภาพในที่อื่น แล้วก็หาทางเอามาแปะกลับมาด้วยวิธีการใดวิธีการหนึ่ง (ก็งานเพิ่มเนาะ)

และแล้ววันนี้ก็มาถึง วันที่ GitHub ขวัญใจของเราเหล่า Dev ก็ประกาศการรอบรับการแสดงแผนภาพแบบต่าง ๆ บนไฟล์ Markdown โดยรอบรับผ่าน Mermaid’s syntax นั่นเอง

นี่ทำให้ปัญหาเหล่านี้ บรรเทาเบาบางลงไปมาก เนื่องจากการใช้ Mermaid’s syntax นั่นเป็นอะไรที่ง่ายมาก ง่ายแบบว่า ถ้าคุณพอเขียน Markdown ได้ Mermaid’s syntax ก็ไม่ใช่ปัญหาอะไรเลยครับ และตัว Mermaid เองก็สามารถใช้สร้างแผนภาพที่ใช้งานกันเยอะ ๆ ได้เลย เช่น Flow charts, Sequence diagrams, Gantt diagrams และอื่น ๆ (ดูทั้งหมดที่นี่)

ตัวอย่าง Mermaid’s syntax

flowchart LR
A[Hard] -->|Text| B(Round)
B --> C{Decision}
C -->|One| D[Result 1]
C -->|Two| E[Result 2]

ตอนเอาไปเขียนลง Markdown ก็แค่ใส่ Code block โดยบอกว่าเป็น Mermaid แล้วเดี๋ยวตอน Preview ทาง GitHub จะ Render ให้เราเองครับ

```mermaid
flowchart LR
A[Hard] -->|Text| B(Round)
B --> C{Decision}
C -->|One| D[Result 1]
C -->|Two| E[Result 2]
```

Demo

https://github.com/puuga/hello-mermaid

References

Include diagrams in your Markdown files with Mermaid | The GitHub Blog

mermaid - Markdownish syntax for generating flowcharts, sequence diagrams, class diagrams, gantt…