.docsproj Reference

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.2.0">
  <!-- Your configuration here -->
</Project>

Essential Properties

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.

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>

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

string

default:"api-reference"

The output directory for generated API reference documentation, relative to DocumentationRoot.

<ApiReferencePath>api</ApiReferencePath>

string

default:"conceptual"

The output directory for conceptual documentation, relative to DocumentationRoot.

<ConceptualPath>guides</ConceptualPath>

Documentation Generation

Namespace Organization

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

bool

default:"false"

When true, enables generation of conceptual documentation from XML comments.

<ConceptualDocsEnabled>true</ConceptualDocsEnabled>

bool

default:"false"

When true, shows placeholder content for types/members that don’t have XML documentation.

<ShowPlaceholders>false</ShowPlaceholders>

bool

default:"false"

When true, displays documentation statistics during build (file counts, etc.).

<ShowDocumentationStats>true</ShowDocumentationStats>

Mintlify-Specific Configuration

1.1.0+: Navigation configuration has been refactored. The <Navigation> element now uses attributes for Mode, Type, and Name. Legacy properties (MintlifyNavigationMode, MintlifyNavigationType, MintlifyNavigationName) are still supported for backward compatibility.

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>

<MintlifyTemplate>
  <Navigation Mode="Unified">
    <Pages>
      <!-- Navigation structure -->
    </Pages>
  </Navigation>
</MintlifyTemplate>

In 1.1.0 and later, use the <Navigation Mode="..."> attribute in MintlifyTemplate instead of the top-level property.

string

default:"API Reference"

The name of the unified navigation group when using MintlifyNavigationMode=Unified.

<MintlifyUnifiedGroupName>API Documentation</MintlifyUnifiedGroupName>

<!-- This is now configured via MintlifyRenderer options in code -->
<!-- or remains as a top-level property for backward compatibility -->
<MintlifyUnifiedGroupName>API Documentation</MintlifyUnifiedGroupName>

Template Configuration

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>

XML element

Inline Mintlify theme and branding configuration. This XML element allows you to configure the visual appearance and navigation structure of your Mintlify documentation.

<MintlifyTemplate>
  <Name>My Project</Name>
  <Theme>maple</Theme>
  <Colors>
    <Primary>#419AC5</Primary>
    <Light>#419AC5</Light>
    <Dark>#3CD0E2</Dark>
  </Colors>
</MintlifyTemplate>

<MintlifyTemplate>
  <Name>My Project</Name>
  <Theme>maple</Theme>
  <Colors>
    <Primary>#419AC5</Primary>
    <Light>#419AC5</Light>
    <Dark>#3CD0E2</Dark>
  </Colors>
  <Navigation Mode="Unified" Type="Tabs" Name="My Project">
    <Pages>
      <!-- Navigation structure -->
    </Pages>
  </Navigation>
</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
<Navigation> - (1.1.0+) Navigation configuration with attributes:
- Mode - Navigation organization mode: Unified (default) or Separated
- Type - Integration type: Pages (default), Tabs, or Products
- Name - Custom display name for tabs/products (optional, defaults to project name)

The <Navigation> element and its attributes are only available in 1.1.0 and later. For 1.0.x, use the legacy MintlifyNavigationMode property.

Documentation References

The <DocumentationReference> item allows you to combine multiple documentation projects into a single unified site. This is useful for organizations with multiple libraries or products that should share a common documentation portal.

MSBuild Item

References another .docsproj file to include in your documentation output.Attributes:

Attribute	Required	Description
`Include`	Yes	Path to the referenced `.docsproj` file
`DestinationPath`	Yes	URL-friendly subfolder name for the copied content
`IntegrationType`	No	How to integrate navigation: `Tabs` or `Products` (default: `Tabs`)
`Name`	No	Display name for the navigation tab/product (defaults to project name)

<ItemGroup>
  <DocumentationReference
    Include="..\MyLib\MyLib.Docs.docsproj"
    DestinationPath="my-lib"
    IntegrationType="Tabs"
    Name="My Library" />
</ItemGroup>

How References Are Processed

When you include a DocumentationReference, the SDK:

Copies content files to /{DestinationPath}/ in your output
Relocates shared resources (images/, snippets/) to central locations with namespacing
Rewrites internal paths in MDX files to reference the relocated resources
Merges navigation into your docs.json as a Tab or Product

For Mintlify documentation, see Collections for detailed information about how path rewriting and resource relocation work.

Multiple References Example

<Project Sdk="DotNetDocs.Sdk/1.2.0">
  <PropertyGroup>
    <DocumentationType>Mintlify</DocumentationType>
    <MintlifyTemplate>
      <Name>My Platform</Name>
      <Navigation Mode="Unified" Type="Tabs" Name="Platform">
        <Pages>
          <Groups>
            <Group Name="Overview" Icon="house">
              <Pages>index;quickstart</Pages>
            </Group>
          </Groups>
        </Pages>
      </Navigation>
    </MintlifyTemplate>
  </PropertyGroup>

  <ItemGroup>
    <DocumentationReference
      Include="..\LibraryA\LibraryA.Docs.docsproj"
      DestinationPath="library-a"
      IntegrationType="Tabs"
      Name="Library A" />

    <DocumentationReference
      Include="..\LibraryB\LibraryB.Docs.docsproj"
      DestinationPath="library-b"
      IntegrationType="Tabs"
      Name="Library B" />
  </ItemGroup>
</Project>

Advanced Configuration

Build Behavior

bool

default:"false"

Controls whether the documentation project produces a NuGet package. Generally should remain false for documentation projects.

<IsPackable>false</IsPackable>

bool

default:"false"

Controls whether the documentation project can be published. Generally should remain false for documentation projects.

<IsPublishable>false</IsPublishable>

bool

default:"false"

Controls whether a NuGet package is generated during build. Generally should remain false for documentation projects.

<GeneratePackageOnBuild>false</GeneratePackageOnBuild>

Project Discovery

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.2.0">

  <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 -->
    <MintlifyTemplate>
      <Name>My Amazing Library</Name>
      <Theme>maple</Theme>
      <Colors>
        <Primary>#419AC5</Primary>
        <Light>#419AC5</Light>
        <Dark>#3CD0E2</Dark>
      </Colors>
      <Navigation Mode="Unified" Type="Tabs" Name="API Reference">
        <Pages>
          <!-- Your navigation structure here -->
        </Pages>
      </Navigation>
    </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

Getting Started

Guides

Providers

Plugins

Learnings

API Reference

Overview

Basic Configuration

SDK Reference

Essential Properties

Output Configuration

Path Settings

Documentation Generation

Namespace Organization

Content Options

Mintlify-Specific Configuration

Navigation Settings

Template Configuration

Documentation References

How References Are Processed

Multiple References Example

Advanced Configuration

Build Behavior

Project Discovery

Complete Example

Environment Variables

Auto-Included Files

Common Files (All Types)

Mintlify-Specific

DocFX-Specific

MkDocs-Specific

Jekyll-Specific

Hugo-Specific

Build Targets

Next Steps

Pipeline Overview

Conceptual Docs

​Overview

​Basic Configuration

​SDK Reference

​Essential Properties

​Output Configuration

​Path Settings

​Documentation Generation

​Namespace Organization

​Content Options

​Mintlify-Specific Configuration

​Navigation Settings

​Template Configuration

​Documentation References

​How References Are Processed

​Multiple References Example

​Advanced Configuration

​Build Behavior

​Project Discovery

​Complete Example

​Environment Variables

​Auto-Included Files

​Common Files (All Types)

​Mintlify-Specific

​DocFX-Specific

​MkDocs-Specific

​Jekyll-Specific

​Hugo-Specific

​Build Targets

​Next Steps

Pipeline Overview

Conceptual Docs

Overview

Basic Configuration

SDK Reference

Essential Properties

Output Configuration

Path Settings

Documentation Generation

Namespace Organization

Content Options

Mintlify-Specific Configuration

Navigation Settings

Template Configuration

Documentation References

How References Are Processed

Multiple References Example

Advanced Configuration

Build Behavior

Project Discovery

Complete Example

Environment Variables

Auto-Included Files

Common Files (All Types)

Mintlify-Specific

DocFX-Specific

MkDocs-Specific

Jekyll-Specific

Hugo-Specific

Build Targets

Next Steps