Pandoc で PlantUML を出力
移転しました。
pandoc は、当然ですがデフォルトでは plantuml に対応していません。
しかし、 markdown でドキュメントを書く際は、 plantuml をよく使用するので、 plantuml の画像を出力できるようにします。
前提
お約束の前提ですが、以下の環境とします。
- Windows 10 Home 64bit
また、あらかじめ以下もインストール済みとします。
- graphviz (plantuml を扱うのに必要)
python3 (pandoc のフィルターに使用)- 結果的に python は使用しませんでした
- node.js (npm を使用するのに必要)
plantuml とは
plantuml がどんなもので、plantuml そのものをどうやってインストールするかは省略します。
詳しくは↓サイトに紹介されています。
pandoc の plantuml 用フィルターを利用
Windows 環境下で pandoc の plantuml フィルターの用意が非常に大変でした。ネットの日本語情報も少なく、その情報も自分の環境ではうまくいかないものばかりだったので、備忘録として経緯も載せます。
pandoc バージョンの注意
私の環境では最初、 pandoc のバージョンが 1.7 でした。そのバージョンではどうやら -F XXX.py
という感じで python ファイルのフィルターが使用できないみたいでした。
バージョンを 2.1.2 にすると解決しました。
(すみません、参考サイトは失念しました。どこかの github の issue だった気がします)
plantuml-filter.py を使用する方法 その1(結果失敗です)
これは結果的に失敗したので、読み飛ばしてもらって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 を使用する方法 その2(結果失敗です)
これも結果的に失敗したので、読み飛ばしてもらってOKです。
以下にある情報をもとにやってみました。
これは inkscape とかの連動をしているので、そのまま流用することはできないのですが、ここでは「その1」であった 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 上に公開されているリポジトリを参照させてもらいました。
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でも同じ不満を言っている人がいますw)
追記
以下のバッチファイルを作ってみました。
# pandoc_markdown2html.bat @echo off rem param1: markdownファイル名 rem param2: cssファイル名 if "%1"=="" ( echo ERROR : Needs Filename. exit /b 1 ) if not "%2"=="" ( rem 第2引数は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 に自動変換するっていうのを実現したいです。