読者です 読者をやめる 読者になる 読者になる

tmori3y2のブログ

主にWindowsのプログラムなど

Atom + Markdown Preview Enhancedで図形交じりのmarkdownを書く

はてなブログmarkdown記法使ってますよね?

ソフトウェア系の仕事や、はてなでは、markdown記法は当たり前。

ブラウザがあれば編集は出来るのですが、やはり専用エディタが書きやすい。

エディタとしては、vs codeやAtomなどいくつか候補があがるが、今回は、markdownのプレビューを見ながら、図がテキストで書けちゃうAtomのエディタ拡張を紹介。

例えば、こんなコードブロックを埋め込むと・・・

 ```@mermaid
 graph LR
 A --> B
 B --> C
 C --> A
 ```

こんな図ができちゃう。勿論独自拡張だが、通常のmarkdown+.pngファイルへの変換もまとめてできるところがすごい。

f:id:tmori3y2:20170326023455p:plain

他の人も紹介しているけど、はてな等での活用方法を具体的に説明しとく。

その前にRedmine vs GitLabどっち?

仕事では、Redmineを使っていて、今、GitLabを試行している。

Redmineでは、markdownではなくて、textileという記法で書いている。

記法の比較は以下が詳しい。

atmarksharp.v01.jp

さて、Redmineはログインして編集中に中座したりするとタイムアウトして編集がパーになることがあったり、間違って保存せずにブラウザを閉じてしまうことがあったりで、長い文書を編集するときはエディタで編集していた。

長い場合、エディタで編集するのはmarkdownも同じだが、markdown + graphviz + plantumlの複合ドキュメント化の課題解決が出来ず、モヤモヤしてた。

たまたまQiitaでmarkdown記法を調べてたら、以下の記事を見つけて興味を惹かれた。

qiita.com

Atom Editor

まず、Atomエディタをインストールする。

前提条件として、Windows 10 Pro (1607)、開発環境なし、とします。

atom.io

  • ダウンロードボタンを押してインストーラをダウンロード
  • 今回はWindows 64bit版をダウンロード (ご自分の環境に合わせてどうぞ)

Markdown Preview Enhanced

次に、お目当ての拡張機能。デモの画像をみると凄さが分かる。

atom.io

  • 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

シンタックス・ハイライトの拡張をするために以下も入れる。

atom.io

  • 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版をダウンロード (ご自分の環境に合わせてどうぞ)
  • セットアップの実行
  • コマンドプロンプト(管理者)で以下を実行 (バージョンは変わる場合があるので注意)

    SETX /M JAVA_HOME “C:\Program Files\Java\jdk1.8.0_121”

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にしてもプレビューは出来るが、画像化するときにエラーメッセージの画像が出来るので注意

f:id:tmori3y2:20170326024452p:plain

外部ファイル読み込みも出来る。

@import "test.dot"

test.dot

digraph
{
  A -> B -> C
}

f:id:tmori3y2:20170326024500p:plain

PlantUML

Markdown Preview Enhancedには、PlantUMLが含まれていると思われる。

このため、本家のサイトからダウンロードは不要だが、記法については以下を参照。

plantuml.com

  ```@plantuml
  @startuml
  
  class A
  class B
  class C
  
  A --|> B
  A *- C
  
  @enduml
  ```

f:id:tmori3y2:20170326024525p:plain

外部ファイル読み込みも出来る。

@import "test.puml"

test.puml

@startuml

class A
class B

A --> B

@enduml

f:id:tmori3y2:20170326024539p:plain

plantuml-viewer

@importで外部のPlantUMLファイルを読み込む場合は、外部ファイル単体でプレビュー出来るように以下もインストールすると良い。

atom.io

プレビューのショートカットはCtrl + Alt + p

graphviz-preview-plus

@importで外部のGraphVizファイルを読み込む場合は、外部ファイル単体でプレビュー出来るように以下もインストールすると良い。

atom.io

プレビューのショートカットは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で出来るらしいが試せていないので、そのうち試して報告する予定。

リクエストを出してみた

github.com

REQUEST: Assign the name associated with the external file to image file on saving as markdown · Issue #298 · shd101wyy/markdown-preview-enhanced · GitHub

@importで外部ファイルを読み込んだ時に"Save as markdown"で保存する画像ファイルの名前についてのリクエストを出しています。