AsciiDoc and Ruby on macOS

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

Are you struggling with getting AsciiDoc to do what you want? You wrestle with configuring Ruby properly to get AsciiDoc to do what you want? You ask ourself why isn’t AsciiDoc more like Markdown?

Then you have had many of the same struggles as me. So I will try to convey solutions to problems and misconceptions I have had while they are still somewhat fresh in memory.

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

Thus with Pandoc you got most of your configuration in a file, which looks something like this inside:

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

input-files:
- title.txt
- preface.md
- intro.md

The specifics here are not that important. What I really just wanted to get across is that with Pandoc you write your book as being composed of multiple…