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

React Components

Embed custom React components directly in your MDX files for interactive documentation

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

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"]
        }
      ]
    }
  ]
}

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

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

services.AddDotNetDocsMintlify(options =>
{
    options.Template = new DocsJsonConfig
    {
        Name = "My API",
        Theme = "quill",
        Colors = new ColorsConfig
        {
            Primary = "#007ACC",
            Light = "#50A3D0",
            Dark = "#004B87"
        },
        Integrations = new IntegrationsConfig
        {
            Ga4 = new GoogleAnalytics4Config { MeasurementId = "G-XXXXXXXXXX" }
        }
    };
    options.IncludeIcons = true;
    options.GenerateDocsJson = true;
});

React Component Support

Mintlify MDX supports embedding custom React components directly in your documentation:

Import components from the snippets folder
Use React hooks (useState, useEffect, etc.)
Create interactive demos, calculators, and visualizations
Build reusable component libraries

snippets/ColorPicker.jsx

export const ColorPicker = () => {
  const [color, setColor] = React.useState('#3CD0E2');

  return (
    <div>
      <input
        type="color"
        value={color}
        onChange={(e) => setColor(e.target.value)}
      />
      <p>Selected: {color}</p>
    </div>
  );
};

Using the Component

import { ColorPicker } from '/snippets/ColorPicker';

## Try It Out

<ColorPicker />

React components must be placed in the snippets folder and exported as named exports. You cannot import components from arbitrary MDX files.

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

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;

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

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	Symbol
Class	`cube`	🧊
Interface	`layer-group`	📚
Struct	`cube-alt`	🔷
Enum	`list-ol`	📋
Delegate	`arrow-right`	➡️
Namespace	`folder`	📁

Member Icons

Icons for class members:

Member	Icon	Symbol
Method	`function`	ƒ
Property	`sliders`	🎚️
Field	`input-text`	📝
Event	`bolt`	⚡
Constructor	`hammer`	🔨
Operator	`calculator`	🔢

Pattern-Based Icons

Icons assigned based on naming patterns:

Pattern	Icon	Example
*Manager	`gears`	DocumentationManager
*Service	`server`	PaymentService
*Repository	`database`	UserRepository
*Controller	`gamepad`	ApiController
*Factory	`industry`	ConnectionFactory
*Builder	`hammer`	StringBuilder
*Provider	`plug`	ConfigurationProvider
*Handler	`hand`	EventHandler
*Helper	`circle-question`	StringHelper
*Validator	`check-circle`	InputValidator

Modifier Icons

Additional icons for access modifiers and type characteristics:

Modifier	Icon	Symbol
Static	`s`	S
Abstract	`shapes`	🔺
Sealed	`lock`	🔒
Generic	`brackets-curly`
Async	`arrows-spin`	🔄

Namespace Segment Icons

Icons based on namespace segments:

Segment	Icon	Example
Core	`circle-dot`	MyApp.Core
Extensions	`puzzle-piece`	MyApp.Extensions
Models	`diagram-project`	MyApp.Models
Services	`server`	MyApp.Services
Data	`database`	MyApp.Data
Security	`shield`	MyApp.Security
Web	`globe`	MyApp.Web
Api	`cloud`	MyApp.Api
Testing	`vial`	MyApp.Testing

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
│   └── ...
└── ...

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.

API Reference

Complete MintlifyRenderer API documentation

Mintlify Documentation

Official Mintlify documentation and component reference

Mintlify Schema

DocsJsonConfig schema and available settings

Pipeline Guide

Understand the DotNetDocs documentation pipeline

Getting Started

Guides

Providers

Plugins

Learnings

API Reference

Mintlify-Enhanced Docs

MDX with Frontmatter

Smart Navigation

Context-Aware Icons

React Components

Overview

Key Features

MDX Generation with Rich Frontmatter

Hierarchical Navigation Generation

50+ Context-Aware Icons

Flexible Output Modes

DocsJson Template Customization

React Component Support

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

API Reference

Mintlify Documentation

Mintlify Schema

Pipeline Guide

Getting Started

Guides

Providers

Plugins

Learnings

API Reference

MDX with Frontmatter

Smart Navigation

Context-Aware Icons

React Components

​Overview

​Key Features

​MDX Generation with Rich Frontmatter

​Hierarchical Navigation Generation

​50+ Context-Aware Icons

​Flexible Output Modes

​DocsJson Template Customization

​React Component Support

​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

API Reference

Mintlify Documentation

Mintlify Schema

Pipeline Guide

Overview

Key Features

MDX Generation with Rich Frontmatter

Hierarchical Navigation Generation

50+ Context-Aware Icons

Flexible Output Modes

DocsJson Template Customization

React Component Support

Getting Started

Configuration Reference

Rich Mintlify Components

Tabs & CodeGroup

Callouts

Cards & CardGroup

Steps

Accordions

Icon Reference

Output Structure

Best Practices

See Also