Skip to main content

​
Overview

The .docsproj file is the heart of your DotNetDocs project. It uses the DotNetDocs.Sdk MSBuild SDK to configure how your documentation is generated, organized, and rendered. This guide covers all available MSBuild properties you can configure.

​
Basic Configuration

​
SDK Reference

Every .docsproj file must reference the DotNetDocs.Sdk: 
<Project Sdk="DotNetDocs.Sdk/1.0.1">
  <!-- Your configuration here -->
</Project>

​
Essential Properties

​
DocumentationType
string
default:"Auto-detected"
The type of documentation system you’re using. Supported values:
  • Mintlify - Mintlify documentation (auto-detected from docs.json)
  • DocFX - DocFX documentation (auto-detected from docfx.json)
  • MkDocs - MkDocs documentation (auto-detected from mkdocs.yml)
  • Jekyll - Jekyll documentation (auto-detected from _config.yml)
  • Hugo - Hugo documentation (auto-detected from hugo.toml)
  • Generic - Generic markdown documentation (default fallback)
The SDK automatically detects your documentation type based on configuration files in your DocumentationRoot.
​
DocumentationRoot
string
default:"$(MSBuildProjectDirectory)"
The root directory containing your documentation files. This allows the .docsproj file to be in a different location than your actual documentation files.
<DocumentationRoot>$(MSBuildProjectDirectory)\..\docs\</DocumentationRoot>
​
GenerateDocumentation
bool
default:"false"
When true, automatically generates API documentation from all packable projects in the solution during build.
<GenerateDocumentation>true</GenerateDocumentation>

​
Output Configuration

​
Path Settings

​
ApiReferencePath
string
default:"api-reference"
The output directory for generated API reference documentation, relative to DocumentationRoot.
<ApiReferencePath>api</ApiReferencePath>
​
ConceptualPath
string
default:"conceptual"
The output directory for conceptual documentation, relative to DocumentationRoot.
<ConceptualPath>guides</ConceptualPath>

​
Documentation Generation

​
Namespace Organization

​
NamespaceMode
string
default:"Folder"
Controls how namespaces are organized in generated documentation:
  • Folder - Each namespace gets its own folder
  • File - All namespaces in a single file
  • Flat - Flat file structure without namespace hierarchy
<NamespaceMode>Folder</NamespaceMode>

​
Content Options

​
ConceptualDocsEnabled
bool
default:"false"
When true, enables generation of conceptual documentation from XML comments.
<ConceptualDocsEnabled>true</ConceptualDocsEnabled>
​
ShowPlaceholders
bool
default:"false"
When true, shows placeholder content for types/members that don’t have XML documentation.
<ShowPlaceholders>false</ShowPlaceholders>
​
ShowDocumentationStats
bool
default:"false"
When true, displays documentation statistics during build (file counts, etc.).
<ShowDocumentationStats>true</ShowDocumentationStats>

​
Mintlify-Specific Configuration

​
MintlifyNavigationMode
string
default:"Unified"
Controls how API reference navigation is organized in Mintlify:
  • Unified - Single unified navigation group
  • Separated - Separate navigation groups per namespace/assembly
Only applies when DocumentationType is Mintlify.
<MintlifyNavigationMode>Unified</MintlifyNavigationMode>
​
MintlifyUnifiedGroupName
string
default:"API Reference"
The name of the unified navigation group when using MintlifyNavigationMode=Unified.
<MintlifyUnifiedGroupName>API Documentation</MintlifyUnifiedGroupName>

​
Template Configuration

​
DocsJsonTemplatePath
string
default:"Auto-detected"
Path to an external docs.json template file. Auto-detected if docs-template.json exists in DocumentationRoot.
<DocsJsonTemplatePath>$(DocumentationRoot)templates\docs-template.json</DocsJsonTemplatePath>
​
MintlifyTemplate
XML element
Inline Mintlify theme and branding configuration. This XML element allows you to configure the visual appearance of your Mintlify documentation.
<MintlifyTemplate>
  <Name>My Project</Name>
  <Theme>maple</Theme>
  <Colors>
    <Primary>#419AC5</Primary>
    <Light>#419AC5</Light>
    <Dark>#3CD0E2</Dark>
  </Colors>
</MintlifyTemplate>
Supported child elements:
  • <Name> - Project name displayed in documentation
  • <Theme> - Mintlify theme name (e.g., maple, quill, venus)
  • <Colors> - Color scheme configuration
    • <Primary> - Primary brand color
    • <Light> - Light mode accent color
    • <Dark> - Dark mode accent color

​
Advanced Configuration

​
Build Behavior

​
IsPackable
bool
default:"false"
Controls whether the documentation project produces a NuGet package. Generally should remain false for documentation projects.
<IsPackable>false</IsPackable>
​
IsPublishable
bool
default:"false"
Controls whether the documentation project can be published. Generally should remain false for documentation projects.
<IsPublishable>false</IsPublishable>
​
GeneratePackageOnBuild
bool
default:"false"
Controls whether a NuGet package is generated during build. Generally should remain false for documentation projects.
<GeneratePackageOnBuild>false</GeneratePackageOnBuild>

​
Project Discovery

​
ExcludePatterns
string
Semicolon-separated list of glob patterns for excluding projects from documentation generation.
<ExcludePatterns>**/*.Tests.csproj;**/*Benchmark*.csproj</ExcludePatterns>

​
Complete Example

Here’s a complete .docsproj file demonstrating common configuration: 
<Project Sdk="DotNetDocs.Sdk/1.0.1">

  <PropertyGroup>
    <!-- Documentation Type -->
    <DocumentationType>Mintlify</DocumentationType>

    <!-- Generation Settings -->
    <GenerateDocumentation>true</GenerateDocumentation>
    <NamespaceMode>Folder</NamespaceMode>
    <ShowDocumentationStats>true</ShowDocumentationStats>

    <!-- Content Options -->
    <ConceptualDocsEnabled>true</ConceptualDocsEnabled>
    <ShowPlaceholders>false</ShowPlaceholders>

    <!-- Mintlify Configuration -->
    <MintlifyNavigationMode>Unified</MintlifyNavigationMode>
    <MintlifyTemplate>
      <Name>My Amazing Library</Name>
      <Theme>maple</Theme>
      <Colors>
        <Primary>#419AC5</Primary>
        <Light>#419AC5</Light>
        <Dark>#3CD0E2</Dark>
      </Colors>
    </MintlifyTemplate>
  </PropertyGroup>

</Project>

​
Environment Variables

The SDK also respects standard MSBuild environment variables:
  • $(Configuration) - Build configuration (Debug/Release)
  • $(SolutionName) - Name of the solution
  • $(SolutionFileName) - Full filename of the solution file
  • $(MSBuildProjectDirectory) - Directory containing the .docsproj file

​
Auto-Included Files

The SDK automatically includes files based on your DocumentationType. You don’t need to manually specify <None Include="..."> for these patterns:

​
Common Files (All Types)

  • README.md
  • LICENSE*
  • CHANGELOG*
  • **/*.txt
  • All image files (png, jpg, gif, svg, webp, ico, pdf)
  • All font files (woff, ttf, otf, eot)
  • All web assets (css, scss, js, ts)

​
Mintlify-Specific

  • docs.json
  • **/*.md, **/*.mdx, **/*.mdz
  • api-reference/**/*
  • conceptual/**/*
  • overrides/**/*
  • guides/**/*
  • images/**/*
  • snippets/**/*
  • favicon.*

​
DocFX-Specific

  • docfx.json
  • toc.yml, toc.yaml
  • **/*.yml, **/*.yaml
  • articles/**/*
  • api/**/*
  • templates/**/*

​
MkDocs-Specific

  • mkdocs.yml
  • docs/**/*.md
  • requirements.txt
  • overrides/**/*
  • theme/**/*

​
Jekyll-Specific

  • _config.yml, _config.yaml
  • _posts/**/*
  • _layouts/**/*
  • _includes/**/*
  • _sass/**/*
  • _data/**/*
  • assets/**/*
  • Gemfile*

​
Hugo-Specific

  • hugo.toml, hugo.yaml, hugo.json
  • config.*
  • content/**/*
  • layouts/**/*
  • static/**/*
  • themes/**/*
  • archetypes/**/*
  • data/**/*
  • i18n/**/*

​
Build Targets

You can invoke specific documentation tasks using MSBuild targets: 
# Show available options and current configuration
dotnet build -t:DocumentationHelp

# Show documentation statistics
dotnet build -t:DocumentationStats

# Generate documentation explicitly
dotnet build -t:GenerateDocumentation

​
Next Steps

Pipeline Overview

Learn how the documentation pipeline works

Conceptual Docs

Add conceptual documentation to your project