DotNetDocs.Sdk

DotNetDocs.Sdk

The MSBuild SDK for documentation projects (.docsproj) that provides a clean way to include documentation in .NET solutions.

Features

• 🚀 Zero Configuration - Works out of the box for common documentation types
• 📁 Clean Folders - No bin/obj folders cluttering your documentation directories
• 🔍 Auto-Detection - Automatically detects documentation type (Mintlify, DocFX, MkDocs, Jekyll, Hugo)
• 📝 Smart Includes - Automatically includes relevant files based on documentation type
• 🛠️ Integration - Optional build targets for linting, preview, and deployment
• 🎯 Visual Studio - Full IntelliSense and editing support in Visual Studio

Quick Start

1. Create a .docsproj file

<Project Sdk="DotNetDocs.Sdk/1.0.1">
  <!-- That's it! Everything is configured automatically -->
</Project>

2. Add to solution

For .slnx files:

<Project Path="docs/MyProject.Docs.docsproj" Type="C#" />

For .sln files:

Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "MyProject.Docs", "docs\MyProject.Docs.docsproj", "{GUID}"
EndProject

Documentation Type Detection

The SDK automatically detects your documentation type based on configuration files:

Configuration Options

Basic Options

<Project Sdk="DotNetDocs.Sdk/1.0.1">
  <PropertyGroup>
    <!-- Override auto-detected documentation type -->
    <DocumentationType>Mintlify</DocumentationType>

    <!-- Enable build-time features -->
    <GenerateMintlifyDocs>true</GenerateMintlifyDocs>
    <LintMarkdown>true</LintMarkdown>
    <ShowDocumentationStats>true</ShowDocumentationStats>
  </PropertyGroup>
</Project>

Advanced Options

<Project Sdk="DotNetDocs.Sdk/1.0.1">
  <PropertyGroup>
    <!-- Preview and deployment -->
    <PreviewDocumentation>true</PreviewDocumentation>
    <DeployDocumentation>true</DeployDocumentation>
    
    <!-- Quality assurance -->
    <ValidateLinks>true</ValidateLinks>
    <GeneratePdf>true</GeneratePdf>
  </PropertyGroup>
</Project>

Separate Documentation Location

If your .docsproj file is in a different location than your documentation files (e.g., project in src/ but docs in docs/), use the DocumentationRoot property:

<Project Sdk="DotNetDocs.Sdk/1.0.1">
  <PropertyGroup>
    <!-- Point to where your documentation files actually live -->
    <DocumentationRoot>$(MSBuildThisFileDirectory)..\..\docs\</DocumentationRoot>
    
    <!-- All features work with the specified root -->
    <GenerateMintlifyDocs>true</GenerateMintlifyDocs>
    <ShowDocumentationStats>true</ShowDocumentationStats>
  </PropertyGroup>
</Project>

This is particularly useful when you want to:

• Keep your .docsproj file with other project files in the src/ folder
• Have all documentation content in a separate docs/ folder at the repository root
• Maintain a clean separation between code and documentation

Available Build Targets

DotNetDocs Integration

The SDK automatically generates documentation when GenerateMintlifyDocs is enabled. Documentation is built from your project's assemblies and XML documentation files.

Usage Examples

# Show help and current configuration
dotnet build -t:DocumentationHelp

# Show documentation statistics  
dotnet build -t:DocumentationStats

# Generate Mintlify docs manually
dotnet build -t:GenerateMintlifyDocs

# Start preview server
dotnet build -t:PreviewDocumentation

Integration Examples

Mintlify Project

<Project Sdk="DotNetDocs.Sdk/1.0.1">
  <PropertyGroup>
    <!-- Auto-generate on build -->
    <GenerateMintlifyDocs>true</GenerateMintlifyDocs>
    
    <!-- Quality checks -->
    <LintMarkdown>true</LintMarkdown>
    <ShowDocumentationStats>true</ShowDocumentationStats>
  </PropertyGroup>
</Project>

Multi-Format Project

<Project Sdk="DotNetDocs.Sdk/1.0.1">
  <PropertyGroup>
    <!-- Override detection -->
    <DocumentationType>Generic</DocumentationType>
  </PropertyGroup>

  <!-- Custom file includes -->
  <ItemGroup>
    <None Include="custom-docs/**/*.rst" />
    <None Include="api-specs/**/*.yaml" />
  </ItemGroup>
</Project>

CI/CD Integration

# GitHub Actions example
- name: Build Documentation
  run: dotnet build docs/MyProject.Docs.docsproj -p:DeployDocumentation=true

Benefits Over Manual Configuration

Requirements

• .NET SDK 8.0 or later
• MSBuild 16.0 or later
• Visual Studio 2019 or later (for full IDE support)

See Also

• Full Documentation - Complete guides and examples
• DotNetDocs CLI - Get up and running fast with our easy CLI
• DotNetDocs.Core - Core documentation engine
• DotNetDocs.Mintlify - Enhanced Mintlify.com support

License

MIT License - see LICENSE for details.