Elements

Much of the publication is a combination of one or more “elements” which make up the components of the file. An element can be a table of contents, a dedication page, or the individual chapters. The top-level contents element contains a list of elements:

contents:
  - element: title
    source: matter/title.html
  - element: chapter
    directory: chapters
    source: /^chapter-\d+.md$/

Sources

Except for a few exceptions, an element has a source attribute which determines the content of the element. This can be a single file:

contents:
  - element: title
    source: matter/title.html

It can also be a regular expression of files and a source directory, most commonly used to include all the chapters or apendixes in the directory.

contents:
  - element: chapter
    directory: chapters
    source: /^chapter-\d+.md$/

Formatting

Inside the element tag, there are a number of attributes that control how they are formatted.

number

When a number is provided, the element template is given that number while rendering. If the element has multiple files, such as using a regular expression source attribute, then the first file will be given the value of number and each one after that will get one higher number. This allows numbering chapters:

contents:
  - element: chapter
    directory: chapters
    source: /^chapter-\d+.md$/
    number: 4 # Starts at chapter 4 and increments by one.