Definition
Assembly: Mintlify.Core.dll Namespace: Mintlify.Core Inheritance: System.ObjectSyntax
Summary
Loads and manages Mintlify docs.json configuration files with navigation manipulation capabilities.Remarks
This class provides comprehensive support for loading, validating, and modifying Mintlify documentation configuration files. It handles serialization using the standard Mintlify JSON options and provides APIs for navigation manipulation.Constructors
.ctor
Initializes a new instance of the DocsJsonManager class.Syntax
Parameters
| Name | Type | Description |
|---|---|---|
validator | Mintlify.Core.DocsJsonValidator? | The validator to use for validating configurations. If null, a new instance will be created. |
.ctor
Initializes a new instance of the DocsJsonManager class with the specified file path.Syntax
Parameters
| Name | Type | Description |
|---|---|---|
filePath | string | The path to the docs.json file to load. |
validator | Mintlify.Core.DocsJsonValidator? | The validator to use for validating configurations. If null, a new instance will be created. |
Exceptions
| Exception | Description |
|---|---|
ArgumentException | Thrown when the file path does not exist or is not a JSON file. |
Properties
Configuration
Gets the loaded Mintlify documentation configuration.Syntax
Property Value
Type:Mintlify.Core.Models.DocsJsonConfig?
The DocsJsonConfig instance loaded from the file system or string content.
Returns null if no configuration has been loaded or if loading failed.
ConfigurationErrors
Gets the collection of configuration loading errors encountered during processing.Syntax
Property Value
Type:System.Collections.Generic.List<System.CodeDom.Compiler.CompilerError>
A collection of CompilerError instances representing validation errors,
parsing failures, or other issues encountered during configuration loading.
FilePath
Gets the file path of the loaded docs.json configuration file.Syntax
Property Value
Type:string?
The full path to the docs.json file that was loaded. Returns null if the configuration
was loaded from string content rather than a file.
IsLoaded
Gets a value indicating whether the configuration has been successfully loaded.Syntax
Property Value
Type:bool
True if the configuration was loaded without errors; otherwise, false.
Methods
AddNavigationItem
Adds a navigation item (page or group) to the specified collection, tracking paths appropriately.Syntax
Parameters
| Name | Type | Description |
|---|---|---|
pages | System.Collections.Generic.List<object> | The pages collection to add to. |
item | object | The item to add (string page path or GroupConfig). |
Returns
Type:bool
True if the item was added; false if it was skipped (duplicate).
AddPage
Adds a page to the navigation structure if it doesn’t already exist.Syntax
Parameters
| Name | Type | Description |
|---|---|---|
pages | System.Collections.Generic.List<object> | The pages collection to add to. |
pagePath | string | The page path to add. |
allowDuplicatePaths | bool | If true, allows adding duplicate paths; otherwise, skips if the path already exists. |
updateKnownPaths | bool | If true, updates the known page paths tracking; otherwise, only adds to the pages collection. |
Returns
Type:bool
True if the page was added; false if it already existed and duplicates are not allowed.
AddPage
Adds a page to a hierarchical group path (slash-separated) in the navigation structure.Syntax
Parameters
| Name | Type | Description |
|---|---|---|
groupPath | string | The hierarchical group path (e.g., “Getting Started/API Reference”). |
pagePath | string | The page path to add. |
allowDuplicatePaths | bool | If true, allows adding duplicate paths; otherwise, skips if the path already exists. |
Returns
Type:bool
True if the page was added; false if it already existed and duplicates are not allowed.
Exceptions
| Exception | Description |
|---|---|
InvalidOperationException | Thrown when no configuration is loaded. |
AddPageToGroup
Adds a page to a group if it doesn’t already exist.Syntax
Parameters
| Name | Type | Description |
|---|---|---|
group | Mintlify.Core.Models.GroupConfig | The group to add the page to. |
pagePath | string | The page path to add. |
allowDuplicatePaths | bool | If true, allows adding duplicate paths; otherwise, skips if the path already exists. |
updateKnownPaths | bool | If true, updates the known page paths tracking; otherwise, only adds to the pages collection. |
Returns
Type:bool
True if the page was added; false if it already existed and duplicates are not allowed.
ApplyDefaults
Applies default values to missing configuration properties.Syntax
Parameters
| Name | Type | Description |
|---|---|---|
name | string? | The name to use for the documentation site if not already set. |
theme | string | The theme to use if not already set (defaults to “mint”). |
Exceptions
| Exception | Description |
|---|---|
InvalidOperationException | Thrown when no configuration is loaded. |
ApplyUrlPrefix
Applies a URL prefix to all page references in the navigation structure.Syntax
Parameters
| Name | Type | Description |
|---|---|---|
prefix | string | The prefix to apply to all URLs. |
Exceptions
| Exception | Description |
|---|---|
ArgumentException | Thrown when prefix is null or whitespace. |
InvalidOperationException | Thrown when no configuration is loaded. |
Remarks
This method recursively traverses the entire navigation structure and prepends the specified prefix to all page URLs, href attributes, and root paths. The prefix is normalized to ensure proper URL formatting (e.g., trailing slashes are handled).CreateDefault
Creates a default Mintlify documentation configuration with basic structure.Syntax
Parameters
| Name | Type | Description |
|---|---|---|
name | string | The name of the documentation site. |
theme | string | The theme to use for the documentation site. |
Returns
Type:Mintlify.Core.Models.DocsJsonConfig
A new DocsJsonConfig instance with default values.
Exceptions
| Exception | Description |
|---|---|
ArgumentException | Thrown when name is null or whitespace. |
FindOrCreateGroup
Finds or creates a group with the specified name in the pages collection.Syntax
Parameters
| Name | Type | Description |
|---|---|---|
pages | System.Collections.Generic.List<object> | The pages collection to search/add to. |
groupName | string | The name of the group to find or create. |
Returns
Type:Mintlify.Core.Models.GroupConfig
The existing or newly created group.
IsPathKnown
Checks if a page path is already known (tracked for duplicate prevention).Syntax
Parameters
| Name | Type | Description |
|---|---|---|
pagePath | string | The page path to check. |
Returns
Type:bool
True if the path is already known; otherwise, false.
Load
Loads and parses the docs.json file from the file path specified in the constructor.Syntax
Exceptions
| Exception | Description |
|---|---|
InvalidOperationException | Thrown when no file path has been specified. |
Load
Loads and parses the docs.json configuration from the specified string content.Syntax
Parameters
| Name | Type | Description |
|---|---|---|
content | string | The JSON content to parse as a docs.json configuration. |
Exceptions
| Exception | Description |
|---|---|
ArgumentException | Thrown when content is null or whitespace. |
Load
Loads the specified configuration and applies validation and cleaning steps.Syntax
Parameters
| Name | Type | Description |
|---|---|---|
config | Mintlify.Core.Models.DocsJsonConfig | The configuration object to load. Cannot be null. |
Remarks
This method replaces any existing configuration and clears previous configuration errors. After loading, the configuration is validated and navigation groups are cleaned to ensure consistency.Merge
Merges another docs.json configuration into the current configuration.Syntax
Parameters
| Name | Type | Description |
|---|---|---|
other | Mintlify.Core.Models.DocsJsonConfig | The configuration to merge into the current one. |
combineBaseProperties | bool | If true, merges base properties; if false, only merges navigation. |
options | Mintlify.Core.Models.MergeOptions? | Optional merge options to control merge behavior. When null, default behavior is used. |
Exceptions
| Exception | Description |
|---|---|
ArgumentNullException | Thrown when other is null. |
InvalidOperationException | Thrown when no configuration is loaded. |
Remarks
This method performs a shallow merge, with the other configuration taking precedence for non-null values. Navigation structures are combined intelligently.MergeNavigation
Merges navigation from another NavigationConfig into the current configuration’s navigation.Syntax
Parameters
| Name | Type | Description |
|---|---|---|
sourceNavigation | Mintlify.Core.Models.NavigationConfig | The navigation configuration to merge from. |
options | Mintlify.Core.Models.MergeOptions? | Optional merge options to control merge behavior. |
Exceptions
| Exception | Description |
|---|---|
ArgumentNullException | Thrown when sourceNavigation is null. |
InvalidOperationException | Thrown when no configuration is loaded. |
Remarks
This method intelligently merges navigation structures, combining groups with the same name and deduplicating page references. Use the MergeOptions parameter to control specific behaviors like how empty groups are handled.MergeNavigation
Merges navigation from an existing docs.json file into the current configuration.Syntax
Parameters
| Name | Type | Description |
|---|---|---|
filePath | string | The path to the docs.json file containing navigation to merge. |
options | Mintlify.Core.Models.MergeOptions? | Optional merge options to control merge behavior. |
Exceptions
| Exception | Description |
|---|---|
ArgumentException | Thrown when filePath is null or whitespace. |
InvalidOperationException | Thrown when no configuration is loaded. |
FileNotFoundException | Thrown when the specified file does not exist. |
Remarks
This method loads navigation from an external docs.json file and merges it into the current configuration. Only the navigation structure is merged; other configuration properties are not affected.PopulateNavigationFromPath
Populates the navigation structure from a directory path by scanning for MDX files.Syntax
Parameters
| Name | Type | Description |
|---|---|---|
path | string | The directory path to scan for documentation files. |
fileExtensions | string[]? | The file extensions to include (defaults to .mdx only). |
includeApiReference | bool | Whether to include the ‘api-reference’ directory in discovery (defaults to false). |
preserveExisting | bool | Whether to preserve existing navigation structure and merge discovered content (defaults to true). |
allowDuplicatePaths | bool | If true, allows adding duplicate paths; otherwise, skips duplicates. |
Exceptions
| Exception | Description |
|---|---|
ArgumentException | Thrown when path is null or whitespace. |
InvalidOperationException | Thrown when no configuration is loaded. |
DirectoryNotFoundException | Thrown when the specified path does not exist. |
Remarks
This method scans the specified directory recursively and builds a navigation structure based on the folder hierarchy and MDX files found. The method includes several advanced features: The method preserves the directory structure in the navigation while applying these intelligent processing rules to create clean, organized documentation.Save
Saves the current configuration to the file system using the original file path.Syntax
Exceptions
| Exception | Description |
|---|---|
InvalidOperationException | Thrown when no configuration is loaded or no file path is specified. |
Save
Saves the current configuration to the specified file path.Syntax
Parameters
| Name | Type | Description |
|---|---|---|
filePath | string | The file path where the configuration should be saved. |
Exceptions
| Exception | Description |
|---|---|
ArgumentException | Thrown when filePath is null or whitespace. |
InvalidOperationException | Thrown when no configuration is loaded. |