76. Static Website Generators

76.1. Front Matter Added for Static Site Generators

Many static site generators (i.e., Jekyll, Middleman, Awestruct) rely on "front matter" added to the top of the document to determine how to convert the content. Front matter typically starts on the first line of a file and is bounded by block delimiters (e.g., ---).

Here’s an example of a document that contains front matter:

---  (1)
layout: default (2)
---  (1)
= Document Title

content
1 Front matter delimiters
2 Front matter data

The static site generator removes these lines before passing the document to the AsciiDoc processor to be converted. Outside of the tool, however, these extra lines can throw off the processor.

If the skip-front-matter attribute is set via the CLI or API (e.g., -a skip-front-matter), Asciidoctor (as of 0.1.4) will recognize the front matter and consume it before parsing the document. Asciidoctor stores the content it removes in the front-matter attribute to make it available for integrations. Asciidoctor also removes front matter when reading include files.

Awestruct can read front matter directly from AsciiDoc attributes defined in the document header, thus eliminating the need for this feature.

76.1.1. Configuring Attributes for Awestruct

Awestruct defines a set of default attributes that it passes to the API in its /default-site.yml file. One of the attributes in that configuration is imagesdir. The value there is set to /images. That means the value in your document is skipped due to the precedence rules.

Fortunately, there is one additional place you can override the attribute. This gives you the opportunity to set your own default and to flip the precedence order so that the document wins out. If an attribute value that is passed to the API ends with an @ symbol, it makes that assignment have a lower precedence than an assignment in the document.

You can define attributes you want to pass to the API in the _config/site.yml file. Here’s an example entry for Asciidoctor:

asciidoctor:
  :safe: safe
  :attributes:
    imagesdir: /assets/images@
    icons: font
    ...
The second-level keys (safe and attributes, in this case) must have colons on both sides of the key name. The rest of the keys only have a colon after the key.

With this configuration added, you should observe that the imagesdir attribute in your document is now respected.