Asciidoctor Book

Table of Contents

• 1. Setup
• 2. Editor/IDE Choice
• 3. Build
• 4. Known Issues

This is a template repository for quick starting asciidoctor book.

It has support for, latex and bibtex, making it a great choice for STEM books

See a sample book at index.adoc and its HTML rendering at thammegowda.github.io/asciidoc-book/

1. Setup

Asciidoc has tools in Java, Javascript, Ruby, and historically Python. At this time, much of the tools are in Ruby. So we need to setup ruby environment properly.

Install rbenv if not already found.

brew install rbenv # or conda install rbenv
# other platforms, follow instructions at https://github.com/rbenv/rbenv-installer
rbenv init
rbenv install 2.7.4   # install this version
rbenv global 2.7.4    # activate env

Install asciidoctor and its extensions:

gem install asciidoctor
gem install rouge
gem install asciidoctor-latex --pre      # this is for HTML
gem install asciidoctor-bibtex

# PDF support
# gem install asciidoctor-pdf
# follow instructions on https://github.com/asciidoctor/asciidoctor-mathematical
# gem install asciidoctor-mathematical      # for latex in PDF

2. Editor/IDE Choice

• IntelliJ/PyCharm with Asciidoctor plugin

• VS Code with Asciidoctor extension

Both of them are great! I used to use PyCharm, but now I am considering VS Code, simply because enabling extensions is easier than PyCharm’s counterpart.

VS Code best settings for asciidoctor

1. Install VS Code and Asciidoc extension

2. Cmd Pallet > Asciidoc: Change preview security settings > Allow everything (i.e.Disable security). Without this latex will not render

3. Settings > Asciidoc >

   1. Set "Full path for the asciidoctor binary/executable" as asciidoctor -r asciidoctor-bibtex --trace

   2. Disable asciidoctor-js so our above command is used to render html in live preview

   3. Without the above bibtex citations wont be rendered.

3. Build

asciidoctor index.adoc -o index.html --trace \
  -r asciidoctor-bibtex

Alternatively, run ./make.sh which has above command

4. Known Issues

1. PDF creation with latex support is not working yet. It is theoretically possible TODO: write