Atom + Markdown Preview Enhancedで図形交じりのmarkdownを書く
注: 新しい情報は以下を参照
はてなブログにmarkdown記法使ってますよね？
ソフトウェア系の仕事や、はてなでは、markdown記法は当たり前。
ブラウザがあれば編集は出来るのですが、やはり専用エディタが書きやすい。
エディタとしては、vs codeやAtomなどいくつか候補があがるが、今回は、markdownのプレビューを見ながら、図がテキストで書けちゃうAtomのエディタ拡張を紹介。
例えば、こんなコードブロックを埋め込むと・・・
```@mermaid graph LR A --> B B --> C C --> A ```
こんな図ができちゃう。勿論独自拡張だが、通常のmarkdown+.pngファイルへの変換もまとめてできるところがすごい。
他の人も紹介しているけど、はてな等での活用方法を具体的に説明しとく。
その前にRedmine vs GitLabどっち?
仕事では、Redmineを使っていて、今、GitLabを試行している。
Redmineでは、markdownではなくて、textileという記法で書いている。
記法の比較は以下が詳しい。
さて、Redmineはログインして編集中に中座したりするとタイムアウトして編集がパーになることがあったり、間違って保存せずにブラウザを閉じてしまうことがあったりで、長い文書を編集するときはエディタで編集していた。
長い場合、エディタで編集するのはmarkdownも同じだが、markdown + graphviz + plantumlの複合ドキュメント化の課題解決が出来ず、モヤモヤしてた。
たまたまQiitaでmarkdown記法を調べてたら、以下の記事を見つけて興味を惹かれた。
Atom Editor
前提条件として、Windows 10 Pro (1607)、開発環境なし、とします。*1
Markdown Preview Enhanced
次に、お目当ての拡張機能。デモの画像をみると凄さが分かる。
- File > Settings > Installでmarkdown-previewを検索
- markdown-previewをDisableに変更
- markdown-preview-enhancedをInstall
- Settings > Use standard code fencing for graphs
- GraphViz/PlantUMLで標準のコードブロックが使用できるようにチェックを外す (2017/04/21追記)
- Settings > Image save path
- textileに変換してRedmineなどで使用するなら./に変更、それ以外は./assetsに変更
プレビューのショートカットはCtrl + Shift + m
Language GFM Enhanced
シンタックス・ハイライトの拡張をするために以下も入れる。
- File > Settings > Installでlanguage-gfmを検索
- language-gfmをDisableに変更
- language-gfm-enhancedをInstall
PlantUMLによるUML図の描画について
PlantUMLの図を描く場合は以下も必要。mermaidで代用が利くので、PlantUMLにこだわる場合にのみインストールすればよい。
Java SE Development Kit
PlantUMLがJavaで実装されているので、JDKをインストールする。
自分の環境ではJREだとだめだった。
Java SE - Downloads | Oracle Technology Network | Oracle
- Java SE Development Kitのダウンロードページを開く
- Accept License Agreementを選択
- 今回はWindows 64bit版をダウンロード (ご自分の環境に合わせてどうぞ)
- セットアップの実行
- コマンドプロンプト(管理者)で以下を実行 (バージョンは変わる場合があるので注意)
GraphViz
PlantUMLでシーケンス図以外の図を描く場合はDOT言語をGraph図に変換するためにGraphVizを使用しているようなので、GraphVizをインストールする。
Graphviz | Graphviz - Graph Visualization Software
- Downloadページを開く
- 一番下のAgreeを選択
- 左のメニューのDownload>Windowsを選択
- graphviz-2.38.msiを選択 (数字はバージョンアップしたら変わる)
- セットアップの実行
- “Just me"は"Everyone"に変更
- コマンドプロンプト(管理者)で以下を実行 (バージョンやパスは変わる場合があるので注意)
SETX /M GRAPHVIZ_DOT “C:\Program Files (x86)\Graphviz2.38\bin\dot.exe”
この他、GraphVizは様々なツールで利用されているので、このbinフォルダをPATHに追加しておくことをお勧めする。
なお、Markdown Preview EnhancedではDOT言語を図に変換するのにGraphVizではなくViz.jsを使用しているので、PlantUMLを使用せずにGraph図を描くだけなら、GraphVizをインストールしなくても以下で図が描ける。
```@viz
digraph
{
A -> B
}
```
注: コードブロックのvizをdotにしてもプレビューは出来るが、画像化するときにエラーメッセージの画像が出来るので注意
外部ファイル読み込みも出来る。
@import "test.dot"
test.dot
digraph
{
A -> B -> C
}
PlantUML
Markdown Preview Enhancedには、PlantUMLが含まれている。
このため、本家のサイトからダウンロードは不要だが、記法については以下を参照。
```@plantuml @startuml class A class B class C A --|> B A *- C @enduml ```
外部ファイル読み込みも出来る。
@import "test.puml"
test.puml
@startuml class A class B A --> B @enduml
# plantuml-viewer
@importで外部のPlantUMLファイルを読み込む場合は、外部ファイル単体でプレビュー出来るように以下もインストールすると良い。
プレビューのショートカットはCtrl + Alt + p
不具合が色々あるが、去年から更新が止まっている。
plantuml-previewとPlantUMLをインストールすると良い。
graphviz-preview-plus
@importで外部のGraphVizファイルを読み込む場合は、外部ファイル単体でプレビュー出来るように以下もインストールすると良い。
プレビューのショートカットはCtrl + Shift + v
図埋め込みmarkdownの作成
GraphVizやPlantUML、および、単体のプレビュー拡張でも画像保存は出来るが、markdown-preview-enhancedはリアルタイムプレビューしながら、一発で画像化が出来るのが良い。
残念ながら、markdown-preview-enhancedでも、勿論その他のエディタでも、GitLabなどの拡張記法に対応したものはない。
当然、markdown-preview-enhancedの独自拡張は互換性がないので、以下の方法で互換性のある文書に差し替えると良い。
注: 画像はAtomで開いたフォルダのルートのAssetsフォルダに出来るので、常にmarkdownファイルのフォルダの下に出来るように、Settingsで/Assetsを./Assetsに変更してください。
- プレビュー画面で右クリック
- “Save as markdown"を選択
- 図が画像として保存される
- DOT言語では、コードブロックがvizではなくdotだと画像にエラーメッセージが出力されるのでvizにしておくこと
- コードブロックが図に置き換えられたmarkdownファイルが保存される
- GitHub/GitLabでは、作成された画像と作成されたmarkdownファイルをコミット
- はてなでは、元のmarkdownファイルの内容をコピペして、後から画像をアップロードする
textileへのコンバートがpandocで出来るらしいが試せていないので、そのうち試して報告する予定。
リクエストを出してみた
@importで外部ファイルを読み込んだ時に"Save as markdown"で保存する画像ファイルの名前についてのリクエストを出しています。
こちらの記事もどうぞ。
