The table of contents file (or toc.yml) allows content publishers to define the hierarchy of topics in a Markdown document using a single YAML file.
Users must name the file toc.yml (the extension must not be .yaml), and place it at the root of the archive.
The toc.yml file must have the following:
| Key | Optional | Description |
|---|---|---|
toc |
No | Defines the table of contents. It contains a list of file paths and the hierarchy of topics. |
filepath |
No | Specifies the path of the Markdown file relative to the root of the archive. It defines each topic or subtopic in the hierarchy. |
children |
Yes | A list of nested file paths under a specific topic, indicating a hierarchy of topics. |
metadata |
No | A metadata key that applies to the document, and all its topics.
It is not possible to add the ft:lang metadata key in a publication that uses a table of contents file. Use the ft:locale metadata key instead. |
key |
No | Under metadata, each entry requires a key to define a metadata key. |
value |
No | Associated with each key in metadata, value defines the corresponding metadata key value. It can be a single value, a list, or hierarchical. |
Example:
toc:
- filepath: "introduction.md" # Title: Introduction
children:
- filepath: "another_topic.md" # Title: Another topic
children:
- filepath: "nested_topic.md" # Title: Nested topic
- filepath: "last_nested_topic.md" # Title: Last nested topic
- filepath: "api.md" # Title: API
metadata:
- key: "ft:originId"
value: "a_test_toc_yml_doc"
- key: "ft:title"
value: "A test toc.yml document"
- key: "ft:locale"
value: "en-US"
- key: "Region"
value:
- ["Europe", "France", "Provence-Alpes-Côte d'Azur"] # These values are hierarchical
- key: "Versions" # The following values are NOT hierarchical. They are at the same level
value:
- "1.0"
- "2.0"
This file produces a document with the following table of contents:
A test toc.yml document
1. Introduction
a. Another topic
i. Nested topic
ii. Last nested topic
2. API
The headers of the Markdown files create subtopics. It it not possible to choose whether the Markdown files headers create subtopics.
The document and all topics receive the following metadata values:
Region: Europe > France > Provence-Alpes-Côte d'Azur
Versions: 1.0, 2.0
For an example, select the Attachments button, and download the Markdown-test-toc-yml-doc.zip archive.