Metadata Generation and Injection

Metadata being a first class citizen of TiefDown, it is imperative to understand how metadata can be accessed. There are four ways to access metadata generated by TiefDown:

1. using the TeX helper file generated during TeX conversion (see TeX templates for details),
2. using the Typst helper file generated during Typst conversion (see Typst templates for details),
3. by accessing metadata fields in the preprocessor or processor arguments using template strings ({{metafield}}),
4. by reading the generated metadata files (see below),
5. or by using metadata inside pandoc lua filters (if generated, see below).

There are two types of metadata, as described below: project metadata and navigation metadata. Only project metadata can be accessed inside the TeX and Typst helpers as well as the templating strings. If navigation metadata is generated, it can be used in lua filters as well as read as a file.

Metadata Generation Settings

Metadata, importantly, is only injected into the pandoc process if it is explicitly generated for a template. The metadata generation settings can take four values:

• None: no metadata is generated and written for this template. This also means that pandoc does not get metadata injected.
• Full: Both navigation and project metadata are generated for this template and injected into pandoc.
• NavOnly: Only navigation metadata as described below is generated and injected into pandoc.
• MetadataOnly: Only project metadata as described below is generated and injected into pandoc.

If metadata generation is enabled, there is always a yml file generated. The yml file is then injected into the pandoc process as a metadata file. There is also an option to enable JSON metadata file generation, which can be enabled via the MetaGenerationFormat.

Project Metadata

Project metadata is simply the metadata collected through the shared- and markdown project specific metadata. The metadata is merged and written to the corresponding YML/JSON file.

Navigation Metadata

Navigation Metadata is split into two parts: global nav metadata, being a list of nodes of all files in the input; and per-file metadata, containing a reference to the own file as well as the next and previous node.

The per file metadata is generated and injected into pandoc for each file separately. That means, one could access the metadata for the file using Lua filters.

Global metadata is generated once and injected into pandoc for every file. This enables a user to easily create a navigation with all nodes.