Table-Of-Content (TOC) Files
DocFX supports processing Markdown files or Conceptual Files, as well as structured data model in YAML or JSON format or Metadata Files. Besides that, DocFX introduces a way to organize these files using Table-Of-Content Files or TOC Files, so that users can navigate through Metadata Files and Conceptual Files.
TOC Files must have file name
toc.yml, but the 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 lower level.
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
@syntax, for example,
@System.String. The value is the
uidof the file to cross-reference.
YAML format TOC
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.yml is as below:
- name: Topic1 href: Topic1.md - name: Topic2 href: Topic2.md items: - name: Topic2_1 href: Topic2_1.md
TOC Item Object
TOC Item Object represents the data model for each TOC Item.
All property names are case sensitive.
|Property Name||Required or Optional||Type||Description|
|name||required||string||Specifies the title of the TOC Item.|
|href||optional||string||Specifies the navigation path of the TOC Item. If href is not specified, the TOC Item serves as a container to parent its children TOC Items. If href is an absolute path, the TOC Item navigates to that specified path. If href is a relative path, see below for details.|
|items||optional||TOC Item Object||Specifies the children TOC Items of current TOC Item.|
Advanced usages: Following properties are useful when a TOC links to another TOC, or links to a uid. They are all optional.
|topicHref||string||Specifies the topic href of the TOC Item. It is useful when href is linking to a folder or TOC file or tocHref is used.|
href in detail
If a TOC Item is linking to a 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 in relative path, it is considered as a placeholder of the referenced TOC File. DocFX will extract the array of TOC Item Object from that TOC File and insert into current TOC Item recursively.
This technique is especially useful when you want DocFX to combine several TOC Files to build into one single TOC.
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 href: 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 upper
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 will be 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.