Pandoc で PlantUML を出力

pandoc は、当然ですがデフォルトでは plantuml に対応していません。
しかし、 markdown でドキュメントを書く際は、 plantuml をよく使用するので、 plantuml の画像を出力できるようにします。

前提

お約束の前提ですが、以下の環境とします。

Windows 10 Home 64bit

また、あらかじめ以下もインストール済みとします。

graphviz （plantuml を扱うのに必要）
~~python3 （pandoc のフィルターに使用）~~
- 結果的に python は使用しませんでした
node.js (npm を使用するのに必要)

前提

plantuml とは
pandoc の plantuml 用フィルターを利用

plantuml とは

plantuml がどんなもので、plantuml そのものをどうやってインストールするかは省略します。
詳しくは↓サイトに紹介されています。

qiita.com

pandoc の plantuml 用フィルターを利用

Windows 環境下で pandoc の plantuml フィルターの用意が非常に大変でした。ネットの日本語情報も少なく、その情報も自分の環境ではうまくいかないものばかりだったので、備忘録として経緯も載せます。

pandoc バージョンの注意

私の環境では最初、 pandoc のバージョンが 1.7 でした。そのバージョンではどうやら -F XXX.py という感じで python ファイルのフィルターが使用できないみたいでした。
バージョンを 2.1.2 にすると解決しました。

（すみません、参考サイトは失念しました。どこかの github の issue だった気がします）

plantuml-filter.py を使用する方法その１（結果失敗です）

これは結果的に失敗したので、読み飛ばしてもらってOKです。

以下にある情報をもとにやってみました。

mickey-happygolucky.hatenablog.com

https://raw.githubusercontent.com/matthiasbeyer/pandoc-paper-template/master/scripts/plantuml-filter.pyにあるものをフィルターとして使用する方法です。

これはどうやら Windows 環境ではうまくいかないようで、実行すると以下のようなエラーが出ました。

> pandoc test.md -o test.html --self-contained -t html5 -F .\plantuml-filter.py
        [PLTUML] plantuml-images/8428a0c71ace69322a85c178b192bb8cdaa0bd20.png
Traceback (most recent call last):
  File ".\plantuml-filter.py", line 64, in <module>
    toJSONFilter(graphviz)
（中略）
  File "C:\Users\XXX\AppData\Local\Programs\Python\Python35-32\lib\subprocess.py", line 873, in __init__
    "close_fds is not supported on Windows platforms"
ValueError: close_fds is not supported on Windows platforms if you redirect stdin/stdout/stderr
Error running filter .\plantuml-filter.py:
Filter returned error status 1

どうやら python のスクリプトの中身が Windows に対応していないみたいです。（close_fds が Windows では使えないっぽい？） python 自体わかっていない人間なので、いったんここで断念します。

※ python をちゃんと理解していたらチョコっと手を加えたら解決する可能性があります。

plantuml-filter.py を使用する方法その２（結果失敗です）

これも結果的に失敗したので、読み飛ばしてもらってOKです。

以下にある情報をもとにやってみました。

takec.hatenablog.jp

これは inkscape とかの連動をしているので、そのまま流用することはできないのですが、ここでは「その１」であった python スクリプトを Windows 用に書き換えて使用する例が載っていました。
が、しかし実行すると以下のエラーが出てうまくいきませんでした。（念のため inkscape に関連する箇所はコメントアウトしたんですが、駄目でした）

> pandoc test.md -o test.html --self-contained -t html5  -F .\plantuml-filter.py
Traceback (most recent call last):
  File ".\plantuml-filter.py", line 64, in <module>
    toJSONFilter(graphviz)
（中略）
  File ".\plantuml-filter.py", line 47, in graphviz
    data, err = pipe(["java", "-jar", "C:\plantuml.jar", "-pipe", "-Tsvg", "-charset", "UTF-8"], code)
  File ".\plantuml-filter.py", line 22, in pipe
    p = subprocess.Popen(cmd, shell=False, stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.PIPE)
  File "C:\Users\XXX\AppData\Local\Programs\Python\Python35-32\lib\subprocess.py", line 950, in __init__
    restore_signals, start_new_session)
  File "C:\Users\XXX\AppData\Local\Programs\Python\Python35-32\lib\subprocess.py", line 1220, in _execute_child
    startupinfo)
FileNotFoundError: [WinError 2] 指定されたファイルが見つかりません。
Error running filter .\plantuml-filter.py:
Filter returned error status 1

このエラーはよくわかりませんでした。一応 plantuml,jar のファイルのパス等を確認したのですが、ファイルが見つかりませんと言われます。
まあよくわかりもせずに、他の人のスクリプトを使うなということです・・・。

pandoc-plantuml-filter.cmd を使用する方法（成功しました）

以下の github 上に公開されているリポジトリを参照させてもらいました。

github.com

pandoc-plantuml-filterの取得

Readme.md には npm -g でグローバルにインストールするように書かれていますが、私の環境ではグローバルインストールではうまくいきませんでした。以下のように、markdown → html 変換するディレクトリにに配置します。

> npm install pandoc-plantuml-filter

実行

Readme に書いてある通り、以下の通り実行します。

> pandoc test.md -o test.html --self-contained -t html5 -F pandoc-plantuml-filter.cmd
[WARNING] This document format requires a nonempty <title> element.
  Please specify either 'title' or 'pagetitle' in the metadata.
  Falling back to 'test'

なんか警告が出ていますが・・・ --metadata pagetitle=<ページタイトル> を付加すると消えます。どうやら、ブラウザ上に表示されるタイトルの設定のようですが、はっきり言って勝手に html の名称を割り当ててくれたらいいのに・・・と思いますので、別途バッチファイルとか作ったほうが便利かもしれません。
（ちなみに、これは pandoc 側の仕様らしい？です。 issueでも同じ不満を言っている人がいますｗ）

追記

以下のバッチファイルを作ってみました。

# pandoc_markdown2html.bat

@echo off

rem param1: markdownファイル名
rem param2: cssファイル名

if "%1"=="" (
  echo ERROR : Needs Filename.
  exit /b 1
)

if not "%2"=="" (
  rem 第２引数はcssだけ許可
  if not "%~x2"==".css" (
    echo ERROR : Arg2 is neet to css filename.
    exit /b 1
  )
  set CSS=-c %2
)

rem ファイル名から拡張子を取り除く
for /f %%i in ('echo %1') do set FILE=%%~ni

pandoc %1 -o %FILE%.html --self-contained -t html5 %CSS% -F pandoc-plantuml-filter.cmd --metadata pagetitle="%FILE%"

使用例：

> pandoc_markdown2html.bat test.md test.css

plantuml を svg 形式で出力

pandoc-plantuml-filter のデフォルトのままでは、出力形式は png 固定です。
ちょこっといじって svg で出力するようにしました。

node_modules\pandoc-plantuml-filter\plantuml-filter.js の以下の部分を書き換えます。

- var res = execSync(util.format("java -splash:no -jar \"%s\" -charset UTF-8 -pipe", plantumlPath), { input: umlText });
+ var res = execSync(util.format("java -splash:no -jar \"%s\" -charset UTF-8 -pipe -Tsvg", plantumlPath), { input: umlText });
- var fileName = util.format("%d.png", imgCounter++);
+ var fileName = util.format("%d.svg", imgCounter++);

とりあえず、これで晴れて目的を達成できました。最終的には gitlab にプッシュしたら、 gitlab runner が走って markdown を html に自動変換するっていうのを実現したいです。