dotnet/docfx
Docfx
Docfx is a documentation build tool that generates structured API reference pages from compiled .NET assemblies and XML documentation comments, while also functioning as a markdown static site generator for technical documentation. It combines automated API metadata extraction with markdown rendering to build developer portals and documentation sites, producing output simultaneously in HTML, JSON, and PDF formats from a single build configuration.
The tool provides fine-grained control over which APIs appear in the generated documentation through visibility-based filtering, attribute-based exclusion, custom rule sets, and programmatic filter callbacks. It manages site navigation with nested table of contents composition, navigation bar population, and cross-referenced content organization, while also supporting search engine optimization through sitemap generation and configurable URL structures.
Docfx handles documentation generation from multiple sources including compiled assemblies, project files via MSBuild design-time compilation, individual source code files, and XML comments. It applies metadata through YAML front matter with configurable precedence, supports page redirection, and allows customization of API page layouts and namespace table of contents hierarchies. The build configuration accepts options to control compilation and output, and the resulting static files are ready for deployment to any hosting server.
Features
- .NET API Reference Generators - Generates structured API reference pages from compiled .NET assemblies and XML documentation comments.
- API Reference Generators - Automatically generates structured API reference pages from compiled .NET assemblies and XML comments.
- Programmatic Generation APIs - Provides a NuGet library with APIs to build a docset and generate managed reference YAML files from code.
- Nested Compositions - Builds site navigation by embedding one toc.yml file inside another, enabling reusable content hierarchies.
- Documentation Site Generators - Converts markdown, .NET assembly XML comments, and REST API Swagger files into rendered HTML pages, JSON models, or PDF output.
- Markdown Renderers - Converts markdown files with YAML metadata into HTML pages using a configurable rendering pipeline.
- Static Documentation Generation - Converts markdown files and API metadata into searchable HTML, JSON, or PDF static websites.
- Static Site Generation - Outputs a folder of pre-rendered HTML, JSON, and PDF files ready for deployment to any static hosting server.
- Static Site Generators - Builds searchable documentation websites from markdown files with custom front matter and extensions.
- Technical Content Organizers - Organizes technical documentation with nested tables of contents, navigation bars, and cross-referenced content.
- Technical Documentation Frameworks - Combines automated API metadata extraction with markdown rendering to build developer portals and documentation sites.
- API Documentation Generators - Reflects compiled .dll or .exe files and their side-by-side XML documentation to produce API reference pages.
- Documentation Build Configurations - Accepts build options to control how a documentation set is compiled and output.
- Documentation Build Tools - Manages site navigation, URL mapping, front-matter metadata, and cross-platform export for documentation projects.
- XML Documentation Comments - Converts XML documentation comments in .NET source code into rendered HTML documentation pages.
- Multi-Format Exports - Renders documentation simultaneously to HTML, JSON, and PDF formats from a single build configuration.
- Multi-Format Document Exports - Produces documentation output in HTML, JSON, and PDF formats from a single source of truth.
- API Attribute Filters - Filters generated API documentation by excluding types and members with specific .NET attributes.
- Front-Matter Precedence Rules - Attaches key-value attributes to articles via YAML front matter, global config, or per-file config with a defined precedence order.
- Member Visibility Filtering - Controls which API members appear in generated documentation based on accessibility modifiers.
- Project-Based Generators - Uses MSBuild to perform a design-time build of .csproj, .vbproj, or solution files before generating API documentation.
- Source File Compilers - Compiles individual .cs or .vb source files using the .NET SDK to produce API reference documentation.
- Design-Time Builds - Uses MSBuild to compile .NET projects without producing binaries, extracting metadata for documentation generation.
- API Documentation Rule Sets - Applies YAML rule sets to include or exclude APIs based on UID patterns, types, or attributes during generation.
- Sitemap Generators - Produces a sitemap.xml file with configurable URL metadata for search engine indexing.
- Development Utilities - Tools for building and publishing API documentation.
- Documentation and API Tools - Static site generator for .NET API documentation.
