Table-Of-Content (TOC) Files
DocFX supports processing Markdown files, which we call Conceptual Files, as well as structured data model in YAML or JSON format, which we call Metadata Files. Besides that, DocFX introduces a way to organize these files using Table-Of-Content Files, which we also call TOC Files, so that users can navigate through Metadata Files and Conceptual Files.
TOC Files must have file name
toc.yml, notice that file name is case-insensitive.
Markdown format TOC
toc.md leverages Markdown Atx-style headers which use 1-6 hash characters at the start of the line to represent the TOC levels 1-6. We call each line starting with hash characters a TOC Item. A TOC Item with higher level is considered as the child of the nearest upper TOC Item with less level. A sample
toc.md is as below:
# [Header1](href) ## [Header1.1](href) # Header2 ## [Header2.1](href) ### [Header2.1.1](href) ## [Header2.2](href) # @UidForAnArticle
Three kinds of links are supported:
- Absolute path, for example,
- Relative path, for example,
../example.md. This kind of link has several advanced usages and is described in detail below.
- URI with
xrefscheme, for example,
xref:System.String, the value is the
uidof the file to be cross-referenced.
YAML format TOC
- name: Topic1 href: Topic1.md - name: Topic2 href: Topic2.md items: - name: Topic2_1 href: Topic2_1.md
toc.yml represents a structured data model and conforms to the YAML standard. It supports advanced functionalities.
Data model for
The data model for
toc.yml is an array of TOC Item Objects.
TOC Item Object
TOC Item Object represents the data model for each TOC Item.
All the property names are case sensitive.
|name||string||Specifies the title of the TOC Item.|
|href||string||Specifies the hyperlink of the TOC Item.|
|items||TOC Item Object||Specifies the children TOC Items of current TOC Item.|
Advanced: These properties are useful when a TOC links another TOC, or links to a uid.
|tocHref||string||Specifies another TOC file, whose items are considered as the child of the currrent TOC Item.|
|topicHref||string||Specifies the topic href of the TOC Item. It is useful when href is linking to a folder or tocHref is used.|
Href in detail
If a TOC Item is linking to some relative path, there are three cases:
- Linking to another TOC File, for example,
- Linking to a folder, which means, the value of the link ends with
/explicitly, for example,
- Linking to some local file.
Each case is described in detail below.
Link to another TOC File
If the TOC Item is linking to some other TOC File, it is considered as a placeholder of the referenced TOC File, and DocFX will extract content from that TOC File and insert into current TOC Item recursively.
This technique is always used when you want to combine several TOC Files into one single TOC File.
topicHref is set for this TOC Item, it will be considered as the
href of the expanded TOC Item.
For example, one
toc.yml file is like below:
- name: How-to tutorials tocHref: howto/toc.yml topicHref: howto/overview.md
It references to the
toc.yml file under folder
howto, with the following content:
- name: "How-to1" href: howto1.md - name: "How-to2" href: howto2.md
DocFX processes these
toc.yml files and expands the uppder
toc.yml file into:
- name: How-to tutorials href: howto/overview.md topicHref: howto/overview.md items: - name: "How-to1" href: howto/howto1.md topichref: howto/howto1.md - name: "How-to2" href: howto/howto2.md topichref: howto/howto2.md
toc.yml file under
howto folder will not be transformed to the output folder even if it is included in
Link to a folder
If the Toc Item is linking to a folder, ending with
/ explicitly, the link value for the Toc Item is determined in the following steps:
topicUidis set, the link value is resolved to the relative path to
topicUidis not set, DocFX searches for Toc File under the folder, and get the first relative link to local file as the link value for current Toc Item. For example, if the Toc Item is
href: article/, and the content of
article/toc.ymlis as follows:
- name: Topic1 href: topic1.md
The link value for the Toc Item is resolved to
If there is no Toc File under the folder, the link value keeps unchanged.
Link to local file
If the Toc Item is linking to a local file, we call this local file In-Toc File. Make sure the file is included in
When a local file is not referenced by any Toc Item, we call this local file Not-In-Toc File. Its TOC File is the nearest TOC File in output folder from the same folder as the local file to the root output folder.