> ## Documentation Index
> Fetch the complete documentation index at: https://dotnetdocs.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Mintlify-Enhanced Docs
> Transform your .NET XML documentation into beautiful, AI-ready Mintlify documentation sites with smart navigation, context-aware icons, and rich MDX features
Auto-generated frontmatter with icons, tags, SEO metadata, and keywords for every API page
Automatic docs.json generation with hierarchical namespace organization and flexible navigation modes
50+ FontAwesome icons automatically assigned based on type characteristics and naming patterns
Multi-project documentation with intelligent path rewriting and resource relocation
Programmatically create, validate, and manage Mintlify docs.json configurations in C#
React components, external script loading, hydration fixes, and custom landing page patterns
## Overview
The DotNetDocs Mintlify provider transforms your .NET XML documentation comments into production-ready Mintlify documentation sites. Built specifically for .NET developers, it generates MDX files with comprehensive frontmatter, organizes your API into intuitive navigation structures, and applies context-aware icons to make your documentation visually scannable.
The Mintlify provider is the most feature-rich renderer in DotNetDocs, with built-in support for AI discoverability, SEO optimization, and rich interactive components.
## Key Features
### MDX Generation with Rich Frontmatter
Every generated MDX file includes comprehensive frontmatter:
* **Title & Description**: SEO-optimized 160-character descriptions for every API member
* **Icons**: Context-aware FontAwesome icons based on type characteristics
* **Tags**: Automatic categorization (class, interface, method, property, etc.)
* **Keywords**: Extracted from XML documentation for enhanced searchability
* **Mode**: Wide layout for types, standard for members
* **OpenGraph Metadata**: Ready for social media sharing
```mdx Example Class Frontmatter theme={"dark"}
---
title: PaymentProcessor
description: Processes payment transactions with support for multiple payment gateways, automatic retry logic, and comprehensive audit logging
icon: credit-card
tags: [class, public]
mode: wide
keywords: payment, transaction, gateway, processing
---
```
```mdx Example Method Frontmatter theme={"dark"}
---
title: ProcessPaymentAsync
description: Asynchronously processes a payment transaction through the configured gateway with automatic retry on transient failures
icon: bolt
tags: [method, public, async]
keywords: payment, async, transaction, process
---
```
### Hierarchical Navigation Generation
The Mintlify provider generates `docs.json` navigation files that organize your API documentation into logical hierarchies. Choose between two navigation modes:
Creates a single navigation tree with all namespaces organized hierarchically under one group.
```json theme={"dark"}
{
"group": "API Reference",
"pages": [
{
"group": "CloudNimble.DotNetDocs",
"pages": [
{
"group": "Core",
"pages": ["api-reference/CloudNimble/DotNetDocs/Core/DocumentationManager"]
}
]
}
]
}
```
Creates separate navigation groups for each assembly, ideal for multi-project solutions.
```json theme={"dark"}
[
{
"group": "MyProject.Core",
"pages": ["api-reference/MyProject/Core/..."]
},
{
"group": "MyProject.Extensions",
"pages": ["api-reference/MyProject/Extensions/..."]
}
]
```
### 50+ Context-Aware Icons
Icons are automatically assigned based on type characteristics, member types, and naming patterns:
* **Type-based**: Classes get `cube`, interfaces get `layer-group`, enums get `list-ol`
* **Pattern-based**: Managers get `gears`, services get `server`, repositories get `database`
* **Member-based**: Methods get `function`, properties get `sliders`, events get `bolt`
* **Modifier-based**: Static members get `s`, abstract types get `shapes`
See the [complete icon reference](#icon-reference) below for all available icons.
### Flexible Output Modes
Control how namespaces are organized in the file system:
* **File Mode (Default)**: Each namespace gets a single MDX file with all members
* **Folder Mode**: Each namespace becomes a folder with separate files per type
```plaintext File Mode Structure theme={"dark"}
api-reference/
MyNamespace.mdx
MyNamespace.SubNamespace.mdx
```
```plaintext Folder Mode Structure theme={"dark"}
api-reference/
MyNamespace/
index.mdx
MyClass.mdx
MyInterface.mdx
SubNamespace/
index.mdx
AnotherClass.mdx
```
### DocsJson Template Customization
Customize the generated `docs.json` configuration by providing a template with pre-configured settings:
* Set global appearance, colors, and theme
* Configure integrations (Google Analytics, etc.)
* Define custom logos and favicons
* Pre-populate navigation structure
* Control navigation type (Pages, Tabs, or Products)
```csharp theme={"dark"}
services.AddDotNetDocsMintlify(options =>
{
options.Template = new DocsJsonConfig
{
Name = "My API",
Theme = "quill",
NavigationType = "Tabs", // NEW: Control root nav placement
NavigationName = "My API Reference", // NEW: Custom name for tab/product
Colors = new ColorsConfig
{
Primary = "#007ACC",
Light = "#50A3D0",
Dark = "#004B87"
},
Integrations = new IntegrationsConfig
{
Ga4 = new GoogleAnalytics4Config { MeasurementId = "G-XXXXXXXXXX" }
}
};
options.IncludeIcons = true;
options.GenerateDocsJson = true;
});
```
Set `NavigationType` to control whether the root project appears in main navigation (`Pages`), as a top-level tab (`Tabs`), or in the products section (`Products`). This is particularly useful for multi-project documentation collections.
## Getting Started
Install the `CloudNimble.DotNetDocs.Mintlify` package:
```bash theme={"dark"}
dotnet add package CloudNimble.DotNetDocs.Mintlify
```
Register the Mintlify renderer in your documentation pipeline:
```csharp Default Configuration theme={"dark"}
var builder = new DotNetDocsBuilder()
.AddDefaultPipeline()
.AddMintlifyRenderer();
var result = await builder.BuildAsync();
```
```csharp Custom Configuration theme={"dark"}
var builder = new DotNetDocsBuilder()
.AddDefaultPipeline()
.AddMintlifyRenderer(options =>
{
options.NavigationMode = NavigationMode.ByAssembly;
options.NamespaceMode = NamespaceMode.Folder;
options.GenerateDocsJson = true;
options.IncludeIcons = true;
options.UnifiedGroupName = "API Reference";
});
var result = await builder.BuildAsync();
```
```xml With MSBuild Integration (.docsproj) theme={"dark"}
Mintlify
Unified
My Project
Tabs
My API
maple
#419AC5
```
Build your project to automatically generate Mintlify documentation:
```bash theme={"dark"}
dotnet build --configuration Release
```
Your MDX files and `docs.json` will be generated in the output directory.
Install the Mintlify CLI and preview your docs locally:
```bash theme={"dark"}
npm install -g mintlify
cd docs
mintlify dev
```
Your documentation will be available at `http://localhost:3000`.
## Configuration Reference
Controls how navigation is organized in `docs.json`:
| Mode | Description | Best For |
| ------------ | ------------------------------------------ | ------------------------ |
| `Unified` | Single navigation tree with all namespaces | Single-project solutions |
| `ByAssembly` | Separate groups per assembly | Multi-project solutions |
```csharp theme={"dark"}
options.NavigationMode = NavigationMode.ByAssembly;
```
Controls file system organization:
| Mode | Description | Output Structure |
| -------- | --------------------------------------------- | ------------------------- |
| `File` | One MDX file per namespace | `MyNamespace.mdx` |
| `Folder` | Folder per namespace with separate type files | `MyNamespace/MyClass.mdx` |
```csharp theme={"dark"}
options.NamespaceMode = NamespaceMode.Folder;
```
Additional configuration options:
```csharp theme={"dark"}
public class MintlifyRendererOptions
{
// Whether to generate docs.json navigation file
public bool GenerateDocsJson { get; set; } = true;
// Whether to include namespace index pages
public bool GenerateNamespaceIndex { get; set; } = true;
// Whether to include FontAwesome icons
public bool IncludeIcons { get; set; } = true;
// Order of namespaces in navigation (default: alphabetical)
public List NamespaceOrder { get; set; }
// Template for docs.json configuration (merged with generated navigation)
public DocsJsonConfig Template { get; set; }
// Group name for Unified navigation mode
public string UnifiedGroupName { get; set; } = "API Reference";
}
```
## Rich Mintlify Components
The Mintlify provider generates standard MDX, allowing you to enhance generated docs with Mintlify's rich component library. Below are examples of the most commonly used components.
### Tabs & CodeGroup
Display multiple code examples or content variants. The Tabs component works with any content, while CodeGroup is specifically optimized for code blocks.
```csharp theme={"dark"}
var result = await processor.ProcessAsync();
```
```fsharp theme={"dark"}
let! result = processor.ProcessAsync()
```
### Callouts
Highlight important information with colored callout boxes:
This method is thread-safe and can be called concurrently.
This operation cannot be undone.
Use caching to improve performance.
Available since version 2.0
Best practice: Always dispose of resources
### Cards & CardGroup
Create visually appealing content grids. Perfect for navigation and feature showcases.
### Steps
The Steps component guides users through sequential processes with automatic numbering and visual flow.
### Accordions
Accordions organize collapsible content sections for progressive disclosure. They work great for FAQs, detailed explanations, and organizing large amounts of related content.
## Icon Reference
The Mintlify provider includes 50+ context-aware FontAwesome icons. Icons are automatically assigned based on type characteristics, but you can override them in XML documentation using custom tags.
Icons assigned based on type classification:
| Type | Icon Class | Icon |
| --------------------- | ------------------------ | -------------------------------------- |
| Class | `file-brackets-curly` | |
| Abstract Class | `shapes` | |
| Static Class | `bolt` | |
| Sealed Class | `lock` | |
| Generic Type | `code-branch` | |
| Interface | `plug` | |
| Struct | `cubes` | |
| Enum | `list-ol` | |
| Record | `database` | |
| Delegate | `arrow-right-arrow-left` | |
| Assembly | `cubes` | |
| Namespace (populated) | `folder-tree` | |
| Namespace (empty) | `folder-open` | |
Icons for class members:
| Member | Icon Class | Icon |
| ---------------- | -------------- | ---------------------------- |
| Method | `function` | |
| Extension Method | `puzzle-piece` | |
| Override Method | `code-merge` | |
| Virtual Method | `code-fork` | |
| Async Method | `rotate` | |
| Static Member | `thumbtack` | |
| Property | `tag` | |
| Field | `box` | |
| Constant Field | `anchor` | |
| Event | `bell` | |
| Constructor | `hammer` | |
| Operator | `calculator` | |
| Indexer | `table-cells` | |
Icons assigned based on type naming patterns:
| Pattern | Icon Class | Icon | Example |
| -------------------- | ---------------------- | ------------------------------------ | --------------------- |
| \*Manager | `briefcase` | | DocumentationManager |
| \*Service | `server` | | PaymentService |
| \*Controller | `gamepad` | | ApiController |
| \*Factory | `industry` | | ConnectionFactory |
| \*Builder | `hammer` | | StringBuilder |
| \*Provider | `plug` | | ConfigurationProvider |
| \*Handler | `hand` | | EventHandler |
| \*Helper / \*Utility | `wrench` | | StringHelper |
| \*Validator | `check-circle` | | InputValidator |
| \*Model / \*Entity | `database` | | UserModel |
| \*DTO | `exchange` | | PaymentDto |
| \*ViewModel | `layer-group` | | OrderViewModel |
| \*Exception | `triangle-exclamation` | | NotFoundException |
| \*Attribute | `tag` | | ObsoleteAttribute |
| I\* (interface) | `plug` | | IDisposable |
Icons for access modifiers and type characteristics:
| Modifier | Icon Class | Icon |
| ------------------ | --------------- | ----------------------------- |
| Public | `globe` | |
| Protected | `shield` | |
| Protected Internal | `shield-halved` | |
| Internal | `building` | |
| Private | `lock` | |
Icons based on namespace segments:
| Segment | Icon Class | Icon | Example |
| ------------------- | ---------------------- | ------------------------------------ | -------------------- |
| Core | `circle` | | MyApp.Core |
| Extensions | `puzzle-piece` | | MyApp.Extensions |
| Models | `database` | | MyApp.Models |
| Services | `server` | | MyApp.Services |
| Data | `database` | | MyApp.Data |
| Controllers | `gamepad` | | MyApp.Controllers |
| Views | `eye` | | MyApp.Views |
| ViewModels | `layer-group` | | MyApp.ViewModels |
| Configuration | `gears` | | MyApp.Configuration |
| Handlers | `hand` | | MyApp.Handlers |
| Factories | `industry` | | MyApp.Factories |
| Builders | `hammer` | | MyApp.Builders |
| Validators | `check-circle` | | MyApp.Validators |
| Exceptions | `triangle-exclamation` | | MyApp.Exceptions |
| Entities | `cubes` | | MyApp.Entities |
| Enums | `list-ol` | | MyApp.Enums |
| Constants | `anchor` | | MyApp.Constants |
| Tests | `flask` | | MyApp.Tests |
| Shared / Common | `share-nodes` | | MyApp.Shared |
| Utilities / Helpers | `wrench` | | MyApp.Utilities |
| Interfaces | `plug` | | MyApp.Interfaces |
| Api | `plug` | | MyApp.Api |
| Web | `globe` | | MyApp.Web |
| Infrastructure | `building` | | MyApp.Infrastructure |
## Output Structure
The Mintlify provider generates the following file structure:
```plaintext File Mode (Default) theme={"dark"}
docs/
├── docs.json
├── api-reference/
│ ├── MyProject/
│ │ ├── Core.mdx
│ │ ├── Core/Services.mdx
│ │ ├── Extensions.mdx
│ │ └── Models.mdx
│ └── ...
└── ...
```
```plaintext Folder Mode theme={"dark"}
docs/
├── docs.json
├── api-reference/
│ ├── MyProject/
│ │ ├── Core/
│ │ │ ├── index.mdx
│ │ │ ├── DocumentationManager.mdx
│ │ │ ├── Services/
│ │ │ │ ├── index.mdx
│ │ │ │ └── PaymentService.mdx
│ │ │ └── ...
│ │ └── ...
│ └── ...
└── ...
```
## Best Practices
The quality of your generated documentation depends on your XML comments. Include detailed ``, ``, ``, and `` sections.
Follow .NET naming conventions. The icon system works best with standard patterns like \*Manager, \*Service, \*Repository.
Structure your namespaces hierarchically. Use segments like Core, Extensions, Models, Services for better automatic icon selection.
Use the Template property to provide custom docs.json configuration settings like themes, colors, and integrations.
## See Also
React components, external script loading, hydration fixes, and custom landing page patterns
Multi-project documentation with intelligent path rewriting and resource relocation
Deep dive into how Mintlify generates and merges navigation structures
Programmatically create, validate, and manage Mintlify docs.json configurations in C#
Complete MintlifyRenderer API documentation
Understand the DotNetDocs documentation pipeline
Official Mintlify documentation and component reference
DocsJsonConfig schema and available settings