Headers contain useful meta information on the document and sub-documents, which may impact how the document, sub-documents and tags are rendered.
Headers are optionally present at the start of a disseminate
document. Headers are enclosed by 3 or more hyphens (’
--- title: Disseminate Headers author: Justin L Lorieau template: component targets: html, tex, pdf include: part1/introduction.dm part1/cakes.dm part1/tarts.dm ---
Since documents can include sub-documents, the context of a parent document is copied over to the sub-documents, which in turn, can overwrite these values.
The project’s title
title: My First Document
The document’s short title
The document’s author
author: Justin L Lorieau
The document target formats
targets: html, tex, pdf
The template to use in rendering the document
The sub-documents to include in a project
See the section on Includes.
The unique document identifier, which may be used to reference labels in other documents.
The formats for labels in rendering the document.
label_fmts: document: "@label.title" ref_document: "@label.title" heading: "@label.tree_number." heading_part: "Part @label.part_number. " heading_chapter': "Chapter @label.chapter_number. "
Specify which label kinds reset the counters f9r other label kinds.
A project may need to have the the chapter, section and subsection numbers reset every time there is a new part. To achieve this sort of reset, the following entry would be entered in the heading of the root document.
label_resets: part: chapter, section, subsection
If True (default), html links are referenced relative to the document’s path. If False, links are absolute.
If absolute links are used and
relative_linksis False, then the base_url string will be prepended to links.
A list of context entries for which paragraphs should be processed
By default, automated paragraph processing is enabled for the body entry.
Sub-documents can be included in the header. Sub-documents may represent parts of books, chapters or sections. Sub-documents can be furthermore nested to form projects with multiple sub-levels. The include statement lists the sub-documents directly subordinate to a document.
Sub-documents to include in the document tree
Sub-documents and their paths are listed one per line with at least two spaces before each entry. The paths are relative to the current document.
include: part1/introduction.dm part1/cakes.dm part1/tarts.dm
A project consists of one root document and, possibly, one more included documents. It is alternatively known as a document tree.
A root document is the first document in a project, and it is not included by any other document.
A child document is a document that was included by a document.
A parent document is the document that was included by a document.
Most header entries from parent documents are available to child documents. If child documents specify their own version of these entries, then these values will be overwritten.
For example, a parent document might specify a
title entry in the header.
If the parent document includes a child document, then the
title entry will
be the same for the child document, unless the child document’s header also
title entry, in which case this entry will be used.
For this reason, it is useful to specify settings for an entire project in the header of the root document, then to overwrite these values (if needed) in the child document headers.
From a technical perspective, header entries are loaded into the context for a document. The context is a Python dictionary that holds the variables needed to render a document.
How do I include quotations in header entries?¶
Quotations within a sentence or string will not be removed
title: This is my "test" title
However, quotations on the end of a sentence or string will be removed. To include these quotations, simply add the quotation mark twice on each side of the entry.
title: ""This is my test title""
In the above example, the title will be
"This is my test title" with the