markdowntoasciidoc's Introduction

MarkdownToAsciidoc

Test project for markdown to asciidoc conversion.

マークダウンをAsciidocに変換するにはPandocではなくDocker-AsciidoctorにあるKramdocを使うと良いということを示す。

Kramdocについてはsee Here.

Sample markdown

Downloaded from https://www.dropbox.com/s/4z6kot27jmikhx5/forapp-markdown-sample.md.

エラーを起こしそうな部分や冗長な箇所は取り除いた。

Pandoc Command

Pandocのバージョンによって挙動が違うので注意

Docker with pandoc 2.10

PandocのイメージをDockerから落として来ることできれいに変換できる。

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

Papndoc1.9 (Deprecated)

--to asciidoctorが肝要だと思われる。なお，v1.9.11では動かなかった。

pandoc sample.md --to asciidoctor -o sample_pandoc.adoc

Docker-Asciidoctor Command

wsl docker run --rm -v $(pwd):/documents/ asciidoctor/docker-asciidoctor kramdoc  --wrap=ventilate --format=GFM sample.md

adoc to html command

option
- left toc
- data-uri
- asciidoctor-diagram

wsl 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

Known Problems

試して判明したエラーや知見など。

Pandoc VS Kramdoc

PandocもKramdocもそれなりにきれいに変換する
- Pandocは意図せぬ改行が入ることがある？
- どちらかというと全般的にPandocのほうがきれいに変換できる。
- タスクリストはKramdocのほうがきれい，番号付きリストもKramdocに軍配があがるか？

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

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

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

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

markdowntoasciidoc's People

Contributors

Stargazers

Watchers

markdowntoasciidoc's Issues

Pandocに対応したsample.mdの更新

ブログでコメントした者です。Pandocでのadocへの変換について、いくつかはmarkdown側の書き方の問題と思われる箇所があったため、sample.mdを更新したものを後ほどPR出しますので、ご参考になればと思います。

PRには変換したsample_pandoc.adocも含めています。本commitではsample.mdに対して以下の対応をしています。

インラインのCode、...について前後に半角空白を入れています。
<>は自動でリンクとみなされるため、例示箇所は<..>としています。
定義参照リンクは2つの[]の間に空白を入れると認識されないため、これを詰めています。

また、以下はPandoc側の問題であることが分かっており、ファイルやオプションの変更では対応できないとみています。

番号付きリストは基本的に[arabic]が自動でつくので記号にはならない（これは現状でも対応できるかもしれませんが、調査不足）
Pandocで出力するadoc形式にはhtmlは埋め込められないため、<s>タグなどは対応できないです。
ハイフンの並びは他の記法とぶつかることが多いので、使用を推奨しません（sample.mdはこれを修正していません）
ネストしたBlockQuoteはPandoc側に問題があり対応できていません（問題個所は把握しました）
h1レベルが--shift-heading-level-by=-1すると消え、titleとしても保存されない

変換に使用したコマンドは以下のとおりです。

pandoc sample.md -o sample_pandoc.adoc  --shift-heading-level-by=-1
asciidoctor sample_pandoc.adoc

使用したPandocのバージョンは、

> pandoc --version
pandoc 2.11
Compiled with pandoc-types 1.22, texmath 0.12.0.3, skylighting 0.10.0.2

asciidoctor のバージョンは

> asciidoctor --version
Asciidoctor 2.0.10 [https://asciidoctor.org]
Runtime Environment (ruby 2.7.2p137 (2020-10-01 revision 5445e04352) [x86_64-linux]) (lc:UTF-8 fs:UTF-8 in:UTF-8 ex:UTF-8)

です。

Recommend Projects