DocFX Overview

This content was generated with the assistance of AI and should be verified against the official documentation of each tool before being relied on in production.

This section’s bibliography lists the reference material consulted while preparing these pages.

This page was written against DocFX 2.81.0 (published on NuGet and GitHub on 2026-09-25, the latest release) and checked on 2026-10-26. DocFX is the documentation generator of the .NET ecosystem: it turns XML documentation comments from C# and Visual Basic code, Markdown articles and optionally Swagger files into a static website or PDF files. The pages of this subsection use Pocket Units, the running example of the section, a small units-conversion library whose C# sources (a Converter class and a LengthUnit enum) are documented with XML comments.

What DocFX is and why it exists

DocFX reads two kinds of input and merges them into one site:

  • API sources. .NET projects, solutions, source files or compiled assemblies. DocFX extracts the public API and the XML documentation comments into YAML files (the metadata stage).

  • Conceptual content. Markdown articles, table-of-contents files (toc.yml) and images that you write by hand.

The build stage compiles both into HTML pages that link to each other, so an article can point at a class and a class page can carry extra Markdown. The value of the tool, in the words of its own documentation, is bringing together static documentation pages and .NET API documentation; it can be used as a plain static site generator, but that is not where it is strongest. The same engine can also render REST API pages from Swagger 2.0 files and, from version 2.73.0 with the modern template, PDF files.

The whole configuration lives in one JSON file, docfx.json, with a metadata section (the API extraction) and a build section (the site). The default output folder is _site, a folder of static files that any web server can host.

Governance and maintenance

DocFX started as a Microsoft project that powered Microsoft Learn. The repository README states that Microsoft Learn no longer uses DocFX and has not intended to support it since November 2022, and that the project moved to the .NET Foundation. Since then it is a community-driven open source project (MIT licence, copyright held by the .NET Foundation and contributors); the project asks interested people to join it and to use GitHub Discussions and Issues for questions and proposals. The documentation site is labelled "Supported by the .NET Foundation".

In practice the following holds:

  • There is no company with a support contract behind it. Fixes and features come from volunteers, so response times on GitHub vary. On the check date the repository had several hundred open issues.

  • There is no fixed release schedule: a release appears when the maintainers judge that enough changes have accumulated. Releases are still frequent, for example 2.80.1 on 2026-09-18 and 2.81.0 on 2026-09-25.

  • The tool is distributed as a .NET tool on NuGet (package docfx), and nightly builds are published to GitHub Packages.

  • Pin the version in CI. Releases change behaviour in small ways (for example 2.80.1 stops metadata generation when the restore of a project fails, and 2.81.0 limits the run time of custom template scripts), so an unpinned tool can break a build that worked yesterday.

When to choose DocFX

Choose DocFX when:

  • The main content of the site is the API reference of a .NET library, generated from XML comments that already live in the code, with a handful of hand-written articles around it.

  • You want the API pages to link to the Microsoft documentation of base class library types, or to link your own types from articles by identifier (see Links and Cross References).

  • The team writes C# or Visual Basic and prefers a .NET tool in the build over a Node.js or Python toolchain.

Look at the other tools of this section when the need is different:

  • Several repositories must be assembled into one versioned site: Antora.

  • A React-based site with a blog and plugins: Docusaurus.

  • A Python project with Markdown documentation and mkdocstrings: Zensical.

The official documentation describes no versioned documentation and no translation workflow (its tools page only lists the DocLanguageTranslator companion tool for multi-language folders); a site with several versions can be built by running DocFX once per version and publishing the outputs side by side. Its supported source languages are C# and Visual Basic (the generated syntax is shown in C#), F# projects are not supported as project input, and for any language outside .NET see Additional Languages.

Requirements

  • The .NET SDK 8.0 or later. The quick start of the documentation asks for 8.0 or higher, and the contributor documentation lists SDK 8, 9 and 10. The checks on this page used the .NET SDK 10.0.403, in the mcr.microsoft.com/dotnet/sdk:10.0 Docker image.

  • Node.js 20 or later, only for PDF files. The documentation marks it optional.

  • A .NET SDK is also needed on the machine that builds the API reference, because DocFX loads the projects with MSBuild. The installation must have the workloads and components the projects need.

Quick start

The three commands of the official quick start are:

dotnet tool update -g docfx
docfx init
docfx docfx.json --serve

Source: DocFX docs: Quick Start

dotnet tool update -g docfx installs DocFX as a global tool, or updates it when it is already installed. To install an exact version use dotnet tool install -g docfx --version 2.81.0. docfx init starts a short wizard that creates a sample project in the current folder; docfx init -y accepts every default without asking. docfx docfx.json --serve builds the site and serves the output at http://localhost:8080. To see changes, run docfx docfx.json again in another terminal.

A first site with Pocket Units

The following session was run in the mcr.microsoft.com/dotnet/sdk:10.0 image. The Pocket Units project sits in a src folder next to the docs folder in which docfx init -y created its files:

src/PocketUnits/PocketUnits.csproj
src/PocketUnits/Converter.cs
src/PocketUnits/LengthUnit.cs
docs/docfx.json      (created by docfx init -y)
docs/index.md
docs/toc.yml
docs/docs/introduction.md
docs/docs/getting-started.md
docs/docs/toc.yml

The generated docfx.json has a metadata section that reads every .csproj below ../src and writes YAML to api, and a build section that includes all Markdown and YAML files, uses the default and modern templates together and writes to _site:

docs/docfx.json (generated by docfx init -y, shortened)
{
  "metadata": [
    { "src": [ { "src": "../src", "files": [ "**/*.csproj" ] } ], "dest": "api" }
  ],
  "build": {
    "content": [ { "files": [ "**/*.{md,yml}" ], "exclude": [ "_site/**" ] } ],
    "resource": [ { "files": [ "images/**" ] } ],
    "output": "_site",
    "template": [ "default", "modern" ],
    "globalMetadata": {
      "_appName": "",
      "_appTitle": "",
      "_enableSearch": true,
      "pdf": true
    }
  }
}

Source: DocFX docs: .NET API Docs (the file shown is the output of the command run here, not a copy of that page)

The generated file sets pdf to true. With that setting docfx docfx.json also creates PDF files, and in a container without Node.js the first run stopped with this error:

error: FatalError: Docfx.Exceptions.DocfxException: Node.js executable is not found. Try to install
Node.js or set the `PLAYWRIGHT_NODEJS_PATH` environment variable.

So on a machine without Node.js, delete the pdf line from globalMetadata (or install Node.js 20 or later) before the first build. With the line removed, the build of the three source files succeeded:

Loading project /w/src/PocketUnits/PocketUnits.csproj
  Determining projects to restore...
  Restored /w/src/PocketUnits/PocketUnits.csproj (in 959 ms).
Processing PocketUnits
Creating output...
Building 3 file(s) in ConceptualDocumentProcessor(BuildConceptualDocument=>ValidateConceptualDocumentMetadata)...
Building 3 file(s) in TocDocumentProcessor(BuildTocDocument)...
Building 3 file(s) in ManagedReferenceDocumentProcessor(...)...
Applying templates to 9 model(s)...
XRef map exported.
Extracting index data from 6 html files

Build succeeded.

    0 warning(s)
    0 error(s)

The output folder contained index.html, toc.json, xrefmap.yml, manifest.json, public/ (the template assets) and api/ with one page per namespace and type: PocketUnits.html, PocketUnits.Converter.html and PocketUnits.LengthUnit.html. Running docfx docfx.json --serve afterwards printed Serving "/w/docs/_site" on http://localhost:8080 and the site answered with HTTP 200. The serve step was checked from inside the container with curl; the pages were not opened in a browser for this documentation.

The toc.yml that docfx init creates at the root links the docs folder and the api folder, and the API pages are reachable from the "API" entry of the navigation bar:

- name: Docs
  href: docs/
- name: API
  href: api/

Source: DocFX docs: Quick Start (the file shown is the output of docfx init -y)

The three stages

The root command docfx runs the stages one after another. Each can also run alone:

Command Stage Output

docfx metadata

Extracts the API and the XML comments from projects, solutions, source files or assemblies.

YAML files in the folder named by metadata.dest (api above).

docfx build

Compiles Markdown, TOC files and the YAML into HTML with the selected template.

The site in _site.

docfx pdf

Creates PDF files from the built site (needs the modern template, 2.73.0 or later, and Node.js).

One toc.pdf per TOC in the output folder.

The details are in Basic Concepts and Pipeline and CLI.

Documenting C# and Visual Basic code

DocFX consumes ordinary XML documentation comments, so the way to write them is the language’s own convention. The C# side of that is covered in C# coding conventions and documentation, the project and tool side in C# build and tooling, and the Visual Basic side, including the compiler warnings that check comments, in Visual Basic XML documentation and analyzers. This subsection does not repeat those rules; it shows what DocFX does with the comments (see DotNet API Docs). One DocFX specific point: DocFX parses the text of the comments as Markdown, so Markdown written in a comment can render badly in places that do not support it, such as the IntelliSense window of an editor.

Map of this subsection

Page Covers

Basic Concepts and Pipeline

Metadata, build and PDF stages, Markdown engine, templates and the _site folder.

docfx.json

Every key of metadata and build, file mappings, metadata precedence and redirects.

DotNet API Docs

Projects, solutions and assemblies as input, filters, layouts, restore behaviour and SDK compatibility.

REST API Docs

Swagger 2.0 files, tags and what to do with OpenAPI 3.

Markdown

DocFX Flavored Markdown: alerts, includes, code snippets, tabs, diagrams and math.

Table of Contents

toc.yml, nested and reference TOCs and the navigation bar.

Links and Cross References

Links by unique identifier, cross-reference maps and the base class library map.

Templates and Customization

The default and modern templates, custom CSS and JavaScript, partials and site settings.

PDF Output

docfx pdf, cover and TOC pages and the Node.js and Playwright requirements.

Additional Languages

Custom converters that produce API pages for languages outside .NET.

CLI

The commands, options and environment variables of the docfx tool.

Deployment

GitHub Pages, Azure DevOps, the sitemap and search settings.

Pitfalls and version notes

  • The docfx init scaffold enables PDF output. Without Node.js the first build fails, as shown above, which looks like a broken installation but is only a missing optional dependency.

  • The scaffold looks for projects in ../src, relative to docfx.json. DocFX globs do not reach outside the folder containing docfx.json, so a project in another place needs the src property of the metadata entry. If the folder does not exist, docfx reports a warning that it cannot find toc.yml or toc.md inside api/, because the metadata stage produced nothing (this happened in a first run without the src folder).

  • DocFX is community-maintained: check the release notes on GitHub before upgrading and pin the version in CI.

  • Mermaid, math and PDF output need the modern template, which is the second entry of the template list that the scaffold generates.

References