Open-source project
dotnet/docfx avatar
dotnet/docfx

docfx, a .NET documentation generator that no longer has Microsoft behind it

Static site generator for .NET API documentation.

4,452 stars886 forksC#MIT

At a glance

What is it?
docfx turns .NET source comments and markdown into a static documentation site with API reference pages, and it now ships without the company that built it. Its quickstart, contributor toolchain and pinned container image each carry a detail worth reading before you adopt it.
Who is it for?
docfx fits a team that publishes .NET API reference pages from source comments and wants the output hosted as static files it controls. It does not fit a team that expects a vendor behind the tool, since Microsoft stepped away in Nov 2022 and new versions land only when maintainers judge enough has changed.
Can I use it commercially?
Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 6 days ago.
What is it written in?
Mainly C#, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 14, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • dotnet/docfx4,452 ★ · +3
Star history
Repository2026-09-232026-11-14
dotnet/docfx4.4k4.5k

3 Stars in the last 52 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

Microsoft stopped backing docfx after November 2022

docfx renders a static documentation site from markdown and source comments: landing pages, API reference pages for .NET assemblies, and REST API pages. That is the short version of a tool built at Microsoft, and the handover it went through is the first thing to weigh. Since Nov 2022 Microsoft Learn no longer uses docfx, and Microsoft does not intend to support it. The repository now sits with the .NET Foundation and runs as a community-driven project, with maintainers asking interested parties to open a discussion thread if they want to reach the community team.

So the vendor question is settled in one direction. The site at https://dotnet.github.io/docfx/, the planned work and the review queue all live in the same repository that contributors fork, and no Microsoft team owns a build that breaks. For a group that wants a documentation tool to outlive one company's priorities, that is the shape of the project today. The code sits under the MIT licence, and the last push to `main` landed on 2026-11-01.

The quickstart build command uses a Windows path separator

The shortest route to a running site is three commands. Install the tool, let the scaffold create a project, then build and serve it:

bash
docfx init -y
docfx build docfx_project\docfx.json --serve

The sample site answers on https://localhost:8080.

That middle line hides a portability trap. The path is `docfx_project\docfx.json`, written with a Windows separator, and the fence around it names no shell, so nothing on the page tells a reader which command interpreter will parse it. On Linux and macOS a backslash is an ordinary character inside a filename, so the shell looks for one file with that whole name and reports it missing rather than descending into a directory. Copying the quickstart verbatim on a POSIX machine means replacing that separator by hand before the sample site ever appears.

Global tool install, and a container pinned to an older build

Installation for readers is one line, taken from the getting started steps:

bash
dotnet tool install -g docfx

Container users get a Dockerfile at the repository root that starts from `mcr.microsoft.com/dotnet/sdk:8.0-noble`, appends `/root/.dotnet/tools` to PATH, and installs the tool from NuGet at a version chosen by a build argument:

dockerfile
ARG DOCFX_VERSION=2.78.2
RUN dotnet tool install docfx -g --version ${DOCFX_VERSION} && \

That pin is the detail worth catching. The newest tag is 2.81.0, dated 2026-09-25, yet the image installs 2.78.2, which sits behind even the 2.78.6 patch that shipped on 2026-09-17. Nothing in the file warns about the gap, because the argument reads like a knob a pipeline sets anyway. Copying this Dockerfile into CI quietly pins you to a build three version lines behind the current one. Override the argument if the exact tag matters.

Contributing needs three SDKs, NodeJS and a git lfs step

Building from source asks for more than the single-command install. The setup calls for Visual Studio 2022 (Community or higher), .NET SDK 8.x, 9.x and 10.x, and NodeJS (24.x.x), then splits the work into two halves: the site templates under `templates`, and the C# solution.

bash
npm install
npm run build
dotnet build
dotnet test
git lfs checkout

`git lfs checkout` is the step that catches out a clean clone. Snapshot tests keep their expected output in Git LFS, so a fresh checkout leaves those fixtures as pointer files until the real content is fetched, and the run has nothing meaningful to compare against in the meantime. The Dockerfile shows the second runtime dependency in the same picture: it installs NodeJS and then runs a Playwright script to fetch chromium `--with-deps`, so the container image also carries a chromium binary.

The build docs name docfx.sln while the root ships docfx.slnx

Contributors following the Build and Test instructions are told to open `docfx.sln` in Visual Studio. No such file sits at the root of the repository; the tree ships `docfx.slnx` instead, the XML solution format. The command line path is unaffected, since `dotnet build` works from the root either way, which leaves the gap sitting squarely on the IDE route described in the text.

The root also carries central build plumbing the walkthrough never explains. `Directory.Build.props`, `Directory.Build.targets` and `Directory.Packages.props` sit next to `global.json`, `.vsconfig` and `.editorconfig`, and the samples directory keeps its own copies of the props files. Package versions for the whole tree resolve through that central file.

Nightly packages move faster than the published tags

Code arrives through two channels with different speeds. Nightly builds go to GitHub Packages, which the README flags in a tip block for anyone who wants current code rather than the newest tag. Stable tags are cut from a commit on `main` that maintainers consider settled, and use of Conventional Commit is encouraged.

The cadence sentence is blunt about how little schedule there is: docfx is not released under a regular cadence, new versions arrive when maintainers see enough changes to warrant one, and preview builds go out to test breaking changes on real projects and collect feedback from the community. A team that upgrades on a timer has no date to aim at here. Pinning an explicit version is the only way to keep a build repeatable between the tags you pick, which is the job the Dockerfile build argument does badly out of the box.

Planned work sits in two GitHub milestones without dates

Future work is tracked in two GitHub Milestones rather than in a roadmap file inside the repository. The Working Set, milestone number 48, holds what maintainers are working on now, and the text warns that not every item in that bucket reaches the next version. The Backlog, milestone number 49, collects candidates for some future version that nobody has started yet.

For planning, the split between the two matters more than what either list contains. An entry in the Working Set tells you where attention sits, not when anything lands, and an entry in the Backlog says an idea was filed rather than scheduled. Both are GitHub objects rather than files, so the answer to whether a feature is coming can change without a single commit to the source tree. A stale clone of docfx tells you nothing about either list.

Undocumented root files and the samples you can copy

Several files at the root do work the walkthrough never describes. A `schemas/` directory sits beside `src/`, `templates/`, `test/` and `docs/`, and nothing in the getting started text says what belongs in it. `testEnvironments.json` also sits at the root. `SpellingExclusions.dic` keeps a checker away from words that are not in a dictionary, and `.xrefmap.json` sits at the root with no explanation in the text at all.

The `samples/` directory is the most usable undocumented asset. It splits into `samples/common/`, `samples/csharp/`, `samples/extensions/` and `samples/seed/`, and it carries its own `samples/Directory.Build.props` and `samples/Directory.Packages.props` so the example projects resolve their own package versions. For anyone who finds the scaffold produced by `docfx init -y` too bare, those folders are a working configuration the documentation never points at.

Editorial conclusion

docfx fits a team that publishes .NET API reference pages from source comments and wants the output hosted as static files it controls. It does not fit a team that expects a vendor behind the tool, since Microsoft stepped away in Nov 2022 and new versions land only when maintainers judge enough has changed. Before committing, open docfx.slnx rather than the docfx.sln the README names, decide whether the git lfs checkout step and a Playwright chromium install belong in your build, and pass your own version to the container instead of inheriting the 2.78.2 default.

Frequently asked questions

What is docfx?

docfx is a static site generator for .NET API documentation. It builds a technical documentation site with landing pages, markdown content, API reference pages for .NET and REST API pages.

How to install docfx?

Install it as a global dotnet tool with `dotnet tool install -g docfx`. Nightly builds are published to GitHub Packages for anyone who wants newer code than the newest tag.

How to use docfx?

Run `docfx init -y` to create a project, build it and pass `--serve`, then open https://localhost:8080 to see the sample site. The README build line uses a Windows path separator, so a POSIX shell needs it rewritten.

How to use docfx in Visual Studio?

The Build and Test instructions tell contributors to build `docfx.sln` in Visual Studio, though the repository root ships `docfx.slnx` instead. `dotnet build` remains the command line path from the root.

Is docfx free?

The project is licensed under the MIT License and is supported by the .NET Foundation. Microsoft Learn no longer uses docfx and does not intend to support the project since Nov 2022, so maintenance is community driven.

docfx vs doxygen

The README does not compare docfx with other documentation generators, so nothing there settles that choice. What it states is the scope: .NET API reference pages, REST API pages and markdown landing pages in one static site.

Official sources

  1. dotnet/docfx on GitHub
  2. License: MIT
  3. Project website
  4. README
  5. Releases
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/dotnet-docfx.svg)](https://hysenlabs.com/projects/dotnet-docfx)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/dotnet-docfx.svg)](https://hysenlabs.com/projects/dotnet-docfx)

Was this useful?