แยกสามแนวคิดที่มักถูกเรียกรวมกัน
Markdown เป็นรูปแบบข้อความสำหรับเนื้อหา เช่น หัวข้อ รายการ ตาราง และ Code Block ส่วน Mermaid เป็นภาษาข้อความสำหรับประกาศ Diagram ขณะที่ Visual Editor ใช้การลากวางและเชื่อม Node บน Canvas
BranchGuide ใช้ Markdown ภายใน Node และรองรับ Mermaid เฉพาะ subset สำหรับแลกเปลี่ยนโครงสร้าง จึงไม่ถือว่า Mermaid ทั้งหมดหรือ Markdown ใด ๆ สามารถแปลงเป็น Graph ได้โดยไม่มีข้อจำกัด
จุดแข็งและข้อแลกเปลี่ยน
เลือกจากวิธีที่ทีมแก้และอ่านงานจริง ไม่ใช่จากความคุ้นเคยของผู้เขียนคนเดียว
| หัวข้อ | Mermaid | Visual Editor |
|---|---|---|
| การแก้โครงสร้าง | เร็วสำหรับคนคุ้น syntax | เห็นตำแหน่งและเส้นทางทันที |
| Version Control | Diff เป็นข้อความอ่านง่าย | ควรเก็บ JSON ที่มี schema |
| Layout | Renderer จัดให้เป็นหลัก | ลากเองหรือ Auto Layout |
| เนื้อหาแต่ละ Node | เหมาะกับ Label สั้น | เก็บ Markdown และชนิดเนื้อหาได้มากกว่า |
Workflow แบบผสมที่รักษาข้อมูลสำคัญ
เริ่มจาก Mermaid เมื่อมีโครงสร้างอยู่ในเอกสารหรือ Repository แล้ว Import มาตรวจรายงาน จากนั้นใช้ Visual Editor ปรับ Layout และเติมรายละเอียด เก็บ BranchGuide JSON เป็นสำเนาหลักของเนื้อหาเต็ม และ Export Mermaid เมื่อผู้รับต้องการเฉพาะโครง
อย่าคาดว่า Export Mermaid แล้ว Import กลับจะรักษาข้อมูลทุกชนิด เพราะ Screenshot, Warning, Markdown ยาว หรือ Styling อาจไม่มีตัวแทนใน subset
- Import syntax ที่รองรับ
- อ่าน Import Report
- เติมข้อมูลที่ Mermaid แทนไม่ได้
- สำรอง JSON ก่อนส่งออก format อื่น
ข้อควรระวังเมื่อนำเข้าเนื้อหาจากภายนอก
ไฟล์นำเข้าคือข้อมูลที่ไม่ควรเชื่อถือ ต้องจำกัดขนาด Parse ด้วย schema ปฏิเสธ URL scheme อันตราย และไม่ execute directive หรือ script จาก Mermaid, Markdown หรือ JSON
Preview Markdown ควรปิด Raw HTML ลิงก์ภายนอกต้องใช้ noopener noreferrer และรูปภาพควรมาจากแหล่งที่นโยบายอนุญาต การแสดงข้อความได้ไม่แปลว่าควรเรียกทรัพยากรทุก URL โดยอัตโนมัติ