2014年12月4日

GitBook + PlantUML 以 Markdown 快速製作 UML 教材


GitBook 是使用 Markdown 編寫電子書的工具及平台。

Markdown 寫書在技術圈已經風行多年,而 GitBook 完美整合了 Git 版本控制,甚至直接串接 GitHub,讓寫作技術書籍更加方便。最近火紅的柯P的市政白皮書也是利用 GitBook 發行。

最近應邀到彰化某科大擔任「系統分析與設計」課程的業師,教材的準備我想拋棄去年的 Slide 作法,直接改用最近長時間投入使用的 GitBook。

使用 Markdown 格式編寫教材講義,最方便之處就是文字和程式很容易修改。所以上課過程還可以隨時增刪講義內容,即時更新發佈給學生。GitBook 平台幫了很大的忙,基本需要的功能它都能做到了(過去為做到自動化的 publish 我們甚至自己開發了 ContPub 平台XDDD)。

GitBook 本身的 off-line editor 用起來效率不佳,我還是習慣用 Vim 或 Sublime Text 編寫文字。

Markdown 的即時 Preview 是很多人在意的功能,GitBook editor 有提供 preview,但是經常遇到 crash 問題,所以我改用 console 下的 gitbook command-line 工具,這是利用 Node.js 開發的 client tool,用來將 Markdown 原始檔轉成電子書格式。

編寫軟工、系統分析的教材,最麻煩的地方就是一些 UML 繪製,每次的修改都需要找到原始檔,做完再匯出成圖片。

我找到一個 PlantUML for GitBook Plugin,這個延伸工具很棒,自動將 Markdown 裡面的 UML code block 自動轉成 SVG 的圖片。

UML code block 看起來像這樣:


轉換出來的結果(利用 gitbook serve 搭配瀏覽器 livereload 即時預覽電子書呈現效果):


原始的 PlantUML Plugin 不好用,而且 commit 到 GitBook 的 source 也無法正常轉檔,所以我 fork 一份 plugin 自己修改成堪用的版本。

GitBook PlantUML Plugin
https://github.com/lyhcode/gitbook-plugin-plantuml

這個版本修正一些問題,讓生成的圖片可以依照 section file name 放置在 .md 的相同路徑下。重要的是重新以「gitbook-plugin-plantuml」發佈到 NPM,讓 GitBook 遠端轉檔也能順利 pass(但真正的轉檔工作只能在 local 進行)。

花了幾個小時才搞定整個流暢的 UML 教材編寫流程,但做好之後真的讓教材開發效率提高不少 : ) 感謝 GitBook 讓我可以吃自己的狗食(Eat my own dog food),自己的教材自己寫,自己的教材開發工具也能自己擴充 : )


lyhcode by lyhcode
歡迎轉載,請務必註明出處!