Build reliable documentation pipelines around DocFX with focused command-line tools for assembling content, validating links, generating navigation, translating pages, and preparing OpenAPI specifications.
Use one tool to solve a specific documentation problem, or combine them into a repeatable CI/CD workflow.
If these tools improve your documentation workflow, you can sponsor ongoing development and maintenance.
| When you need to... | Use | What it does |
|---|---|---|
| Combine documentation from multiple repositories or folders | 🧩 DocAssembler | Collects and restructures content, rewrites links, and applies configurable path or content replacements. |
| Generate DocFX navigation from a folder hierarchy | 🗂️ DocFxTocGenerator | Creates one or more toc.yml files with configurable ordering, titles, folder references, and generated index pages. |
| Catch documentation problems before publishing | 🔎 DocLinkChecker | Validates local and external links, anchors, pipe tables, and resources; it can also report or remove orphaned attachments. |
| Keep multilingual documentation structures aligned | 🌐 DocLanguageTranslator | Finds missing localized files and translates complete documents or selected line ranges with Azure AI Translator. |
| Publish OpenAPI content through DocFX | 🔄 DocFxOpenApi | Converts OpenAPI v2 or v3 JSON/YAML into the OpenAPI v2 JSON format expected by DocFX. |
Each tool has its own usage guide and command reference. All tools provide command-line help through --help.
The tools require the .NET 10 runtime. Install only the tools you need as global .NET tools:
dotnet tool install --global DocAssembler
dotnet tool install --global DocFxTocGenerator
dotnet tool install --global DocLinkChecker
dotnet tool install --global DocLanguageTranslator
dotnet tool install --global DocFxOpenApiTip
If .NET 10 is not installed but a newer major .NET runtime is available, allow the tool to roll forward to that runtime:
DocLinkChecker --roll-forward Major --docfolder ./docsThe --roll-forward Major option works with any of the companion tools and must appear before the tool-specific arguments.
Alternatively, set the DOTNET_ROLL_FORWARD environment variable. In PowerShell:
$env:DOTNET_ROLL_FORWARD = "Major"
DocLinkChecker --docfolder ./docsIn a Linux or macOS shell, set it for a single command:
DOTNET_ROLL_FORWARD=Major DocLinkChecker --docfolder ./docsFor example, validate links, attachments, and tables, then generate a DocFX table of contents:
DocLinkChecker --docfolder ./docs --attachments --table
DocFxTocGenerator --docfolder ./docs --sequence --override --indexing NotExistsNon-zero exit codes make the tools suitable for validation gates in automated builds. See each tool's guide for its exact exit-code behavior.
flowchart LR
Sources[Documentation sources] --> Validate[Validate links and resources]
Validate --> Assemble[Assemble content]
API[OpenAPI specifications] --> Convert[Convert for DocFX]
Assemble --> Generate[Generate toc.yml]
Convert --> Generate
Generate --> Build[Build with DocFX]
Build --> Publish[Publish documentation]
The tools are independent, so the pipeline can start with the pieces that fit your repository. Translation can run before validation when localized documentation is part of the build.
Note
The tools are built for .NET 10 and expect the .NET 10 runtime to be installed. If only a newer major runtime is available, use the roll-forward options described above.
Install a single package globally:
dotnet tool install --global DocLinkCheckerUpdate it later with:
dotnet tool update --global DocLinkCheckerThe package IDs match the tool names listed above.
Install all companion tools on Windows with Chocolatey:
choco install docfx-companion-toolsPrebuilt Windows executables are available from GitHub Releases. They are framework-dependent and require .NET 10.
Ready-to-adapt Azure Pipelines examples are included in this repository:
- Documentation validation uses Markdownlint and DocLinkChecker to validate Markdown, links, and attachments.
- Documentation build generates the table of contents, builds the DocFX site, and publishes it to Azure App Service.
The Dockerfile can package any one of the tools. This example builds and runs DocLinkChecker:
docker build --tag doclinkchecker:latest --build-arg tool=DocLinkChecker -f Dockerfile .When you mount a host directory for output or generated files, the runtime user needs write access. In the official .NET 10 runtime image, the default non-root user is app with UID/GID 1654; --user 1654:1654 runs the container as that built-in app account, not as your Windows host user. On Windows, bind-mounted files are commonly governed by Docker Desktop and WSL permissions, so prefer a writable directory inside the container or fix the mounted directory ownership from the WSL side before running the tool.
PowerShell (run as the image's built-in non-root user):
docker run --rm --user 1654:1654 -v ${PWD}:/workspace doclinkchecker:latest -d /workspaceLinux or macOS (match the host UID/GID):
docker run --rm --user "$(id -u):$(id -g)" -v "$(pwd):/workspace" doclinkchecker:latest -d /workspaceIf you do not pass --user, use a writable directory inside the container or a bind mount whose ownership matches the container's non-root UID/GID; otherwise writes can fail with Permission denied.
The repository also contains reusable guidance and examples:
- Markdown authoring guidelines
- Markdownlint guidelines
- End-user documentation guidelines
- Mermaid and UI-specific elements
Issues and pull requests are welcome. Keep pull requests focused and add one or more of these labels when the change should appear in the changelog:
| Category | Labels |
|---|---|
| 🚀 Features | feature, enhancement |
| 🐛 Fixes | fix, bug |
| 📄 Documentation | documentation |
The repository requires the .NET 10 SDK. Build and package all tools from PowerShell with:
.\build.ps1The Build & Test workflow restores, builds, and tests each solution individually. Release packaging is automated through the repository's Release & Publish workflow; maintainers can reproduce it with pack.ps1 after running the build script.
DocFX Companion Tools is licensed under the MIT License. See THIRD-PARTY-NOTICES.TXT for third-party notices. Several tools originated from work done with ZF.