> ## Documentation Index
> Fetch the complete documentation index at: https://dotnetdocs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# .docsproj Reference

> Configure your documentation project with MSBuild properties

## 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:

<CodeGroup>
  ```xml Current (1.2.0) theme={"dark"}
  <Project Sdk="DotNetDocs.Sdk/1.2.0">
    <!-- Your configuration here -->
  </Project>
  ```
</CodeGroup>

### Essential Properties

<ParamField path="DocumentationType" type="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`.
</ParamField>

<ParamField path="DocumentationRoot" type="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.

  ```xml theme={"dark"}
  <DocumentationRoot>$(MSBuildProjectDirectory)\..\docs\</DocumentationRoot>
  ```
</ParamField>

<ParamField path="GenerateDocumentation" type="bool" default="false">
  When `true`, automatically generates API documentation from all packable projects in the solution during build.

  ```xml theme={"dark"}
  <GenerateDocumentation>true</GenerateDocumentation>
  ```
</ParamField>

## Output Configuration

### Path Settings

<ParamField path="ApiReferencePath" type="string" default="api-reference">
  The output directory for generated API reference documentation, relative to `DocumentationRoot`.

  ```xml theme={"dark"}
  <ApiReferencePath>api</ApiReferencePath>
  ```
</ParamField>

<ParamField path="ConceptualPath" type="string" default="conceptual">
  The output directory for conceptual documentation, relative to `DocumentationRoot`.

  ```xml theme={"dark"}
  <ConceptualPath>guides</ConceptualPath>
  ```
</ParamField>

## Documentation Generation

### Namespace Organization

<ParamField path="NamespaceMode" type="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

  ```xml theme={"dark"}
  <NamespaceMode>Folder</NamespaceMode>
  ```
</ParamField>

### Content Options

<ParamField path="ConceptualDocsEnabled" type="bool" default="false">
  When `true`, enables generation of conceptual documentation from XML comments.

  ```xml theme={"dark"}
  <ConceptualDocsEnabled>true</ConceptualDocsEnabled>
  ```
</ParamField>

<ParamField path="ShowPlaceholders" type="bool" default="false">
  When `true`, shows placeholder content for types/members that don't have XML documentation.

  ```xml theme={"dark"}
  <ShowPlaceholders>false</ShowPlaceholders>
  ```
</ParamField>

<ParamField path="ShowDocumentationStats" type="bool" default="false">
  When `true`, displays documentation statistics during build (file counts, etc.).

  ```xml theme={"dark"}
  <ShowDocumentationStats>true</ShowDocumentationStats>
  ```
</ParamField>

## Mintlify-Specific Configuration

### Navigation Settings

<Note>
  **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.
</Note>

<ParamField path="MintlifyNavigationMode" type="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`.

  <CodeGroup>
    ```xml Current (1.0.x) theme={"dark"}
    <MintlifyNavigationMode>Unified</MintlifyNavigationMode>
    ```

    ```xml 1.1.0+ theme={"dark"}
    <MintlifyTemplate>
      <Navigation Mode="Unified">
        <Pages>
          <!-- Navigation structure -->
        </Pages>
      </Navigation>
    </MintlifyTemplate>
    ```
  </CodeGroup>

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

<ParamField path="MintlifyUnifiedGroupName" type="string" default="API Reference">
  The name of the unified navigation group when using `MintlifyNavigationMode=Unified`.

  <CodeGroup>
    ```xml Current (1.0.x) theme={"dark"}
    <MintlifyUnifiedGroupName>API Documentation</MintlifyUnifiedGroupName>
    ```

    ```xml 1.1.0+ theme={"dark"}
    <!-- This is now configured via MintlifyRenderer options in code -->
    <!-- or remains as a top-level property for backward compatibility -->
    <MintlifyUnifiedGroupName>API Documentation</MintlifyUnifiedGroupName>
    ```
  </CodeGroup>
</ParamField>

### Template Configuration

<ParamField path="DocsJsonTemplatePath" type="string" default="Auto-detected">
  Path to an external `docs.json` template file. Auto-detected if `docs-template.json` exists in `DocumentationRoot`.

  ```xml theme={"dark"}
  <DocsJsonTemplatePath>$(DocumentationRoot)templates\docs-template.json</DocsJsonTemplatePath>
  ```
</ParamField>

<ParamField path="MintlifyTemplate" type="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.

  <CodeGroup>
    ```xml Current (1.0.x) theme={"dark"}
    <MintlifyTemplate>
      <Name>My Project</Name>
      <Theme>maple</Theme>
      <Colors>
        <Primary>#419AC5</Primary>
        <Light>#419AC5</Light>
        <Dark>#3CD0E2</Dark>
      </Colors>
    </MintlifyTemplate>
    ```

    ```xml 1.1.0+ theme={"dark"}
    <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>
    ```
  </CodeGroup>

  **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)

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

## 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.

<ParamField path="DocumentationReference" type="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) |

  ```xml theme={"dark"}
  <ItemGroup>
    <DocumentationReference
      Include="..\MyLib\MyLib.Docs.docsproj"
      DestinationPath="my-lib"
      IntegrationType="Tabs"
      Name="My Library" />
  </ItemGroup>
  ```
</ParamField>

### How References Are Processed

When you include a `DocumentationReference`, the SDK:

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

<Info>
  For Mintlify documentation, see [Collections](/providers/mintlify/collections) for detailed information about how path rewriting and resource relocation work.
</Info>

### Multiple References Example

```xml theme={"dark"}
<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

<ParamField path="IsPackable" type="bool" default="false">
  Controls whether the documentation project produces a NuGet package. Generally should remain `false` for documentation projects.

  ```xml theme={"dark"}
  <IsPackable>false</IsPackable>
  ```
</ParamField>

<ParamField path="IsPublishable" type="bool" default="false">
  Controls whether the documentation project can be published. Generally should remain `false` for documentation projects.

  ```xml theme={"dark"}
  <IsPublishable>false</IsPublishable>
  ```
</ParamField>

<ParamField path="GeneratePackageOnBuild" type="bool" default="false">
  Controls whether a NuGet package is generated during build. Generally should remain `false` for documentation projects.

  ```xml theme={"dark"}
  <GeneratePackageOnBuild>false</GeneratePackageOnBuild>
  ```
</ParamField>

### Project Discovery

<ParamField path="ExcludePatterns" type="string">
  Semicolon-separated list of glob patterns for excluding projects from documentation generation.

  ```xml theme={"dark"}
  <ExcludePatterns>**/*.Tests.csproj;**/*Benchmark*.csproj</ExcludePatterns>
  ```
</ParamField>

## Complete Example

Here's a complete `.docsproj` file demonstrating common configuration:

<CodeGroup>
  ```xml Current (1.2.0) theme={"dark"}
  <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>
  ```
</CodeGroup>

## 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:

```bash theme={"dark"}
# 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

<CardGroup cols={2}>
  <Card title="Pipeline Overview" icon="faucet-drip" href="/guides/pipeline">
    Learn how the documentation pipeline works
  </Card>

  <Card title="Conceptual Docs" icon="book" href="/guides/conceptual-docs">
    Add conceptual documentation to your project
  </Card>
</CardGroup>