粗大メモ置き場

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

MarkdownをAsciidocに変換するKramdocをDocker環境で動かす

概要

  • Asciidocは便利できれいだがちょっと書きにくい
  • 書き慣れているMarkdownから変換する手法を試した
  • asciidoctor/docker-asciidoctorのイメージを使って以下のように変換可能。
docker run --rm -v $(pwd):/documents/ asciidoctor/docker-asciidoctor kramdoc  --wrap=ventilate --format=GFM sample.md

なお,筆者の環境は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(2020年10月では非推奨)

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

有名かつ有用なツールですがAsciidocの生成に関しては使い物にならないと思っています。

qiita.com

一応試したコマンドが以下のとおりです。

pandoc -o sample_pandoc.adoc sample.adoc

うまく行っていない点が非常に多いのですが,

章たてや箇条書き以降の変換はズタボロな感じがします。Prefixの設定で化けるかも知れませんがそれを調べるよりも次の手法が楽なので深堀りしませんでした。

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-asciidoctorが使えれば結構気軽に使えると思います。

バグ報告など

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

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

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

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

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