# What Tools Are Used for Generating Documentation from the `docs` Directory in ASP.NET Core? > ASP.NET Core uses DocFX to generate API reference and conceptual documentation from its docs directory. Learn how this static-site generator is orchestrated by MSBuild and GitHub Actions. - Repository: [.NET Platform/aspnetcore](https://github.com/dotnet/aspnetcore) - Tags: how-to-guide - Published: 2026-08-01 --- **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`](https://github.com/dotnet/aspnetcore/blob/main/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: ```xml ``` ## CI/CD Pipeline Automation Documentation generation is automated via **GitHub Actions** in [`.github/workflows/documentation.yml`](https://github.com/dotnet/aspnetcore/blob/main/.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: ```bash # 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`](https://github.com/dotnet/aspnetcore/blob/main/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`](https://github.com/dotnet/aspnetcore/blob/main/.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`](https://github.com/dotnet/aspnetcore/blob/main/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`](https://github.com/dotnet/aspnetcore/blob/main/.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.