AsciiDoc and Asciidoctor

Markdown to Asciidoc

Use kramdown, which is better suited than pandoc as it has more AsciiDoc-sensible options.

$ gem install kramdown kramdown-asciidoc

$ for file in ./*.md ; do
    kramdoc \
      --format=GFM \
      --output="${file%.md}.adoc" \
      --wrap=ventilate "$file"
  done

$ rm -vi ./*.md

Source Highlighter

Add this attribute to the document:

= My Title
:toc: left
...
:source-highlighter: <which highlighter to use>

As of 2023, the docs currently say for pygments we simply write pygments.

Asciidoctor Source Highlighter pygments.rb

but I got an error with this:

= My Title
:toc: left
...
:source-highlighter: pygments

$ asciidoctor ./algds/other/prime_factors/README.adoc
asciidoctor: WARNING: optional gem 'pygments.rb' is not available (reason: cannot load 'pygments'). Functionality disabled.

But if I changing to pygments.rb works:

= My Title
:toc: left
...
:source-highlighter: pygments.rb

Source Highlighter Not Working

We have observed at times that if asciidoctor is installed from a Gemfile and pygments.rb is installed with gem install, it may fail (with no errors) to add the tags around the code tokens.

Installing everything from Gemfile and then running bundle exec asciidoctor file.adoc worked.