DotNetDocs.Sdk 1.0.0-preview.5

CloudNimble.DotNetDocs.Sdk

MSBuild SDK for documentation projects (.docsproj) - 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="{9A19103F-16F7-4668-BE54-9A1E7A4F7556}" projectTypeName="SharedProject" />

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>
    
    <KeepLocalOutput>true</KeepLocalOutput>
    
    
    <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

EasyAF.Tools Integration

The SDK automatically checks for and attempts to install CloudNimble.EasyAF.Tools when using Mintlify features. If automatic installation fails, you'll see instructions to visit this GitHub issue and leave a reaction emoji to get access to the tools.

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>
    
    
    <KeepLocalOutput>true</KeepLocalOutput>
  </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 6.0 or later
• MSBuild 16.0 or later
• Visual Studio 2019 or later (for full IDE support)

Contributing

This SDK is part of the CloudNimble EasyAF framework. Contributions welcome!

License

MIT License - see LICENSE for details.