CLI Reference

The DotNetDocs CLI provides commands to manage documentation projects and generate documentation from .NET assemblies.

Commands

dotnet docs add

Create and add a documentation project (.docsproj) to your solution. Usage:

dotnet docs add [options]

Options:

Option	Alias	Description	Default
`--solution <PATH>`	`-s`	Path to solution file (.sln or .slnx)	Current directory search
`--name <NAME>`		Name for the docs project	`{SolutionName}.Docs`
`--output <PATH>`	`-o`	Output directory for docs project	Project folder
`--type <TYPE>`	`-t`	Documentation type	`Mintlify`
`--prerelease`		Use latest prerelease SDK version	Latest stable version

Documentation Types:

Mintlify - Mintlify documentation with MDX support (default)
DocFX - DocFX documentation
MkDocs - MkDocs documentation
Jekyll - Jekyll documentation
Hugo - Hugo documentation
Generic - Generic markdown documentation

SDK Versioning: By default, dotnet docs add queries NuGet.org to find the latest stable version of DotNetDocs.Sdk and uses it in the generated .docsproj file. Use --prerelease to get the latest preview version instead.

# Use latest stable version (e.g., 1.0.0)
dotnet docs add

# Use latest prerelease version (e.g., 1.0.0-preview.31)
dotnet docs add --prerelease

Behavior:

Locates Solution

Searches current directory for .slnx (preferred) or .sln file if not specified

Creates Project

Generates .docsproj file with Mintlify configuration and default theme

Adds to Solution

Adds project to solution in “Docs” solution folder

Post-Processing

For .slnx files, adds Type="C#" attribute for proper Visual Studio support

Examples:

# Create Mintlify docs project with latest stable SDK
dotnet docs add

Generated Project Template:

Mintlify (Default)
Other Types

<Project Sdk="DotNetDocs.Sdk/1.0.1">
  <PropertyGroup>
    <DocumentationType>Mintlify</DocumentationType>
    <GenerateDocumentation>true</GenerateDocumentation>
    <NamespaceMode>Folder</NamespaceMode>
    <ShowDocumentationStats>true</ShowDocumentationStats>

    <ConceptualDocsEnabled>false</ConceptualDocsEnabled>
    <ShowPlaceholders>false</ShowPlaceholders>

    <MintlifyNavigationMode>Unified</MintlifyNavigationMode>
    <MintlifyTemplate>
      <Name>YourSolution</Name>
      <Theme>maple</Theme>
      <Colors>
        <Primary>#419AC5</Primary>
        <Light>#419AC5</Light>
        <Dark>#3CD0E2</Dark>
      </Colors>
    </MintlifyTemplate>
  </PropertyGroup>
</Project>

dotnet docs update

Update existing .docsproj files to use the latest DotNetDocs.Sdk version from NuGet. Usage:

dotnet docs update [options]

Options:

Option	Alias	Description	Default
`--project <NAME\|PATH>`	`-p`	Project name or path to .docsproj file to update	All .docsproj files in current directory
`--recursive`	`-r`	Search recursively in subdirectories	Current directory only
`--prerelease`		Update to latest prerelease SDK version	Latest stable version

The --project option accepts either a project name (e.g., MyProject.Docs) or a file path (e.g., MyProject.Docs.docsproj or path/to/MyProject.Docs.docsproj). If you provide just the project name, the tool will automatically append .docsproj to find the file.

Behavior:

Query NuGet

Queries NuGet.org for the latest version of DotNetDocs.Sdk (stable or prerelease)

Find .docsproj Files

Locates all .docsproj files (or a specific file if —file is specified)

Update SDK References

Updates Sdk="DotNetDocs.Sdk/X.X.X" to the latest version in each file

Report Results

Shows which files were updated and which were skipped

Examples:

# Update all .docsproj files in current directory
dotnet docs update

This command is useful when a new version of DotNetDocs.Sdk is released and you want to upgrade your documentation projects without manually editing each file.

dotnet docs build

Build documentation from .NET assemblies and XML documentation files. Usage:

dotnet docs build [options]

Options:

Option	Alias	Description	Default	Required
`--assembly-list <PATH>`	`-a`	Path to file containing assembly list		✅
`--output <PATH>`	`-o`	Output path for documentation		✅
`--type <TYPE>`	`-t`	Documentation type	`Mintlify`
`--namespace-mode <MODE>`	`-n`	Namespace organization	`File`
`--api-reference-path <PATH>`		API reference subfolder	`api-reference`

Documentation Types:

Type	Description
`Mintlify`	Mintlify-enhanced MDX with icons, navigation, and frontmatter (default)
`DocFX`	DocFX-compatible documentation format
`MkDocs`	MkDocs-compatible documentation format
`Jekyll`	Jekyll-compatible documentation format
`Hugo`	Hugo-compatible documentation format
`Generic`	Generic Markdown documentation

Namespace Modes:

File Mode (Default)
Folder Mode

Each namespace gets a single file.Structure:

docs/
├── MyNamespace.md
├── MyNamespace.SubNamespace.md
└── MyNamespace.OtherNamespace.md

Best for: Smaller projects, simpler file organization

Assembly List File: Create a text file with one assembly path per line:

assemblies.txt

bin/Release/net8.0/MyProject.Core.dll
bin/Release/net8.0/MyProject.Extensions.dll
bin/Release/net8.0/MyProject.Utilities.dll

Only assemblies with corresponding XML documentation files (.xml) will be processed. Assemblies without XML docs are skipped.

Examples:

# Generate Markdown documentation
dotnet docs build \
  --assembly-list assemblies.txt \
  --output ./docs

Complete Workflows

Quick Start Workflow

Add Documentation Project

dotnet docs add

Creates .docsproj in your solution

Build Your Projects

dotnet build --configuration Release

Generates assemblies and XML docs

Create Assembly List

echo "bin/Release/net8.0/MyProject.dll" > assemblies.txt

List assemblies to document

Generate Documentation

dotnet docs build -a assemblies.txt -o ./docs --type Mintlify

Creates documentation files

Preview Documentation

npm i mint -g
cd docs
mint dev

View at http://localhost:3000

Multi-Project Workflow

For solutions with multiple projects:

Build All Projects

dotnet build --configuration Release

Create Assembly List

assemblies.txt

ProjectA/bin/Release/net8.0/ProjectA.dll
ProjectB/bin/Release/net8.0/ProjectB.dll
ProjectC/bin/Release/net8.0/ProjectC.dll

Generate Unified Documentation

dotnet docs build -a assemblies.txt -o ./docs --type Mintlify

All assemblies merged into single documentation site

CI/CD Integration

GitHub Actions
Azure Pipelines

.github/workflows/docs.yml

name: Build Documentation

on:
  push:
    branches: [main]

jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup .NET
        uses: actions/setup-dotnet@v4
        with:
          dotnet-version: '8.0.x'

      - name: Install DotNetDocs CLI
        run: dotnet tool install --global DotNetDocs

      - name: Build Projects
        run: dotnet build --configuration Release

      - name: Generate Documentation
        run: dotnet docs build -a assemblies.txt -o ./docs --type Mintlify

      - name: Deploy to Mintlify
        run: |
          cd docs
          npx mintlify deploy

Tips and Best Practices

Ensure XML Documentation

Enable XML documentation in your .csproj files:

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>

Without XML files, assemblies are skipped during documentation generation.

Use Relative Paths

Use relative paths in your assembly list file for portability across environments:

# Good - relative paths
bin/Release/net8.0/MyProject.dll

# Avoid - absolute paths
C:\Projects\MyApp\bin\Release\net8.0\MyProject.dll

Organize Output

Choose namespace mode based on project size:

File Mode: Better for small-to-medium projects (< 50 types)
Folder Mode: Better for large projects (> 50 types)

Automate Assembly Lists

Generate assembly lists dynamically in CI/CD:

# Find all assemblies with XML docs
find bin/Release -name "*.xml" | sed 's/.xml/.dll/' > assemblies.txt

Troubleshooting

No assemblies found to process

Problem: Assembly list file is empty or paths are incorrectSolution:

Verify assembly paths in the list file
Ensure you’ve built projects in Release mode
Check that paths are relative to where you’re running the command

Assemblies skipped (no XML docs)

Problem: Assemblies don’t have corresponding XML documentation filesSolution:

Add <GenerateDocumentationFile>true</GenerateDocumentationFile> to .csproj
Rebuild projects
Verify .xml files exist next to .dll files

Solution file not found

Problem: dotnet docs add can’t find a solution fileSolution:

Run from directory containing .sln or .slnx file
Or specify solution path: dotnet docs add --solution path/to/solution.sln

Documentation generation fails

Problem: Errors during documentation buildSolution:

Check that assemblies are valid .NET assemblies
Ensure XML files match assembly structure
Review console output for specific error messages

DotNetDocs.Sdk

Use MSBuild SDK for integrated documentation builds

Pipeline Guide

Understand how documentation generation works

Mintlify Provider

Learn about Mintlify-enhanced documentation

GitHub Repository

View source code and report issues

Getting Started

Guides

Providers

Plugins

Learnings

API Reference

Commands

dotnet docs add

dotnet docs update

dotnet docs build

Complete Workflows

Quick Start Workflow

Multi-Project Workflow

CI/CD Integration

Tips and Best Practices

Troubleshooting

See Also

DotNetDocs.Sdk

Pipeline Guide

Mintlify Provider

GitHub Repository

Getting Started

Guides

Providers

Plugins

Learnings

API Reference

​Commands

​dotnet docs add

​dotnet docs update

​dotnet docs build

​Complete Workflows

​Quick Start Workflow

​Multi-Project Workflow

​CI/CD Integration

​Tips and Best Practices

​Troubleshooting

​See Also

DotNetDocs.Sdk

Pipeline Guide

Mintlify Provider

GitHub Repository

Commands

dotnet docs add

dotnet docs update

dotnet docs build

Complete Workflows

Quick Start Workflow

Multi-Project Workflow

CI/CD Integration

Tips and Best Practices

Troubleshooting

See Also