False expectations take away joy, according to Sandra Bullock. Such was my feeling when I tried to write a full-fledged document using AsciiDoc. I thought I would be a pleasant journey. Could I be wrong?

Dear Emily,

A couple of months ago, Conflux employees got the opportunity to do a course called "Basiskwalificatie Didactische Bekwaamheid"[1]. I happened to be one of the trainees 😉. We had to write a paper as proof that we understood what we had learned. As I prefer markup languages over WYSIWYG editors like MS Word or Pages, I wanted to use the AsciiDoc markup language to write this document. The authors of this blog site use AsciiDoc to write the articles. Having written a fair number of blogs myself, I felt I had more than enough experience with the language, so I thought it would be a natural fit. But girl I was wrong!

Though the language documentation is thorough[2], I was looking for concise documentation to create a simple document. So I went through the docs and found a nice AsciiDoc Syntax Quick Reference. But then, I still was looking for a template in code, so I could start writing the content instead of focusing on the code. Just when I wanted to give up, I stumbled upon an asciidoc-article-template.adoc file!

The start of the document was promising:

= AsciiDoc Article Title
Firstname Lastname <author@asciidoctor.org>
3.0, July 29, 2022: AsciiDoc article template
:toc:
:icons: font

However, this template did not quite fit, because an article has sections but no chapters. So I journeyed on and went through more documentation. Ah, at last, I found it! AsciiDoc also supports the document type book, which corresponds to both real books and (technical) papers! With that type you can create parts, a feature that works nice with the Table of Contents attribute!

In our profession, we often speak about the known and unknown factors and risks. There is an idea called the unknown-unknown, which are things we are not aware of and do not understand. You could also apply this to learning new languages; as long as you don’t know the terms and keywords, googling about it is quite hard.

So once I knew a "book" is a thing within the AsciiDoc language, it was way easier to find a fitting template: the asciidoctor-book-template. Nice, this was exactly what I needed! So I started writing my pages and from then on everything went smoothly. But then, my preview mode showed nice formatted text, where the exported PDF looked kinda ugly (compare the reference document in HTML and PDF).

So, back to the drawing board… Or better, let’s dive into the documentation once more 😔. Ah, there is an Asciidoctor PDF Theming page! That’s a lot of text, which is why I tried to read some sample code instead. After more digging, I ran into the default-theme page. Apparently theming is nothing more than a simple language which describes how your document looks, akin to the CSS language for HTML.

Now I had all tools I needed, I came with the following template:

= <name of document>
<author> <author@email.com>
<date>
:docdatetime: <date>
:author: <author>
:doctype: book
:pdf-fontsdir: fonts
:pdf-themesdir: theme
:pdf-theme: custom-theme.yml
:icons: font
:toc:

== Chapter 1

include::chapters/chapter-one.adoc[]

== Chapter 2

include::chapters/chapter-two.adoc[]

[bibliography]
= Bibliography

.Article
- [[[msv]]] Ross Tate (2013). _Mixed-Site Variance._ Cornell University

.Books
- [[[hfk]]] Dawn Griffiths, David Griffiths (2019). _Head First Kotlin._ O'Reilly Media, Inc.

.Websites
- [[[klb]]] JetBrains. _Kotlin books._ https://kotlinlang.org/docs/books.html

And then for the theming; I created in the same folder where the AsciiDoc resides a fonts and theme folders. Overall, my folder looked like[3]:

<root>
├── chapters
│   ├── chapter-one.adoc
│   └── chapter-two.adoc
├── fonts
│   ├── OpenSans-Bold.ttf
│   ├── OpenSans-BoldItalic.ttf
│   ├── OpenSans-Italic.ttf
│   └── OpenSans-Regular.ttf
├── theme
│   ├── custom-theme.yml
│   └── front-image.svg
└── name-of-document.adoc

After I tweaked the theming file a bit, it got it working:

extends: default
page:
  margin: [0.67in, 0.67in, 0.67in, 0.67in]
base:
  font_family: OpenSans
title_page:
  background_color: ba3925
  font_color: ffffff
  logo:
    top: 7%
    image: image:front-image.svg[scaledwidth=95%]
  title:
    font_color: ffffff
    font-size: $heading_h1_font_size * 1.1
    margin-top: 20
    margin-bottom: 10
  authors:
    font_color: ffffff
heading:
  font-family: OpenSans
  font_style: normal
  font-color: ba3925
  h2_font_size: floor($base_font_size * 2.75)
  h2_margin_bottom: $vertical_rhythm * 0.6
  h3_margin_bottom: $vertical_rhythm * 0.2
toc:
  dot_leader:
    font_color: B2B2B2
table:
  background_color: $page_background_color
  border_color: E6E6E6
  border_width: $base_border_width
  grid_width: $base_border_width
  cell_padding: 6
  head:
    background-color: dedede
    font_style: bold
    border_bottom_width: $base_border_width * 2.5
  body:
    stripe_background_color: F9F9F9
  foot:
    background_color: F0F0F0
footer:
  border_width: 0
  columns: =100%
  recto:
    center:
      content: '- {page-number} -'
  verso:
    center:
      content: '- {page-number} -'
font:
  catalog:
    Noto Serif:
      normal: GEM_FONTS_DIR/notoserif-regular-subset.ttf
      bold: GEM_FONTS_DIR/notoserif-bold-subset.ttf
      italic: GEM_FONTS_DIR/notoserif-italic-subset.ttf
      bold_italic: GEM_FONTS_DIR/notoserif-bold_italic-subset.ttf
    M+ 1mn:
      normal: GEM_FONTS_DIR/mplus1mn-regular-subset.ttf
      bold: GEM_FONTS_DIR/mplus1mn-bold-subset.ttf
      italic: GEM_FONTS_DIR/mplus1mn-italic-subset.ttf
      bold_italic: GEM_FONTS_DIR/mplus1mn-bold_italic-subset.ttf
    OpenSans:
      normal: OpenSans-Regular.ttf
      italic: OpenSans-Italic.ttf
      bold: OpenSans-Bold.ttf
      bold_italic: OpenSans-BoldItalic.ttf

And there you have it, a beautiful document template. Now just run the asciidoctor command to build it all[4]:

$ asciidoctorj -b pdf -a backend=pdf  /<path>/Name-of-Document.adoc

That’s it!

Check out the AsciiDoctor Book Example for an illustration of what it might look like. You can download the whole template here; use it for free for your own benefit!

SU,
Jacob

1. Check the Dutch LinkedIn post for more info.
2. See the AsciiDoc Language Documentation.
3. Click here to download the OpenSans font.
4. I use the IntelliJ AsciiDoc plugin to create the PDF, which uses JRuby under the hood. So your command may look a little bit different.
shadow-left