Header¶
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.
Entries¶
Basic Entries¶
title
The project’s title
- examples
title: My First Document
short
The document’s short title
- examples
short: First
author
The document’s author
- examples
author: Justin L Lorieau
targets
The document target formats
- values
html
,tex
,pdf
,epub
,txt
- examples
targets: html, tex, pdf
template
The template to use in rendering the document
- values
articles/basic
books/novel
books/tufte
default
reports/basic
- examples
template: book/tufte
include
The sub-documents to include in a project
- notes
See the section on Includes.
Render Options¶
doc_id
The unique document identifier, which may be used to reference labels in other documents.
- examples
doc_id: chapters-chap1-dm
label_fmts
The formats for labels in rendering the document.
- examples
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. "
label_resets
Specify which label kinds reset the counters f9r other label kinds.
- examples
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
relative_links
If True (default), html links are referenced relative to the document’s path. If False, links are absolute.
- examples
relative_links: True
base_url
If absolute links are used and
relative_links
is False, then the base_url string will be prepended to links.- examples
base_url: /{target}/{subpath}
process_paragraphs
A list of context entries for which paragraphs should be processed
- notes
By default, automated paragraph processing is enabled for the body entry.
- examples
process_paragraphs: body
Includes¶
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.
include
Sub-documents to include in the document tree
- notes
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.
- examples
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.
Inheritance¶
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
specifies a 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.
Additional Notes¶
How do I include quotations in header entries?¶
Quotations within a sentence or string will not be removed
- example
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.
- example
title: ""This is my test title""
In the above example, the title will be "This is my test title"
with the
double quotations.