DocFxTocGenerator 1.20.0

Table of Contents (TOC) generator for DocFX

This tool allow to generate a yaml compatible toc.yml file for DocFX.

Usage

DocFxTocGenerator -d <docs folder> [-o <output folder>] [-vsi]

-d, --docfolder          Required. Folder containing the documents.
-o, --outputfolder       Folder to write the resulting toc.yml in.
-v, --verbose            Show verbose messages.
-s, --sequence           Use the .order files for TOC sequence. Format are raws of: filename-without-extension
-r, --override           Use the .override files for TOC file name override. Format are raws of: filename-without-extension;Title you want
-i, --index              Auto-generate a file index in each folder.
-g, --ignore             Use the .ignore files for TOC directory ignore. Format are raws of directory names: directory-to-ignore
-m, --multitoc <depth>   Generate multiple toc files for child folders down to a certain child depth, default is 0 (root only generation).
--help                   Display this help screen.
--version                Display version information.

If the -o or --outputfolder is not provided, the output folder is set to the docfolder.

If normal return code of the tool is 0, but on error it returns 1.

Warnings, errors and verbose

If the tool encounters situations that might need some action, a warning is written to the output. The table of contents is still created.

If the tool encounters an error, an error message is written to the output. The table of contents will not be created. The tool will return errorcode 1.

If you want to trace what the tool is doing, use the -v or verbose flag to output all details of processing the files and folders and creating the table of contents.

Ordering TOC entries

If the -s or --sequence parameter is provided, the tool will inspect every folder with content if a .order file exists and use that to determine the order of files and directories. The .order file is just a list of file- and/or directory-names, case-sensitive without file extensions. Also see the Azure DevOps WIKI documentation on this file.

A sample .order file could look like this:

README
getting-started
working-agreements
developer

Overriding names

If the -r or --override parameter is provided, the tool will inspect every folder with content if a .override file exists. It will use it to override the name displayed in the TOC for a specific file or directory. For example, if the folder name is introduction, the default behavior will be to create the name Introduction. If you want to call it To start with, you can use overrides, like in the following example:

introduction;To start with
working-agreements;All working agreements of all teams

Just use the folder name or Markdown file name without extension, a semicolon ; as a separator and the wanted name to be used. For files, the default behavior without this override is to use the description in the main title of the file.

If there are files or directories which are not in the .order file, they will be alphabetically ordered on the title and added after the ordered entries. The title for an MD-file is taken from the H1-header in the file. The title for a directory is the directory-name, but cleanup from special characters and the first character in capitals.

Automatic adding index of files and directories

If the -i or --index parameter is provided, for every folder that doesn't have a README.md or INDEX.md, an INDEX.md is generated with the contents of that folder. That file is also added to the top of the list of files and directories in that folder.

The generated INDEX.md contains of an H1-header with the name of the folder, followed by a list of files and directories using their title and a link to the item.

Generating mutiple child toc files

The -m or --multitoc option will control how far down the folder tree structure to generating toc files and allows you to generate multiple smaller, more managable TOC files for large DocFX projects. If the parameter is omitted, the default of 0 is assumed, which means only one large TOC at the root level will generated. Any value greater than 0 indicates how deep into the child folder structure TOC files will be generated, with the parent TOC having references to those located in the child folders.