Mintlify-Enhanced Docs

MDX with Frontmatter

Auto-generated frontmatter with icons, tags, SEO metadata, and keywords for every API page

Smart Navigation

Automatic docs.json generation with hierarchical namespace organization and flexible navigation modes

Context-Aware Icons

50+ FontAwesome icons automatically assigned based on type characteristics and naming patterns

Collections

Multi-project documentation with intelligent path rewriting and resource relocation

.NET Library

Programmatically create, validate, and manage Mintlify docs.json configurations in C#

Tips & Tricks

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

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

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

The Mintlify provider generates docs.json navigation files that organize your API documentation into logical hierarchies. Choose between two navigation modes:

Unified Mode (Default)
ByAssembly Mode

Creates a single navigation tree with all namespaces organized hierarchically under one group.

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

[
  {
    "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 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

api-reference/
  MyNamespace.mdx
  MyNamespace.SubNamespace.mdx

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)

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

Add the Mintlify Provider

Install the CloudNimble.DotNetDocs.Mintlify package:

dotnet add package CloudNimble.DotNetDocs.Mintlify

Configure Your Pipeline

var builder = new DotNetDocsBuilder()
    .AddDefaultPipeline()
    .AddMintlifyRenderer();

var result = await builder.BuildAsync();

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();

<Project Sdk="DotNetDocs.Sdk/1.2.0">
  <PropertyGroup>
    <DocumentationType>Mintlify</DocumentationType>
    <MintlifyNavigationMode>Unified</MintlifyNavigationMode>
    <MintlifyTemplate>
      <Name>My Project</Name>
      <NavigationType>Tabs</NavigationType>
      <NavigationName>My API</NavigationName>
      <Theme>maple</Theme>
      <Colors>
        <Primary>#419AC5</Primary>
      </Colors>
    </MintlifyTemplate>
  </PropertyGroup>
</Project>

Generate Documentation

Build your project to automatically generate Mintlify documentation:

dotnet build --configuration Release

Your MDX files and docs.json will be generated in the output directory.

Preview with Mintlify CLI

Install the Mintlify CLI and preview your docs locally:

npm install -g mintlify
cd docs
mintlify dev

Your documentation will be available at http://localhost:3000.

Configuration Reference

NavigationMode
NamespaceMode
Other Options

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

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`

options.NamespaceMode = NamespaceMode.Folder;

Additional configuration options:

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

var result = await processor.ProcessAsync();

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.

Type Icons

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`

Member Icons

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`

Pattern-Based Icons

Icons assigned based on type naming patterns:

Pattern	Icon Class	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

Modifier Icons

Icons for access modifiers and type characteristics:

Modifier	Icon Class	Icon
Public	`globe`
Protected	`shield`
Protected Internal	`shield-halved`
Internal	`building`
Private	`lock`

Namespace Segment Icons

Icons based on namespace segments:

Segment	Icon Class	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:

docs/
├── docs.json
├── api-reference/
│   ├── MyProject/
│   │   ├── Core.mdx
│   │   ├── Core/Services.mdx
│   │   ├── Extensions.mdx
│   │   └── Models.mdx
│   └── ...
└── ...

docs/
├── docs.json
├── api-reference/
│   ├── MyProject/
│   │   ├── Core/
│   │   │   ├── index.mdx
│   │   │   ├── DocumentationManager.mdx
│   │   │   ├── Services/
│   │   │   │   ├── index.mdx
│   │   │   │   └── PaymentService.mdx
│   │   │   └── ...
│   │   └── ...
│   └── ...
└── ...

Best Practices

Write Detailed XML Comments

The quality of your generated documentation depends on your XML comments. Include detailed <summary>, <remarks>, <example>, and <code> sections.

Use Consistent Naming

Follow .NET naming conventions. The icon system works best with standard patterns like *Manager, *Service, *Repository.

Organize Namespaces Logically

Structure your namespaces hierarchically. Use segments like Core, Extensions, Models, Services for better automatic icon selection.

Customize DocsJson Configuration

Use the Template property to provide custom docs.json configuration settings like themes, colors, and integrations.

Tips & Tricks

React components, external script loading, hydration fixes, and custom landing page patterns

Collections

Multi-project documentation with intelligent path rewriting and resource relocation

Navigation Generation

Deep dive into how Mintlify generates and merges navigation structures

.NET Library

Programmatically create, validate, and manage Mintlify docs.json configurations in C#

API Reference

Complete MintlifyRenderer API documentation

Pipeline Guide

Understand the DotNetDocs documentation pipeline

Mintlify Documentation

Official Mintlify documentation and component reference

Mintlify Schema

DocsJsonConfig schema and available settings

MDX with Frontmatter

Smart Navigation

Context-Aware Icons

Collections

.NET Library

Tips & Tricks

​Overview

​Key Features

​MDX Generation with Rich Frontmatter

​Hierarchical Navigation Generation

​50+ Context-Aware Icons

​Flexible Output Modes

​DocsJson Template Customization

​Getting Started

​Configuration Reference

​Rich Mintlify Components

​Tabs & CodeGroup

​Callouts

​Cards & CardGroup

​Steps

​Accordions

​Icon Reference

​Output Structure

​Best Practices

Write Detailed XML Comments

Use Consistent Naming

Organize Namespaces Logically

Customize DocsJson Configuration

​See Also

Tips & Tricks

Collections

Navigation Generation

.NET Library

API Reference

Pipeline Guide

Mintlify Documentation

Mintlify Schema

Overview

Key Features

MDX Generation with Rich Frontmatter

Hierarchical Navigation Generation

50+ Context-Aware Icons

Flexible Output Modes

DocsJson Template Customization

Getting Started

Configuration Reference

Rich Mintlify Components

Tabs & CodeGroup

Callouts

Cards & CardGroup

Steps

Accordions

Icon Reference

Output Structure

Best Practices

See Also