What Tools Are Used for Generating Documentation from the `docs` Directory in ASP.NET Core?

ASP.NET Core uses DocFX, a static-site generator orchestrated by MSBuild targets in eng/CodeGen.proj and GitHub Actions workflows to transform Markdown files in the docs directory into public API reference and conceptual documentation.

The dotnet/aspnetcore repository maintains its technical documentation in a dedicated docs folder at the repository root. Understanding what tools are used for generating documentation from the docs directory reveals a pipeline that combines DocFX for static site generation with automated build scripts and continuous integration workflows.

DocFX Configuration in docs/docfx.json

At the heart of the documentation pipeline sits DocFX, a .NET-based static site generator. The tool consumes Markdown source files and API metadata to produce the HTML output seen on the ASP.NET Core documentation site.

According to the ASP.NET Core source code, the configuration is defined in docs/docfx.json. This file specifies the source Markdown locations, API metadata paths, output directories, and theming options that control how the final site renders.

MSBuild Integration and the GenerateDocs Target

The build process integrates documentation generation into the repository's standard MSBuild system through eng/CodeGen.proj. This project file defines a GenerateDocs target that invokes DocFX with the repository's configuration.

As implemented in dotnet/aspnetcore, this target ensures documentation generation is treated as a standard build artifact. The target executes DocFX against the configuration file to produce the static site output:

<Target Name="GenerateDocs">
  <Exec Command="docfx $(RepoRoot)\docs\docfx.json -f" />
</Target>

CI/CD Pipeline Automation

Documentation generation is automated via GitHub Actions in .github/workflows/documentation.yml. This workflow runs on CI agents and triggers the GenerateDocs MSBuild target, creating deployable artifacts and managing the publication pipeline.

The workflow coordinates the build process by restoring DocFX dependencies and executing the generation target, ultimately producing the documentation site as a build artifact suitable for deployment to hosting environments like GitHub Pages.

API Metadata Generation

Before DocFX can render API reference pages, the repository generates API description JSON files that serve as input metadata. The src/Tools/Extensions.ApiDescription.Client projects produce these description files, which DocFX consumes to create the interactive API documentation pages.

This separation of concerns allows the documentation system to automatically reflect the latest public APIs from the source code while maintaining conceptual documentation separately in the docs folder.

Local Documentation Build Workflow

Developers can reproduce the complete documentation build locally using standard .NET CLI commands. To generate the documentation site on your development machine:

# Install DocFX (requires .NET 6+)

dotnet tool install -g docfx

# From the repository root, restore the DocFX packages

dotnet restore docs

# Generate the documentation site with a local server

docfx docs/docfx.json --serve

The --serve flag launches a local web server to preview the generated site, while the -f flag (used in CI) forces rebuilding all documentation from scratch.

Summary

• DocFX serves as the primary static-site generator, configured via docs/docfx.json to transform Markdown into HTML.
• The GenerateDocs target in eng/CodeGen.proj integrates documentation builds into the MSBuild pipeline.
• GitHub Actions workflows in .github/workflows/documentation.yml automate the generation and publication process.
• API metadata is produced by src/Tools/Extensions.ApiDescription.Client projects to feed the API reference documentation.
• Local builds require only the DocFX tool and the dotnet restore docs command to reproduce the CI output.

Frequently Asked Questions

What is the primary tool used to generate ASP.NET Core documentation from the docs directory?

DocFX is the primary tool used to generate ASP.NET Core documentation from the docs directory. It is a static-site generator that processes Markdown files and API metadata to produce the HTML documentation site.

Where is the DocFX configuration file located in the ASP.NET Core repository?

The DocFX configuration file is located at docs/docfx.json in the repository root. This JSON file defines the source paths, output directories, and theming options for the documentation build.

How does the CI pipeline trigger documentation builds in dotnet/aspnetcore?

The CI pipeline triggers documentation builds through the GenerateDocs target defined in eng/CodeGen.proj, which is invoked by the GitHub Actions workflow in .github/workflows/documentation.yml. This target executes the DocFX command with the repository's configuration to produce the documentation artifacts.

Can I build the ASP.NET Core documentation locally without using the CI pipeline?

Yes, you can build the documentation locally by installing the DocFX tool globally with dotnet tool install -g docfx, restoring packages with dotnet restore docs, and running docfx docs/docfx.json --serve from the repository root. This reproduces the same output generated by the CI pipeline.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}