You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

32 lines
1.3 KiB

4 years ago
////
Included in:
- user-manual: Static website generators: 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:
[source]
----
--- <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 <<user-manual#include-directive,include files>>.
TIP: Awestruct can read front matter directly from AsciiDoc attributes defined in the document header, thus eliminating the need for this feature.