AsciiDoc and Ruby on macOS

Notes based on my struggles configuring AsciiDoc with latex math support.

Pandoc Background

I have been writing books and documentation using Pandoc. With Pandoc you typically use a flavor of Markdown. Generating a book is like this:

❯ pandoc --defaults pdf-settings.txt
output-file:   sample-julia-beginners.pdf
standalone: true

# Gets put in LaTeX header of intermediate latex document created.
include-in-header: header.tex

# Need to use this PDF engine to support Unicode
pdf-engine: xelatex

- title.txt

Enter AsciiDoc

AsciiDoc in contrast is nothing like that. That was confusing to me at first, because I kept looking for a description of the configuration file that said how my book configured and what files it was made out of.



:leveloffset: 1
:xrefstyle: short
:stem: latexmath
:source-highlighter: coderay
:bibliography-database: dl4nlp.bib
:chapter: 2
:sectnumoffset: 1

AsciiDoc Flexibility

Compared to Pandoc Markdown AsciiDoc feels like a more complete solution. It has support for a lot more stuff. The downside is getting all this to work is tricker. Pandoc feels more like a big comprehensive package which solves everything out of the box.

[[Listing-XYZ-1, reftext={chapter}.{counter:listing}]]
.Listing title
print("Hello world") <1>
<1> Say hello

Avoid Ruby Configuration Hell

The price you got to pay for all of these features and flexibility is what felt like configuration hell. To be fair I was probably a bit unlucky and mix Ruby skills are rusty.

$ gem install asciidoctor-pdf 
ERROR: While executing gem ... (NoMethodError)
undefined method `request' for nil:NilClass
❯ gem install --pre asciidoctor-pdf

Installing and Using RVM

rvm is software to manage multiple versions of Ruby. By using rvm we can switch to e.g. the latest 2.x version of Ruby, Ruby 2.7.3 to install asciidoctor-pdf.

❯ brew install gnupg
❯ gpg --keyserver hkp:// --recv-keys 409B6B1796C275462A1703113804BB82D39DC0E3 7D2BAF1CF37B13E2069D6956105BD0E739499BDB
❯ \curl -sSL | bash
❯ rvm use default

RVM is not a function, selecting rubies with 'rvm use ...' will not work.
❯ rvm install 2.7.3
❯ rvm list
=* ruby-2.7.3 [ x86_64 ]

# Default ruby not set. Try 'rvm alias create default <ruby>'.
❯ rvm alias create default 2.7.3
❯ zsh --login
❯ bash --login
❯ rvm use default
❯ rvm list
=* ruby-2.7.3 [ x86_64 ]

# => - current
# =* - current && default
# * - default

Installing asciidoctor-pdf

Now with RVM and version 2.7.3 you can install asciidoctor-pdf using gem:

❯ gem install asciidoctor-pdf
❯ which asciidoctor-pdf

Configure Asciidoctor for Your Writing

When generating PDF files using Asciidoctor you might want to use particular themes, fonts and configurations. You can add your own custom stuff under the gem install folder for asciidoctor-pdf. We have already figured out that on my Mac this is at:

❯ tree -L 2 ~/.rvm/gems/ruby-2.7.3/
├── gems
│ ├── Ascii85-1.1.0
│ ├── afm-0.2.2
│ ├── asciidoctor-2.0.12
│ ├── asciidoctor-pdf-1.5.4
│ ├── concurrent-ruby-1.1.8
│ ├── css_parser-1.9.0
│ ├── hashery-2.1.2
│ ├── pdf-core-0.7.0
│ ├── pdf-reader-2.4.2
│ └── ttfunk-1.5.1
❯ tree -L 2 ~/.rvm/gems/ruby-2.7.3/gems/asciidoctor-pdf-1.5.4
├── bin
│ ├── asciidoctor-pdf
│ └── asciidoctor-pdf-optimize
├── data
│ ├── fonts
│ └── themes
├── docs
│ └── theming-guide.adoc
└── lib
├── asciidoctor
├── asciidoctor-pdf
└── asciidoctor-pdf.rb
extends: default
merge: true
Noto Serif:
normal: GEM_FONTS_DIR/notoserif-regular-subset.ttf
bold: GEM_FONTS_DIR/notoserif-bold-subset.ttf
bold_italic: GEM_FONTS_DIR/notoserif-bold_italic-subset.ttf
margin: [0.67in, 0.67in, 0.67in, 0.67in]
size: Letter
❯ tree -L 3 ~/.rvm/gems/ruby-2.7.3/gems/asciidoctor-pdf-1.5.4
├── data
│ ├── fonts
│ └── themes
│ ├── base-theme.yml
│ ├── default-theme.yml
│ ├── default-with-fallback-font-theme.yml
│ └── manning-theme.yml

LaTeX Math Does Not Work!

Here there can be a lot of problems. I made a serious of mistakes here which I hope others can learn from and avoid.

Notation for Formatting LaTeX Math

Let me start from the first embarrassing mistake. I thought you wrote Math like this because that is what all Markdown flavors do:

k_{n+1} = n^2 + k_n^2 - k_{n-1}
k_{n+1} = n^2 + k_n^2 - k_{n-1}
:stem: latexmath
x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}
Inline equation works too! latexmath:[a^2+b^2=c^2]. Or as stem
stem:[a^2+b^2=c^2]. Pretty nice, huh?

Add LaTeX Support

To actually produce math equations in HTML or PDF you need to add support for this.

❯ gem install asciidoctor-mathematical
❯ asciidoctor-pdf -a pdf-style=manning -r asciidoctor-mathematical  math-sample.adoc

Get Fonts Right!

If your LaTeX math looks bad it may not be because of problems with your installation of configuration but rather that you lack appropriate fonts. Here is an example from bad output I got:

❯ tree -L 2 ~/.rvm/gems/ruby-2.7.3/gems/asciidoctor-pdf-1.5.4
├── data
│ ├── fonts
│ └── themes

Wrong Advice on Fonts!

This is an edit to original story

cd ~/Library/Fonts
curl -LO \
-LO \
-LO \
-LO \
-LO \
-LO \
-LO \

Testing Mathematical if You Are Unsure

If you are not sure where the problem is, then you can test the mathematical Ruby Gem directly.

require 'mathematical'
r ="mathy.svg", "w") {|f|
d = r.render("$f(x) = x$")

Geek dad, living in Oslo, Norway with passion for UX, Julia programming, science, teaching, reading and writing.

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store