DotNetDocs.Sdk 1.0.0-preview.31

DotNetDocs.Sdk

<a href="https://dotnetdocs.com"> <img src="https://raw.githubusercontent.com/CloudNimble/DotNetDocs/refs/heads/dev/src/CloudNimble.DotNetDocs.Docs/images/logos/dotnetdocs.light.svg" alt="DotNetDocs Logo" width="450" /> </a>

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.0">
  
</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.0">
  <PropertyGroup>
    
    <DocumentationType>Mintlify</DocumentationType>

    
    <GenerateMintlifyDocs>true</GenerateMintlifyDocs>
    <LintMarkdown>true</LintMarkdown>
    <ShowDocumentationStats>true</ShowDocumentationStats>
  </PropertyGroup>
</Project>

Advanced Options

<Project Sdk="DotNetDocs.Sdk/1.0.0">
  <PropertyGroup>
    
    <PreviewDocumentation>true</PreviewDocumentation>
    <DeployDocumentation>true</DeployDocumentation>
    
    
    <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.0">
  <PropertyGroup>
    
    <DocumentationRoot>$(MSBuildThisFileDirectory)..\..\docs\</DocumentationRoot>
    
    
    <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.0">
  <PropertyGroup>
    
    <GenerateMintlifyDocs>true</GenerateMintlifyDocs>
    
    
    <LintMarkdown>true</LintMarkdown>
    <ShowDocumentationStats>true</ShowDocumentationStats>
  </PropertyGroup>
</Project>

Multi-Format Project

<Project Sdk="DotNetDocs.Sdk/1.0.0">
  <PropertyGroup>
    
    <DocumentationType>Generic</DocumentationType>
  </PropertyGroup>

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