docfx: a .NET API documentation generator that Microsoft Learn left behind

What docfx generates that a Markdown-only generator does not

The README describes docfx as a tool to "Build your technical documentation site with docfx, with landing pages, markdown, API reference docs for .NET, REST API and more." The distinguishing part is the middle of that list. A plain Markdown site generator turns files into HTML and stops. docfx also reads compiled .NET assemblies, extracts the XML documentation comments attached to types and members, and emits a reference section with one page per namespace, class and method. The same pipeline handles REST API descriptions, so a service that publishes an OpenAPI document can get reference pages from it too.

That makes the target audience narrow and specific. It fits library maintainers who already annotate public members with XML comments and want those comments to become a browsable site without writing the pages by hand. It fits teams whose documentation lives in the same repository as the code and is reviewed in the same pull requests. It does not fit a marketing site, a blog, or a project whose public surface is a command line tool with no assembly to reflect over.

The build pipeline: Markdown in, metadata, templates, static HTML out

The repository layout reflects a three-part pipeline. The src/ directory holds the tool itself, schemas/ holds the configuration schemas that docfx.json is validated against, and templates/ holds the site themes, which the contributing guide says are built with npm before the .NET solution is compiled. A build therefore has two distinct stages: a metadata stage that reads assemblies and produces an intermediate model, and a rendering stage that combines that model with Markdown files and applies a template to produce HTML.

This split is why the tool ships with a Dockerfile that installs Node.js and a Chromium browser alongside the .NET SDK. The Dockerfile sets PLAYWRIGHT_NODEJS_PATH to /usr/bin/node and runs playwright.ps1 with install --with-deps chromium. That is a heavier container than a pure Markdown generator needs, and it tells you the rendering stage can drive a real browser rather than only concatenating strings.

Configuration is centralised in a docfx.json file. The getting-started steps pass that file explicitly on the command line, so the file is the unit of configuration rather than a set of flags. The schemas/ directory exists so editors can validate the file, which matters because a malformed docfx.json fails the build rather than degrading quietly.

Installing docfx and building a first site

docfx ships as a .NET global tool on NuGet, so installation assumes a .NET SDK is already present. The README gives the install command directly:

dotnet tool install -g docfx

After that, the README's getting-started sequence scaffolds a project and builds it in two commands. The -y flag accepts the defaults for the scaffolding prompt:

docfx init -y
docfx build docfx_project/docfx.json --serve

The second command builds the site and starts a local server. According to the README, you then open https://localhost:8080 to see the sample site. Note the path separator in the README example is a Windows-style backslash; on macOS or Linux you would write the same path with a forward slash. The port is 8080 and the --serve flag is what starts the server rather than exiting after the build.

If you would rather not install the tool on your machine, the repository's Dockerfile shows the container route. It installs a pinned version as a global tool and sets docfx as the entry point, with /opt/prj as the working directory and a declared volume:

ARG DOCFX_VERSION=2.78.2
RUN dotnet tool install docfx -g --version ${DOCFX_VERSION}
WORKDIR /opt/prj
VOLUME [ "/opt/prj" ]
ENTRYPOINT [ "docfx" ]

The ARG line is the part worth copying into your own image: pinning DOCFX_VERSION means a rebuild does not silently pick up a newer release. The Dockerfile's default is 2.78.2, which is older than the most recent release listed in the repository, so treat it as an example of the pattern rather than a current recommendation.

The maintenance question the README answers plainly

Most project READMEs avoid the awkward history. This one does not. It states that docfx "has been transitioned to be a .NET Foundation project" and that "Microsoft Learn no longer uses docfx and do not intend to support the project since Nov 2022." The same section says docfx "is planned to continue as a community-driven project."

That is a candid framing and it should shape how you evaluate the tool. The project is not archived, and the last push to the default branch was on 2026-09-22, so work is happening. But the release cadence is explicitly irregular: the README says docfx "is _not_ released under a regular cadence, new versions arrive when maintainers see enough changes that warrant a new releases." The release list bears that out. v2.78.5 landed on 2026-02-24, and v2.78.6 and v2.80.1 both landed on 2026-09-17 and 2026-09-18, roughly seven months later.

For a documentation tool this matters less than it would for a runtime dependency. Your output is static HTML, so a frozen version keeps working. What you lose with an irregular cadence is predictable timing for fixes to template bugs or new framework support. Plan to pin a version and upgrade deliberately rather than tracking latest.

Where docfx is the wrong choice

The clearest failure mode is a project with no .NET assembly and no OpenAPI document. The API reference generation is the reason to pick docfx over a general static site generator, and if you cannot feed it metadata, you are paying the configuration cost of docfx.json and the template build for a Markdown renderer you could get with far less setup.

A second boundary is the theme ecosystem. The README points contributors at the templates directory and the npm build, and the getting-started flow uses whatever template the init command scaffolds. The repository does not document a marketplace of third-party templates the way some static site generators do, so if your requirement is a large catalogue of ready-made themes, that requirement is better served elsewhere.

A third is the container footprint. The official Dockerfile installs Node.js and Chromium with dependencies. If your CI environment is constrained to small images, or your build runs in a sandbox that forbids launching a browser, that image will not fit. Nothing in the README suggests a lighter official variant.

Finally, consider the documentation gap around failure. The README covers install, init and build. It does not document rollback, migration between versions, or what happens when a docfx.json schema changes between releases. If you need a documented upgrade path, you will be reading release notes and testing.

docfx compared with Doxygen, MkDocs and Sphinx

The natural comparison is Doxygen, because both extract API documentation from source. The difference is the input. Doxygen parses source files directly and supports many languages. docfx reads compiled .NET assemblies and their XML comment files, which means it sees exactly the public surface the compiler sees, including types generated at build time. If your project is a single C# library, that is an advantage. If your project mixes C#, C++ and Python, Doxygen's source-level approach covers all of them and docfx does not.

Against MkDocs, the split is metadata. MkDocs is a Markdown-to-site generator with a plugin system, and it has no built-in concept of reflecting over an assembly. You would need a plugin to produce API pages, and the result would not be the same pipeline. Choose MkDocs when your documentation is prose and your API reference is generated elsewhere or written by hand.

Sphinx sits closer to Doxygen in that it is language-aware through domain-specific extensions, and it is strongest in the Python ecosystem. The practical question is which language your public surface is written in. For a .NET library, docfx's assembly-based extraction removes a class of drift that hand-maintained reference pages always accumulate.

Licence, contributions and what the project asks of you

docfx is licensed under MIT, and the README links the LICENSE file at the repository root. MIT is permissive: you can use the tool commercially, modify it, and redistribute it, provided the copyright notice and permission notice travel with copies. The repository also carries a THIRD-PARTY-NOTICES.TXT file, which is where the licences of bundled dependencies are recorded. If you vendor docfx into a product or ship its output inside a commercial distribution, that file is the one to read before your own legal review, not this article.

On contribution, the README points questions at Discussions and bugs or feature proposals at Issues, and flags issues labelled help-wanted as good starting points for code contributions. The prerequisites are specific: Visual Studio 2022 Community or higher, .NET SDK 8.x, 9.x and 10.x, and NodeJS 24.x.x. Building the templates requires npm install and npm run build, and the test suite requires git lfs checkout to fetch files used for snapshot testing. That snapshot-testing setup is a signal about how the maintainers guard rendering output, and also a warning that a local test run will fail in confusing ways if you skip the LFS step.

Roadmap visibility comes from GitHub Milestones rather than a published plan. The README describes a Working Set milestone for features being actively worked on and a Backlog milestone for candidates not yet being worked on, and notes that not every item in the Working Set will ship in the next release.

Editorial conclusion

Adopt docfx if you ship a .NET library or REST API and want reference pages generated from XML comments and OpenAPI descriptions alongside hand-written Markdown, without running a JavaScript build chain. Do not adopt it if you need a documentation framework with a large third-party theme ecosystem, or if you expect Microsoft Learn to keep the project moving. Before committing, verify two things yourself: that a current .NET SDK is available on your build agents, and that the templates directory builds with the Node.js version your CI image provides, because the repository pins NodeJS 24.x.x for template work.

Frequently asked questions

Official sources

1. dotnet/docfx on GitHub
2. License: MIT
3. Project website
4. README
5. Releases