Basic Concepts and Pipeline

DocFX is a command-line tool that brings together two kinds of content in one site: hand-written Markdown pages (articles) and API reference pages generated from .NET source code. For the API part it relies on the XML documentation comment syntax that C# and Visual Basic already have, so no second documentation format has to be learned. Both languages can be read, but the generated signatures are always shown in C# syntax.

The work is split into stages that can be run on their own, because each one consumes the files the previous one produced:

Running the stages separately is useful to understand what DocFX does, to inspect the intermediate YAML, and to regenerate only the part that changed. In day-to-day use one command runs everything:

Source: DocFX docs: Basic Concepts

Without a sub-command, docfx runs the metadata, build and pdf commands in turn, as the command-line overview lists. The pdf step only produces files for tables of contents that opt in with pdf: true; the site built in this page does not, and its log shows no pdf activity.

The figure below follows the data. Each box is a file or folder you can open and read; each arrow is a DocFX command or an internal step of it.

Pipeline of the DocFX commands, from .NET source and Markdown to the _site folder, PDF files and a local preview.

Everything is driven by one JSON file, docfx.json, which has a metadata section for the first stage and a build section for the second. Its keys are covered in docfx.json.

All commands in this page run in a small project that documents the Pocket Units length converter. The folder looks like this:

The project file targets net8.0 and sets GenerateDocumentationFile, which is good practice for a library but is not what DocFX reads (see the metadata stage below). The code carries ordinary XML documentation comments; this is the converter, trimmed to the part that matters:

Source: DocFX docs: .NET API Docs

The configuration used throughout is the smallest one that produces a complete site:

Source: DocFX docs: Template

The src entry says where the projects are and which files in that folder to take, dest says where the generated YAML goes, content lists the files the build step reads, output is the site folder and template selects the look. The meaning of each key, and the many other options, are in docfx.json; how the C# comments become pages is in DotNet API Docs. The comment syntax itself is covered in C# coding conventions and documentation and, for Visual Basic, in Visual Basic XML documentation, analyzers and code style; the project and tooling side is in C# build and tooling.

The first stage is run with docfx metadata docfx.json. It reads the sources listed in the metadata section and searches them for XML documentation entries. A detail that surprises people: for project input DocFX does not read the .xml file the compiler can emit; it uses the Roslyn compiler to walk the code itself. A project can also be replaced by compiled .dll or .exe files together with their .xml files (see DotNet API Docs).

Running it on Pocket Units printed:

Restore ran automatically before the project was loaded. The folder named by dest then contains:

There is one YAML file per namespace and per type, plus a generated table of contents. This is the only auto-generated toc.yml: every other table of contents is written by hand. The head of the file for the class shows the shape of the data (listing shortened; the real file continues with the members and their syntax):

Source: DocFX docs: Basic Concepts

Three things are worth noticing:

The member marked with <exclude /> in the C# source does not appear in the YAML at all: searching the generated PocketUnits.Converter.yml for Reset finds nothing, and neither does the rendered page.

The second stage is run with docfx build docfx.json. Appending --serve hosts the result on a local web server for preview. According to the official description, the stage does four things:

The log of the Pocket Units build names the processors that handled each kind of input:

The build output goes to the folder named by output (by convention _site). For the modern template the site contains static HTML for every page, the shared assets and a few machine-readable files:

Running docfx docfx.json --serve builds and then hosts _site on http://localhost:8080.

PDF output is optional and builds on the site produced by the build stage. It applies to DocFX 2.73.0 or newer and to the modern template. Setting the pdf global metadata to true makes the built site show a "Download PDF" button, and the docfx pdf command then creates a toc.pdf file for every table of contents in the output directory; pdf: true, pdfFileName, pdfTocPage and related keys can also be set per table of contents. The details are in PDF Output. The pdf stage was not executed for this page: it renders pages in a headless browser, which the Docker image used here does not provide.

Other commands (init, template, download, merge) and the options such as --serve, --warningsAsErrors and --dryRun are covered in Command-Line Interface.