粗大メモ置き場

個人用,たまーに来訪者を意識する雑記メモ

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は書きやすさとリッチな描写力を兼ね備えた便利なマークアップ言語です。

qiita.com

ossyaritoori.hatenablog.com


しかし,Latexはいざしらず超楽なMarkdownに慣れてしまうとなかなか文法を覚えて書くというのをしたくなくなります。


そこで,Markdownでさっと書いてそこからAsciidocの雛形を書くという方式を取るための手順をまとめてみます。

サンプルやソースについて

本記事で用いたサンプルやソースはこちら。

github.com

Markdown to Asciidoc

ざっと調べた感じ,Pandocを使うという人とKramdoc(Kramdown)を使うという人の2パターンあるようです。

サンプルに使うマークダウンファイルはこちら

Pandoc(新しいバージョンを使うことを推奨)

Jupyterで使われているはずなので多分Pandocが入っている人も多いと思います。

有名かつ有用なツールですが古いバージョンに関してはAsciidocの生成に関しては使い物にならないので注意です。Dockerなどで特定のバージョンを使える環境を用意したほうが良いと思います。

qiita.com

WSL,Docker環境がある前提で行けば下記のコマンドにてsample.mdファイルをsample_pandoc.adocファイルに変換できます。

pandoc/core:2.10

おそらくこちらが本来のバージョンです。こちらを使ったほうが引用がきれいになりそうです。

wsl docker run --rm -v $(pwd):/data pandoc/core:2.10 sample.md --to asciidoctor -o sample_pandoc.adoc 

pandoc/latex:2.10 (非推奨)

Latexコンパイルに特化したイメージです。

wsl docker run --rm -v $(pwd):/data pandoc/latex:2.10 sample.md --to asciidoctor -o sample_pandoc.adoc

Kramdoc(On Docker)

一方で,Asciidocの開発寄りで作られているのがKramdocです。

github.com

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をつけるのをわすれずに。

オプションについては下記を参照しました。つけなくてもそこまで支障があるわけではなかったですが念の為。

matthewsetter.com

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

このオプションとして以下を追記しています。

  • data-uri:画像など埋め込み
  • toc=left:目次を左に
  • asciidoctor-diagram:PlantUMLの図などを埋め込む

見た目はこんな感じになります。

f:id:ossyaritoori:20201016210600p:plain

まとめ

Asciidocは環境構築やら書き方やらちょっとハードル高いですが,Docker環境があれば結構気軽に使えると思います。

PandocとKramdocのどちらがいいか?に関してはまだ自分では結論が出ていませんが,どちらでも実用に耐えうるとは思っています。

  • Pandoc
    • 言わずとしれた万能コンバータ
    • リストまわりの挙動に不安。バージョンによって大きく挙動が変わるので要注意
    • 半角スペースで改行を入れられてしまうことがあるのはちょっといただけない
  • Kramdoc
    • きれいに変換できる。
    • リンクや特殊文字が絡むと微妙
    • 開発速度にちょっと期待しづらいか?

変換結果詳細比較

下記リポジトリにて変換結果とコマンドなどを載せているのでご参考までに。

github.com

バグ報告など

とりあえず,下記リポジトリにも書いていますが,いくつかバグがあったのでメモしておきます。

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'); } ?>

バージョンによっては改善しているかもしれない。

リンク以降の改行がおかしい

  • 定義参照リンク以降の変換がバグる。
    • 定義参照リンクは別口で書くなどして対応するしか?