oxdraw - เครื่องมือไดอะแกรมแบบอิงโค้ด

 (github.com/RohanAdwankar)
25 คะแนน โดย GN⁺ 2025-10-27 | 1 ความคิดเห็น | แชร์ทาง WhatsApp
  • oxdraw คือ เครื่องมือ ‘Diagram as Code’ ที่เขียนด้วย Rust ออกแบบมาเพื่อให้สามารถแก้ไขไดอะแกรมแบบอิงโค้ดได้ในเชิงภาพ และคงไว้ในรูปแบบที่ทำซ้ำได้
  • ไดอะแกรมเขียนด้วย ไวยากรณ์ Mermaid และสามารถ ปรับด้วยการลาก ตำแหน่งโหนด สี และเส้นเชื่อมต่าง ๆ ผ่านเว็บอินเทอร์เฟซ
  • การแก้ไขเชิงภาพจะถูก บันทึกเป็นคอมเมนต์ภายในไฟล์ Mermaid เพื่อคงความเข้ากันได้กับเครื่องมือ Mermaid อื่น ๆ
  • ประกอบด้วย CLI และเว็บเอดิเตอร์ที่สร้างด้วย React โดยรองรับทั้ง การเรนเดอร์ผ่านบรรทัดคำสั่งและโหมดแก้ไขแบบเรียลไทม์
  • เป็นที่จับตามองในฐานะ ทางเลือกแทนเครื่องมือ GUI อย่าง Lucidchart ด้วยการผสานประสิทธิภาพของไดอะแกรมที่สร้างจากโค้ดเข้ากับอิสระของการแก้ไขแบบภาพ

ภาพรวมโปรเจกต์

  • เป้าหมายของ oxdraw คือทำให้การ สร้างและดูแลไดอะแกรมคุณภาพสูงเป็นเรื่องง่าย ผ่านไวยากรณ์เชิงประกาศที่ทำซ้ำได้
    • ไดอะแกรมเขียนด้วยไวยากรณ์ Mermaid และปรับแต่งเชิงภาพผ่านเว็บอินเทอร์เฟซ
    • สิ่งที่ผู้ใช้แก้ไขด้วยภาพจะถูกสะท้อนกลับไปยังโค้ดต้นฉบับ ทำให้รองรับ การควบคุมเวอร์ชันและระบบอัตโนมัติ
  • การเปลี่ยนแปลงจะถูกบันทึกในรูปแบบ คอมเมนต์ (comment) ภายในไฟล์ Mermaid จึงคง ความเข้ากันได้อย่างสมบูรณ์ กับเครื่องมืออื่นในอีโคซิสเต็ม Mermaid
  • รีโพซิทอรีประกอบด้วย CLI ที่พัฒนาด้วย Rust และ เว็บอินเทอร์เฟซที่พัฒนาด้วย React โดย CLI จะคอมไพล์ไฟล์ .mmd ให้เป็นภาพ

วิสัยทัศน์ของโปรเจกต์

  • ก่อนหน้านี้ผู้พัฒนาเคยใช้ Mermaid เพื่อทำไดอะแกรมสถาปัตยกรรมหรือการแสดงภาพของโค้ดเบส แต่ต้องย้ายไปใช้ Lucidchart และเครื่องมืออื่น เนื่องจาก ข้อจำกัดด้านการแก้ไขอย่างละเอียด
  • oxdraw มีเป้าหมายจะผสาน ระบบอัตโนมัติแบบอิงโค้ดของ Mermaid เข้ากับ อิสระในการจัดวางเชิงภาพของ Lucidchart
  • แนวทางนี้ช่วยคง ความทำซ้ำได้ การทำงานร่วมกัน และศักยภาพด้านอัตโนมัติ ของไดอะแกรมที่สร้างจากโค้ด พร้อมยกระดับ คุณภาพงานภาพโดยรวม

วิธีใช้งาน

  • ติดตั้งผ่าน Cargo ได้ด้วย: cargo install oxdraw
  • เรนเดอร์ไดอะแกรม: oxdraw --input flow.mmd
  • เปิดเอดิเตอร์แบบอินเทอร์แอ็กทีฟ: oxdraw --input flow.mmd --edit
  • CLI รับไฟล์ Mermaid เป็นอินพุตและสร้างผลลัพธ์เป็น SVG หรือ PNG โดยสามารถใช้ตัวเลือก --edit เพื่อเปิด เว็บเอดิเตอร์แบบโลคัล

คำอธิบายแฟลกของ CLI

  • -i, --input : ไฟล์ซอร์ส Mermaid อินพุต
  • -o, --output : ระบุพาธสำหรับบันทึกผลลัพธ์ที่เรนเดอร์
  • --png: ส่งออกในรูปแบบ PNG
  • --scale : ปรับสเกลการเรนเดอร์ PNG (ค่าเริ่มต้น 10.0)
  • --edit: เปิดตัวแก้ไขเชิงภาพ
  • --serve-host / --serve-port : ระบุที่อยู่และพอร์ตของเซิร์ฟเวอร์เอดิเตอร์ (ค่าเริ่มต้น 127.0.0.1:5151)
  • -b, --background-color : กำหนดสีพื้นหลัง (เฉพาะ SVG)
  • -q, --quiet: ซ่อนข้อความเอาต์พุต เช่น ข้อความแจ้งว่าเรนเดอร์เสร็จแล้ว

ความสามารถฝั่งฟรอนต์เอนด์

  • การจัดการโหนดและเอดจ์
    • ลบโหนดหรือเอดจ์ที่เลือกไว้ (รองรับปุ่ม Delete/Backspace)
    • กำหนดและรีเซ็ตสีโหนด เส้นขอบ และสีข้อความแยกกันได้
    • ตั้งค่าสีเอดจ์ รูปแบบเส้น (ทึบ/ประ) และทิศทางลูกศร
    • เพิ่มและลบ จุดควบคุม (control point) ที่ลากได้บนเส้นทางของเอดจ์
  • การโต้ตอบกับแคนวาสและเอดิเตอร์
    • เมื่อลากโหนดจะแสดง การสแนปเข้ากริดและไกด์การจัดแนว
    • ย้ายโหนดด้วย Shift+ลูกศร
    • ลากแฮนเดิลของเอดจ์เพื่อแก้ไขเส้นทาง และดับเบิลคลิกเพื่อเพิ่ม/ลบแฮนเดิล
    • รองรับ การย้ายทั้งซับกราฟ — ย้ายโหนดและเอดจ์ในกลุ่มไปพร้อมกัน
    • แผงซอร์ส สะท้อนไฟล์ Mermaid แบบเรียลไทม์ พร้อมการบันทึกอัตโนมัติและสถานะต่าง ๆ (เช่น กำลังบันทึก/เกิดข้อผิดพลาด)
    • แถบเครื่องมือด้านบนจะแสดงพาธไฟล์ปัจจุบันและสถานะการบันทึก

สแตกเทคโนโลยีและไลเซนส์

  • พัฒนาด้วย Rust 55.7%, TypeScript 40.0%, CSS 3.4% และอื่น ๆ 0.9%
  • เผยแพร่ภายใต้ MIT License จึงสามารถใช้งานและแก้ไขได้อย่างอิสระ
  • ปัจจุบันมี 506 Stars และ 10 Forks สะท้อนความสนใจจากชุมชนอย่างต่อเนื่อง

สรุปภาพรวม

  • oxdraw เป็นแนวทางใหม่ที่ผสาน ระบบอัตโนมัติของการจัดการไดอะแกรมแบบอิงโค้ด เข้ากับ ความใช้งานง่ายของการแก้ไขเชิงภาพ
  • โดยยังคง ความเข้ากันได้อย่างสมบูรณ์ กับอีโคซิสเต็ม Mermaid พร้อมใช้ ประสิทธิภาพของ Rust และ UI แบบอินเทอร์แอ็กทีฟของ React
  • กำลังเป็นที่จับตามองในฐานะเครื่องมือที่มอบ เวิร์กโฟลว์ไดอะแกรมที่ทำงานร่วมกันได้ สำหรับทั้งนักพัฒนาและนักออกแบบ

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

1 ความคิดเห็น

 
GN⁺ 2025-10-27
ความคิดเห็นใน Hacker News

  • เป็นโปรเจกต์ที่เจ๋งมาก การเลือกใช้ Mermaid.js ถือว่าตอบโจทย์ เพราะน่าจะเป็นไลบรารีไดอะแกรมเชิงประกาศที่ได้รับความนิยมที่สุดในตอนนี้
    ถ้าต้องการรองรับไดอะแกรมที่ซับซ้อนกว่านี้ D2 Language ก็น่าลองดูเช่นกัน เพราะให้ แนวทางเชิงประกาศที่ยืดหยุ่นกว่า มาก

  • ส่วนตัวผมทำ MacPorts port ไว้ใช้เองแล้ว
    ถ้าได้ใช้บ่อย ๆ ก็คิดว่าจะส่งเข้าร่วมกับ คลัง MacPorts อย่างเป็นทางการ
    แต่ตอนนี้แพ็กเกจทำยาก เพราะไม่มี Git tag หรือ GitHub release ที่ผูกกับ Cargo release
    ตอนนี้เลยแก้ขัดด้วยการสมมติให้คอมมิตนี้ (9ccd9bf53f9a309ccda42b5c17e9c1056493fb90) เป็นรีลีส 0.1.0 ไปก่อน
    ดูพอร์ตที่เกี่ยวข้องได้ ที่นี่

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

    • ไอเดียน่าสนใจมาก อยากรู้ว่าป๊อปอัปนั้นตั้งใจใช้ส่วนตัว หรือเอาไว้แชร์กับทีม
      เช่น อยากให้แชร์ลิงก์แล้วอีกฝ่ายเปิดดูไดอะแกรมที่มีป๊อปอัปและโครงสร้างซ้อนได้ทันทีหรือไม่
      หรือแค่แชร์ไฟล์ .mmd แล้วเปิดด้วย CLI ได้ก็เพียงพอ
      แบบหลังน่าจะทำได้เร็ว แต่แบบแรกอาจต้องมี self-hosting แบบ ngrok หรือ deploy ขึ้นคลาวด์
      หรืออาจเพิ่มฟีเจอร์ export เป็นไฟล์ HTML เพื่อให้ป๊อปอัปทำงานได้โดยไม่ต้องใช้ CLI ก็ได้

  • ยินดีด้วยที่เปิดตัวโปรเจกต์ จุดที่น่าประทับใจคือการนิยามความสัมพันธ์ด้วยไวยากรณ์เชิงประกาศ และเปิดให้ทำ การปรับแต่งอย่างละเอียด ในแบบที่ระบบ auto-layout เดิมทำไม่ได้
    แต่ใน Cargo.toml ระบุว่าเป็นไลเซนส์ MIT ทว่าที่รีโพซิทอรียัง ไม่มีไฟล์ไลเซนส์
    ถ้าเพิ่มเข้าไปเพื่อให้ตรวจสอบได้จาก GitHub โดยตรงก็น่าจะดี

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

  • เป็นโปรเจกต์ที่จำเป็นมาก ผมใช้ PlantUML เป็นหลัก และถ้ามีคอมโพเนนต์เกิน 5 ตัว เมื่อไร จะต้องเสียเวลา 20–30% ไปกับการจัดเลย์เอาต์
    แนวทางใช้คอมเมนต์เพื่อสะท้อนเข้าไปยัง layout engine น่าสนใจดี ถ้ากำหนดพิกัดของคอมโพเนนต์บางตัวเป็น ข้อจำกัดแบบตรึงค่า แล้วให้ที่เหลือจัดวางอัตโนมัติ ก็น่าจะมีประโยชน์มาก
    ถ้าไดอะแกรมถูกจัดการเวอร์ชันไปพร้อมกับการเปลี่ยนโค้ดด้วย ก็จะทำให้ code review และการดูแลสถาปัตยกรรม เป็นธรรมชาติมากขึ้น

    • ผมก็ใช้ PlantUML บน GitLab แต่บน GitHub ต้องใช้ Mermaid เลยค่อนข้างยุ่งยาก
      คุณภาพเลย์เอาต์ของ Mermaid ไม่ค่อยดี และก็น่าเสียดายที่ GitHub เมินคำขอรองรับ PlantUML
      ดูเหมือนว่า อัตราการยอมรับแนวคิด ‘diagrams as code’ จะขึ้นอยู่กับฟอร์แมตที่แพลตฟอร์มหลักรองรับ
      มากกว่าจะสร้างมาตรฐานใหม่ ผมคิดว่าการปรับปรุงอย่าง การเรนเดอร์ตามน้ำหนักขององค์ประกอบ น่าจะเป็นไปได้จริงมากกว่า
      ประเด็นนี้มีพูดถึงใน GitHub community discussion เช่นกัน

  • อยากให้ PlantUML แก้ปัญหาแบบนี้ได้จริง ๆ

  • นี่เหมือน เวอร์ชันต่อยอดของภาษา dot ของ Graphviz
    มีตัวแปรและไวยากรณ์ที่สะอาดกว่า แต่แนวคิดพื้นฐานคล้ายกัน
    ดู เอกสาร Graphviz ได้

  • ใน Mermaid.js มีแนวคิดเรื่อง layout engine อยู่แล้ว
    อย่างเช่น @mermaid-js/layout-elk
    เลยสงสัยว่าคุณสนใจจะทำอัลกอริทึมนี้ให้เป็น auto-layout engine สำหรับ Mermaid หรือเปล่า

  • โปรเจกต์เจ๋งมาก ผมลองดูบนมือถือแล้ว แต่ ปุ่มเพิ่มโหนด ไม่แสดง
    อีกฟีเจอร์ที่อยากได้คือ การยุบโหนดลูกด้านล่าง (collapse downstream nodes) แม้อาจจะเกินขอบเขตของโปรเจกต์ไปหน่อย แต่ถ้ามีก็น่าจะดี

    • ตอนนี้ยังต้องแก้ข้อความ .mmd โดยตรงอยู่ แต่ก็คิดว่าเป็นข้อเสนอที่ดี
      ฟีเจอร์ยุบโหนดลูกด้านล่างก็น่าจะเข้ากันได้ดีกับ ฟีเจอร์แอนิเมชัน ที่ผู้ใช้อีกคนเคยขอไว้