MarkdownをAsciidocに変換するKramdocまたはPandocをDocker環境で動かす
概要
- Asciidocは便利できれいだがちょっと書きにくい
- 書き慣れているMarkdownから変換する手法を試した
- Dockerイメージを用いて以下のように変換可能。
Kramdoc版：
docker run --rm -v $(pwd):/documents/ asciidoctor/docker-asciidoctor kramdoc --wrap=ventilate --format=GFM sample.md
または，Pandoc版：
docker run --rm -v $(pwd):/data pandoc/core:2.10 sample.md --to asciidoctor -o sample_pandoc.adoc
なお，筆者の環境はDocker on ubuntu20 on wsl2 on windows 10です。（ギャグっぽい）
はじめに
Asciidocは書きやすさとリッチな描写力を兼ね備えた便利なマークアップ言語です。
しかし，Latexはいざしらず超楽なMarkdownに慣れてしまうとなかなか文法を覚えて書くというのをしたくなくなります。
そこで，Markdownでさっと書いてそこからAsciidocの雛形を書くという方式を取るための手順をまとめてみます。
サンプルやソースについて
本記事で用いたサンプルやソースはこちら。
Markdown to Asciidoc
ざっと調べた感じ，Pandocを使うという人とKramdoc（Kramdown）を使うという人の2パターンあるようです。
サンプルに使うマークダウンファイルはこちら。
Pandoc（新しいバージョンを使うことを推奨）
Jupyterで使われているはずなので多分Pandocが入っている人も多いと思います。
有名かつ有用なツールですが古いバージョンに関してはAsciidocの生成に関しては使い物にならないので注意です。Dockerなどで特定のバージョンを使える環境を用意したほうが良いと思います。
WSL，Docker環境がある前提で行けば下記のコマンドにてsample.mdファイルをsample_pandoc.adocファイルに変換できます。
pandoc/core
おそらくこちらが本来のバージョンです。こちらを使ったほうが引用がきれいになりそうです。
既存の問題としてこのままだとタイトルのレベルがずれるので別途タイトルを= タイトルのようにAsciidoc記法で書く必要があります。
wsl docker run --rm -v $(pwd):/data pandoc/core:2.10 sample.md --to asciidoctor -o sample_pandoc.adoc
pandoc/latex:2.10 （非推奨）
wsl docker run --rm -v $(pwd):/data pandoc/latex:2.10 sample.md --to asciidoctor -o sample_pandoc.adoc
Kramdoc（On Docker）
一方で，Asciidocの開発寄りで作られているのがKramdocです。
Rubyで動くらしいので手元にRuby環境がある場合はgemでインストール出来ます。
自分はRuby使いでない＆環境構築に興味がないのでDockerを用いていきます。
asciidoctor/docker-asciidoctor 環境でのKramdoc
DockerでAsciidoc環境構築をしたことがあるならばasciidoctor/docker-asciidoctorのイメージを落としている方も多いと思いますが，Kramdocは現状asciidoctor/docker-asciidoctor環境にインストールされているので新規インストールの問題がないのでこちらを使っていきます。
変換コマンドは以下のとおりです。
docker run --rm -v $(pwd):/documents/ asciidoctor/docker-asciidoctor kramdoc --wrap=ventilate --format=GFM sample.md
$(pwd)の所はコマンドプロンプトの場合"%CD%"でも動くとは思います。wsl2で動かしている方は先頭にwslをつけるのをわすれずに。
オプションについては下記を参照しました。つけなくてもそこまで支障があるわけではなかったですが念の為。
html変換
adocファイルが出来たらhtml変換も同様に以下のコマンドで変換できます。
docker run --rm -v $(pwd):/documents/ asciidoctor/docker-asciidoctor asciidoctor <sample.adoc> -r asciidoctor-diagram -a allow-uri-read -a data-uri -a toc=left
このオプションとして以下を追記しています。
見た目はこんな感じになります。
まとめ
Asciidocは環境構築やら書き方やらちょっとハードル高いですが，Docker環境があれば結構気軽に使えると思います。
PandocとKramdocのどちらがいいか？に関してはまだ自分では結論が出ていませんが，どちらでも実用に耐えうるとは思っています。
- Pandoc
- 言わずとしれた万能コンバータ
- リストまわりの挙動に不安。バージョンによって大きく挙動が変わるので要注意
- 半角スペースで改行を入れられてしまうことがあるのはちょっといただけない
- Kramdoc
- きれいに変換できる。
- リンクや特殊文字が絡むと微妙
- 開発速度にちょっと期待しづらいか？
変換結果詳細比較
下記リポジトリにて変換結果とコマンドなどを載せているのでご参考までに。
バグ報告など
とりあえず，下記リポジトリにも書いていますが，いくつかバグがあったのでメモしておきます。
GitHub - YoshiRi/MarkdownToAsciidoc: Test project for markdown to asciidoc conversion
なお，Kramdocのバージョンは1.01でした。
>> wsl docker run --rm asciidoctor/docker-asciidoctor kramdoc --version kramdoc 1.0.1
PHPのシンタックスハイライトをつけようとするとエラーが出る
xmlのコメントを変換する機能でエラーがでる。以下がそのエラー文。
/usr/lib/ruby/gems/2.7.0/gems/kramdown-asciidoc-1.0.1/lib/kramdown-asciidoc/converter.rb:99:in `convert': undefined method `convert_xml_pi' for #<Kramdown::AsciiDoc::Converter:0x0000561a13adec28> (NoMethodError) Did you mean? convert_li
デバッグの結果以下が原因となった部分。
<?php if (is_tag()){ $posts = query_posts($query_string . '&showposts=20'); } ?>
バージョンによっては改善しているかもしれない。
リンク以降の改行がおかしい
- 定義参照リンク以降の変換がバグる。
- 定義参照リンクは別口で書くなどして対応するしか？
