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

# Why DotNetDocs?

> by Robert McLaws - Former Microsoft MVP and CEO of CloudNimble

## Introduction

A .NET influencer once tweeted "When I ask myself 'What would have the most impact today?' I sit down and write documentation."

That has always stuck with me.

.NET has never had a truly fantastic documentation story. For a while, I had hoped DocFX would be the answer, but that didn't really pan out.

AI changed everything.

In the last 18 months, documentation has gone from a "nice to have" to a requirement for AI coding tools. If the tool doesn't understand the code, it will
generate garbage. Every. Single. Time.

Which brought me back to that quote.

A full decade since that tweet, how are .NET developers to follow that advice?

GitHub Copilot can fill in your XML doc comments, but there's been no truly fantastic place for them to be seen and understood.

With Claude at my fingertips, it was time to finally build the solution the .NET Ecosystem always deserved, so every .NET developer can be a better Context
Engineer.

So try it out. Let us know what still needs work. Open up some issues and help us make this ecosystem we love that much better.

And write some great documentation.

-Robert, 13 October 2025

***

## Design Tenets

* It must be the simplest, most intuitive documenation system ever made
* It must make Documentation a first-class citizen in Visual Studio and VSCode
  * This means it should be able to edit content targeting any documentation platform
* It must be built for .NET 10 first and designed for the next 25 years of .NET development
* It must support standard formats but allow for premium experiences
* It MUST support weaving long-lived and dynamically-generated content together

## What Makes DotNetDocs Special

<CardGroup cols={4}>
  <Card title="Multiple Output Formats" icon="palette">
    Generate beautiful Mintlify sites, clean Markdown, structured JSON, or YAML - all from your existing XML documentation
  </Card>

  <Card title="MSBuild Integration" icon="gear">
    Seamlessly integrate into your build process with MSBuild tasks and .NET CLI tools
  </Card>

  <Card title="Flexible Architecture" icon="cubes">
    Modular design supports custom renderers, transformers, and extensibility patterns
  </Card>

  <Card title="Developer-First" icon="code">
    Zero configuration required - works out of the box with sensible defaults and powerful customization
  </Card>
</CardGroup>

## Supported Output Formats

### Traditional Formats

* **Markdown** - Clean, readable documentation for GitHub, GitLab, or any markdown processor
* **JSON** - Structured data for custom integrations and tooling
* **YAML** - Configuration-friendly format for documentation pipelines

### Mintlify Integration

Create stunning documentation sites with Mintlify's modern design system:

* **Interactive Navigation** - Automatically generated from your namespace structure
* **Code Syntax Highlighting** - Beautiful rendering of your C# signatures and examples
* **Search Integration** - Built-in search across all your API documentation
* **Responsive Design** - Perfect on desktop, tablet, and mobile devices

## Customization Options

### File Organization Modes

<Tabs>
  <Tab title="Folder Mode">
    ```
    📁 docs/
    ├── 📁 MyNamespace/
    │   ├── 📄 index.mdx
    │   ├── 📄 MyClass.mdx
    │   └── 📁 SubNamespace/
    │       └── 📄 AnotherClass.mdx
    └── 📄 index.mdx
    ```

    Mirrors your namespace structure as folders
  </Tab>

  <Tab title="File Mode">
    ```
    📁 docs/
    ├── 📄 index.mdx
    ├── 📄 MyNamespace.MyClass.mdx
    ├── 📄 MyNamespace.SubNamespace.AnotherClass.mdx
    └── 📄 MyNamespace.SubNamespace.mdx
    ```

    Flat structure with namespace prefixes
  </Tab>
</Tabs>

### Mintlify Themes & Branding

* **Custom Colors** - Match your brand identity
* **Logo Integration** - Light and dark mode logo support
* **Icon Customization** - Rich icon library for types and members
* **Navigation Control** - Unified or assembly-grouped organization

## Advanced Features

### Smart Content Discovery

DotNetDocs automatically discovers and integrates:

* Existing MDX files in your documentation folder
* Custom navigation structures via `navigation.json`
* Conceptual documentation alongside API references
* Asset files and resources

### Extensible Architecture

```csharp theme={"dark"}
// Custom renderer example
services.AddDotNetDocsPipeline(pipeline =>
{
    pipeline.UseCustomRenderer<MyRenderer>()
           .AddTransformer<MyTransformer>()
           .ConfigureContext(ctx => { /* ... */ });
});
```