.NET Library for Mintlify

Mintlify.Core is a comprehensive .NET library that provides strongly-typed models, validation, and management tools for Mintlify documentation configurations. Built by the CloudNimble team and used by DotNetDocs, it enables C# developers to programmatically generate, modify, and validate docs.json files with full IntelliSense support.

Why Use Mintlify.Core?

Type Safety

Strongly-typed C# models for every Mintlify configuration option with compile-time validation

IntelliSense Support

Full XML documentation on every property with examples and schema references

Validation Built-In

Comprehensive validation against Mintlify schema ensures configurations will work before deployment

Multi-Platform

Targets .NET Standard 2.0, .NET 8, .NET 9, and .NET 10 for maximum compatibility

Navigation Management

Advanced DocsJsonManager for intelligent navigation merging and duplicate detection

Production Ready

Battle-tested in DotNetDocs and used by Sustainment for managing complex documentation sites

Installation

Install via NuGet Package Manager or .NET CLI:

dotnet add package Mintlify.Core

<PackageReference Include="Mintlify.Core" Version="*" />

Install-Package Mintlify.Core

Quick Start

Create a basic Mintlify configuration programmatically:

using Mintlify.Core;
using Mintlify.Core.Models;

// Create a default configuration
var config = DocsJsonManager.CreateDefault("My Project", "maple");

// Customize colors
config.Colors.Primary = "#419AC5";
config.Colors.Light = "#419AC5";
config.Colors.Dark = "#3CD0E2";

// Add logo
config.Logo = new LogoConfig
{
    Light = "/images/logo-light.svg",
    Dark = "/images/logo-dark.svg"
};

// Create navigation groups
config.Navigation.Pages = new List<object>
{
    new GroupConfig
    {
        Group = "Getting Started",
        Icon = new IconConfig { Name = "rocket" },
        Pages = new List<object> { "index", "quickstart", "installation" }
    },
    new GroupConfig
    {
        Group = "API Reference",
        Icon = new IconConfig { Name = "code" },
        Pages = new List<object> { "api-reference/index" }
    }
};

// Serialize to JSON
var json = JsonSerializer.Serialize(config, MintlifyConstants.JsonSerializerOptions);
File.WriteAllText("docs.json", json);

Core Components

DocsJsonConfig

The root configuration object representing the complete docs.json schema:

public class DocsJsonConfig
{
    [NotNull] public string Name { get; set; }           // Required
    [NotNull] public string Theme { get; set; }          // Required: mint, maple, palm, etc.
    [NotNull] public ColorsConfig Colors { get; set; }   // Required: Primary color minimum
    [NotNull] public NavigationConfig Navigation { get; set; } // Required

    public string? Description { get; set; }              // SEO description
    public LogoConfig? Logo { get; set; }                 // Light/dark logos
    public FaviconConfig? Favicon { get; set; }           // Favicon paths
    public FooterConfig? Footer { get; set; }             // Footer configuration
    public NavbarConfig? Navbar { get; set; }             // Top navigation
    public ApiConfig? Api { get; set; }                   // API playground settings
    public SeoConfig? Seo { get; set; }                   // SEO settings
    public AppearanceConfig? Appearance { get; set; }     // Light/dark mode
    public StylingConfig? Styling { get; set; }           // Custom CSS/styling
    public IntegrationsConfig? Integrations { get; set; } // Analytics, support, etc.
    // ... and 10+ more optional configuration properties
}

All required properties are marked with [NotNull] and will generate compiler warnings if not set. Use the DocsJsonValidator to catch configuration issues at runtime.

NavigationConfig

Defines the documentation structure with support for pages, groups, tabs, anchors, and more:

public class NavigationConfig
{
    public List<object>? Pages { get; set; }           // Mix of strings and GroupConfig
    public List<GroupConfig>? Groups { get; set; }     // Named groups
    public List<TabConfig>? Tabs { get; set; }         // Top-level tabs
    public List<AnchorConfig>? Anchors { get; set; }   // Sidebar anchors
    public List<DropdownConfig>? Dropdowns { get; set; } // Dropdown menus
    public List<LanguageConfig>? Languages { get; set; } // Language switcher
    public List<VersionConfig>? Versions { get; set; }  // Version switcher
    public GlobalNavigationConfig? Global { get; set; } // Global nav items
}

Pages Property: The Pages property is polymorphic - it can contain both string (page paths) and GroupConfig objects (nested groups):

config.Navigation.Pages = new List<object>
{
    "index",  // Simple page reference
    "quickstart",
    new GroupConfig  // Nested group
    {
        Group = "Guides",
        Pages = new List<object> { "guides/intro", "guides/advanced" }
    }
};

GroupConfig

Organizes pages into collapsible sections:

public class GroupConfig
{
    [NotNull] public string Group { get; set; }    // Group title (required)
    public List<object>? Pages { get; set; }       // Nested pages/groups
    public IconConfig? Icon { get; set; }          // Group icon
    public string? Tag { get; set; }               // Badge text (e.g., "NEW", "BETA")
    public string? Root { get; set; }              // Root page URL
    public bool? Hidden { get; set; }              // Hide from navigation
    public ApiSpecConfig? OpenApi { get; set; }    // OpenAPI spec path
    public ApiSpecConfig? AsyncApi { get; set; }   // AsyncAPI spec path
}

Nested Groups: Groups can contain other groups for hierarchical navigation:

new GroupConfig
{
    Group = "API Reference",
    Pages = new List<object>
    {
        "api/overview",
        new GroupConfig
        {
            Group = "Authentication",
            Pages = new List<object> { "api/auth/oauth", "api/auth/api-keys" }
        }
    }
}

ColorsConfig

Theme color configuration with hex color validation:

public class ColorsConfig
{
    [NotNull] public string Primary { get; set; } = "#000000";  // Required
    public string? Light { get; set; }   // Light mode accent (used in dark mode)
    public string? Dark { get; set; }    // Dark mode accent (used in light mode)
}

All colors must be valid hex format: #RRGGBB or #RGB. The validator will catch invalid formats.

DocsJsonManager

The DocsJsonManager class provides advanced navigation management with intelligent merging and duplicate detection:

Key Features

Load & Save

var manager = new DocsJsonManager();

// Load from file
manager = new DocsJsonManager("path/to/docs.json");
manager.Load();

// Load from string
manager.Load(jsonString);

// Load from config object
manager.Load(docsConfig);

// Save back to file
manager.Save();
manager.Save("path/to/output.json");

Create Default Configuration

var config = DocsJsonManager.CreateDefault("Project Name", "maple");
// Returns a DocsJsonConfig with sensible defaults:
// - Basic Getting Started and API Reference groups
// - Default color scheme
// - Standard navigation structure

Navigation Discovery

manager.Load(config);

// Scan directory for .mdx files and populate navigation
manager.PopulateNavigationFromPath(
    path: "./docs",
    fileExtensions: new[] { ".mdx" },
    includeApiReference: false,   // Exclude api-reference folder
    preserveExisting: true,        // Merge with existing navigation
    allowDuplicatePaths: false     // Skip duplicate pages
);

manager.Save("docs.json");

Smart Navigation Merging

// Load base configuration
manager.Load(baseConfig);

// Merge another configuration
manager.Merge(otherConfig, combineBaseProperties: true);

// Merge just navigation from a file
manager.MergeNavigation("external-docs.json");

// Merge navigation from a config object
manager.MergeNavigation(externalConfig.Navigation);

Add Pages Safely

// Add page to navigation root
manager.AddPage(manager.Configuration.Navigation.Pages, "new-page");

// Add page to specific group path
manager.AddPage("Getting Started/Tutorials", "tutorial-1");

// Add page to group with duplicate detection
var group = manager.FindOrCreateGroup(pages, "My Group");
if (manager.AddPageToGroup(group, "my-page"))
{
    Console.WriteLine("Page added successfully");
}
else
{
    Console.WriteLine("Page already exists, skipped");
}

Check Known Paths

// The manager tracks all added paths internally
if (manager.IsPathKnown("api-reference/index"))
{
    Console.WriteLine("This page is already in navigation");
}

Duplicate Detection

The DocsJsonManager maintains an internal _knownPagePaths HashSet that tracks every page path added to navigation:

var manager = new DocsJsonManager();
manager.Load(config);  // Scans existing navigation, populates _knownPagePaths

// Attempt to add duplicate
var added = manager.AddPage(pages, "quickstart");  // Returns false if already exists

// Check before adding
if (!manager.IsPathKnown("new-guide"))
{
    manager.AddPage(pages, "new-guide");
}

Duplicate detection is case-insensitive and works across all navigation levels (root pages, grouped pages, nested groups).

DocsJsonValidator

Comprehensive validation against the Mintlify schema:

using Mintlify.Core;
using Mintlify.Core.Models;

var validator = new DocsJsonValidator();
var errors = validator.Validate(config);

if (errors.Count > 0)
{
    Console.WriteLine("Configuration errors:");
    foreach (var error in errors)
    {
        Console.WriteLine($"  - {error}");
    }
}

Validation Rules

The validator checks: Required Fields

Name must be set
Theme must be set and valid
Colors.Primary must be a valid hex color
Navigation must have at least one navigation element

Theme Validation

Must be one of: mint, maple, palm, willow, linden, almond, aspen

Color Validation

All colors must match regex: ^#([a-fA-F0-9]{6}|[a-fA-F0-9]{3})$
Examples: #FF0000, #F00, #419AC5

Navigation Validation

Must contain at least one of: pages, groups, anchors, tabs, dropdowns, languages, versions
Group names cannot be null (Mintlify will reject the config)
Empty group names generate warnings (treated as separate ungrouped sections)

API Configuration Validation

Auth methods: bearer, basic, key, cobo
Playground display: interactive, simple, none
Examples defaults: all, required

Appearance Validation

Default mode: system, light, dark

Icons Validation

Library: fontawesome, lucide

SEO Validation

Indexing: navigable, all

Example Validation Output

var config = new DocsJsonConfig
{
    Name = "",  // Invalid: empty
    Theme = "custom",  // Invalid: not a valid theme
    Colors = new ColorsConfig { Primary = "blue" }  // Invalid: not hex format
};

var errors = validator.Validate(config);
// Returns:
// - "Name is required."
// - "Invalid theme 'custom'. Valid themes are: mint, maple, palm, willow, linden, almond, aspen"
// - "Primary color 'blue' must be a valid hex color (e.g., #FF0000 or #F00)."

MintlifyConstants

Provides shared configuration for consistent JSON serialization:

public static class MintlifyConstants
{
    public static JsonSerializerOptions JsonSerializerOptions { get; }
}

The JsonSerializerOptions instance includes:

Indented formatting for readable JSON output
CamelCase property naming to match Mintlify schema
Null value ignoring to omit optional properties
Custom converters for polymorphic types:
- NavigationJsonConverter - Handles complex navigation structures
- NavigationPageListConverter - Handles mixed string/GroupConfig lists
- IconConverter - Supports both string and object icon formats
- ColorConverter - Handles color pairs and single values
- ApiConfigConverter - Handles API spec configuration formats

Usage

using System.Text.Json;
using Mintlify.Core;

// Serialize with proper formatting
var json = JsonSerializer.Serialize(config, MintlifyConstants.JsonSerializerOptions);

// Deserialize with proper type handling
var config = JsonSerializer.Deserialize<DocsJsonConfig>(json, MintlifyConstants.JsonSerializerOptions);

Configuration Models Reference

Mintlify.Core includes 50+ strongly-typed models covering every Mintlify configuration option:

Theme & Appearance

ColorsConfig

Theme color configurationProperties:

Primary (required): Main theme color
Light: Light mode accent
Dark: Dark mode accent

config.Colors = new ColorsConfig
{
    Primary = "#419AC5",
    Light = "#419AC5",
    Dark = "#3CD0E2"
};

LogoConfig

Logo configuration for light and dark modesProperties:

Light: Path to light mode logo
Dark: Path to dark mode logo
Href: URL logo links to

config.Logo = new LogoConfig
{
    Light = "/images/logo-light.svg",
    Dark = "/images/logo-dark.svg",
    Href = "https://example.com"
};

FaviconConfig

Favicon paths for different modesProperties:

Light: Light mode favicon
Dark: Dark mode favicon

config.Favicon = new FaviconConfig
{
    Light = "/favicon-light.png",
    Dark = "/favicon-dark.png"
};

AppearanceConfig

Appearance and color mode settingsProperties:

Default: Default mode (system, light, dark)
Toggle: Show dark mode toggle

config.Appearance = new AppearanceConfig
{
    Default = "dark",
    Toggle = true
};

StylingConfig

Custom styling and CSSProperties:

StylesheetPaths: Array of custom CSS file paths
Codeblocks: Code block styling options

config.Styling = new StylingConfig
{
    StylesheetPaths = new List<string> { "/styles/custom.css" }
};

TabConfig

Top-level navigation tabsProperties:

Tab: Tab title
Href: Tab URL
Pages: Tab pages
Groups: Tab groups
Icon: Tab icon

new TabConfig
{
    Tab = "API",
    Href = "/api",
    Icon = new IconConfig { Name = "code" },
    Pages = new List<object> { "api/overview" }
}

AnchorConfig

Sidebar anchor linksProperties:

Anchor: Link text
Href: Link URL
Icon: Anchor icon

new AnchorConfig
{
    Anchor = "Community",
    Href = "https://community.example.com",
    Icon = new IconConfig { Name = "users" }
}

DropdownConfig

Dropdown navigation menusProperties:

Dropdown: Dropdown title
Href: Optional direct link
Items: Dropdown items

new DropdownConfig
{
    Dropdown = "Resources",
    Items = new List<NavbarLink>
    {
        new NavbarLink { Name = "Blog", Href = "/blog" },
        new NavbarLink { Name = "Docs", Href = "/docs" }
    }
}

API & Integration

ApiConfig

API playground and documentation settingsProperties:

Mdx: MDX API configuration
Playground: Playground display settings
Examples: Example configuration
Params: Parameter settings

config.Api = new ApiConfig
{
    Playground = new ApiPlaygroundConfig
    {
        Display = "interactive"
    }
};

IntegrationsConfig

Analytics and third-party integrationsProperties:

GoogleAnalytics: GA tracking ID
GoogleTagManager: GTM ID
Mixpanel: Mixpanel project token
Segment: Segment write key
Intercom: Intercom app ID
And 10+ more integrations

config.Integrations = new IntegrationsConfig
{
    GoogleAnalytics = "G-XXXXXXXXXX",
    Intercom = "app_id_here"
};

SeoConfig

SEO and indexing settingsProperties:

Indexing: Indexing mode (navigable, all)
Sitemap: Custom sitemap URL

config.Seo = new SeoConfig
{
    Indexing = "all",
    Sitemap = "https://example.com/sitemap.xml"
};

Advanced Features

FooterConfig

Footer configuration with social linksProperties:

Socials: Social media links
Links: Custom footer links

config.Footer = new FooterConfig
{
    Socials = new Dictionary<string, string>
    {
        { "twitter", "https://twitter.com/example" },
        { "github", "https://github.com/example" }
    }
};

BannerConfig

Top banner configurationProperties:

Text: Banner text
Link: Banner link URL
Color: Banner color

config.Banner = new BannerConfig
{
    Text = "New version available!",
    Link = "/changelog",
    Color = "#419AC5"
};

RedirectConfig

URL redirectsProperties:

Source: Source path
Destination: Destination path

config.Redirects = new List<RedirectConfig>
{
    new RedirectConfig
    {
        Source = "/old-path",
        Destination = "/new-path"
    }
};

SearchConfig

Search configurationProperties:

Provider: Search provider
AlgoliaConfig: Algolia settings

config.Search = new SearchConfig
{
    Provider = "algolia"
};

Advanced Scenarios

Building Multi-Project Documentation

var manager = new DocsJsonManager();

// Create base configuration
var baseConfig = DocsJsonManager.CreateDefault("Multi-Project Docs", "maple");
manager.Load(baseConfig);

// Add Project A navigation
var projectANav = new NavigationConfig
{
    Pages = new List<object>
    {
        new GroupConfig
        {
            Group = "Project A",
            Pages = new List<object> { "project-a/overview", "project-a/api" }
        }
    }
};
manager.MergeNavigation(projectANav);

// Add Project B navigation
var projectBNav = new NavigationConfig
{
    Pages = new List<object>
    {
        new GroupConfig
        {
            Group = "Project B",
            Pages = new List<object> { "project-b/overview", "project-b/api" }
        }
    }
};
manager.MergeNavigation(projectBNav);

manager.Save("docs.json");

// Create custom navigation for a specific directory
var customGroup = new GroupConfig
{
    Group = "Advanced Topics",
    Icon = new IconConfig { Name = "graduation-cap" },
    Pages = new List<object>
    {
        "advanced/architecture",
        "advanced/performance",
        new GroupConfig
        {
            Group = "Security",
            Pages = new List<object>
            {
                "advanced/security/authentication",
                "advanced/security/authorization"
            }
        }
    }
};

// Serialize to navigation.json
var json = JsonSerializer.Serialize(customGroup, MintlifyConstants.JsonSerializerOptions);
File.WriteAllText("docs/advanced/navigation.json", json);

Programmatic Theme Configuration

var config = DocsJsonManager.CreateDefault("My Docs", "maple");

// Configure complete theme
config.Colors = new ColorsConfig
{
    Primary = "#419AC5",
    Light = "#419AC5",
    Dark = "#3CD0E2"
};

config.Logo = new LogoConfig
{
    Light = "/images/logo-light.svg",
    Dark = "/images/logo-dark.svg"
};

config.Favicon = new FaviconConfig
{
    Light = "/favicon-light.png",
    Dark = "/favicon-dark.png"
};

config.Appearance = new AppearanceConfig
{
    Default = "system",
    Toggle = true
};

config.Footer = new FooterConfig
{
    Socials = new Dictionary<string, string>
    {
        { "twitter", "https://twitter.com/myproject" },
        { "github", "https://github.com/myproject" },
        { "discord", "https://discord.gg/myproject" }
    }
};

Validation Pipeline

public bool ValidateAndSaveConfig(DocsJsonConfig config, string outputPath)
{
    var validator = new DocsJsonValidator();
    var errors = validator.Validate(config);

    if (errors.Count > 0)
    {
        Console.WriteLine("L Configuration validation failed:");
        foreach (var error in errors)
        {
            Console.WriteLine($"   {error}");
        }
        return false;
    }

    try
    {
        var json = JsonSerializer.Serialize(config, MintlifyConstants.JsonSerializerOptions);
        File.WriteAllText(outputPath, json);
        Console.WriteLine($" Configuration saved to {outputPath}");
        return true;
    }
    catch (Exception ex)
    {
        Console.WriteLine($"L Failed to save configuration: {ex.Message}");
        return false;
    }
}

Best Practices

Always Validate

Use DocsJsonValidator before saving configurations to catch errors early. Invalid configs will be rejected by Mintlify.

Use DocsJsonManager

Leverage DocsJsonManager for navigation operations instead of manually manipulating collections. It handles duplicate detection automatically.

Preserve Templates

When using PopulateNavigationFromPath, set preserveExisting: true to merge discovered content with template navigation.

Check Known Paths

Use IsPathKnown() before adding pages to avoid duplicates. The manager tracks all paths internally.

Serialize with Constants

Always use MintlifyConstants.JsonSerializerOptions for consistent JSON formatting and proper converter handling.

Set Required Fields First

Initialize Name, Theme, Colors.Primary, and Navigation before other properties. These are required by Mintlify.

Multi-Platform Support

Mintlify.Core targets multiple .NET platforms for maximum compatibility:

Framework	Version	Use Case
.NET 10.0	Latest	Bleeding-edge projects
.NET 9.0	Current	Modern .NET applications
.NET 8.0	LTS	Enterprise production apps
.NET Standard 2.0	Legacy	Maximum compatibility

All core functionality works identically across platforms, with some optimizations for modern frameworks (e.g., source-generated regex in .NET 7+).

Navigation Generation

Learn how MintlifyRenderer uses DocsJsonManager to build navigation

Mintlify Provider Overview

Complete guide to the Mintlify provider features

DocsJsonManager API

Full API reference for DocsJsonManager class

Mintlify Schema

Official Mintlify docs.json schema reference

​Why Use Mintlify.Core?

Type Safety

IntelliSense Support

Validation Built-In

Multi-Platform

Navigation Management

Production Ready

​Installation

​Quick Start

​Core Components

​DocsJsonConfig

​NavigationConfig

​GroupConfig

​ColorsConfig

​DocsJsonManager

​Key Features

​Duplicate Detection

​DocsJsonValidator

​Validation Rules

​Example Validation Output

​MintlifyConstants

​Usage

​Configuration Models Reference

​Theme & Appearance

​Navigation Components

​API & Integration

​Advanced Features

​Advanced Scenarios

​Building Multi-Project Documentation

​Custom Navigation Override

​Programmatic Theme Configuration

​Validation Pipeline

​Best Practices

Always Validate

Use DocsJsonManager

Preserve Templates

Check Known Paths

Serialize with Constants

Set Required Fields First

​Multi-Platform Support

​See Also

Navigation Generation

Mintlify Provider Overview

DocsJsonManager API

Mintlify Schema

Why Use Mintlify.Core?

Installation

Quick Start

Core Components

DocsJsonConfig

NavigationConfig

GroupConfig

ColorsConfig

DocsJsonManager

Key Features

Duplicate Detection

DocsJsonValidator

Validation Rules

Example Validation Output

MintlifyConstants

Usage

Configuration Models Reference

Theme & Appearance

Navigation Components

API & Integration

Advanced Features

Advanced Scenarios

Building Multi-Project Documentation

Custom Navigation Override

Programmatic Theme Configuration

Validation Pipeline

Best Practices

Multi-Platform Support

See Also