Conceptual Documentation

What is Conceptual Documentation?

Conceptual Documentation is DotNetDocs’ system for enriching API reference documentation with rich, context-aware content that goes beyond what XML documentation comments can provide. While XML comments describe what an API element is, conceptual documentation explains how to use it effectively. Conceptual documentation is inspired by best practices from major documentation platforms like Microsoft Learn, Read the Docs, and Mintlify. It brings the power of rich, structured content to your .NET projects. Conceptual content is stored in separate .mdz files organized alongside your code, allowing technical writers and developers to collaborate on comprehensive documentation without cluttering source files.

The .mdz file extension was chosen to avoid being picked up by documentation platforms that autiomatically look for .md or .mdx files. It does not stand for anything in particular, except that if you have the file index.md and index.mdx and index.mdz in the same folder, the index.mdz file will appear last in the list.

How Conceptual Documentation Works

DotNetDocs follows a two-phase documentation pipeline:

XML Extraction

The AssemblyManager extracts documentation from XML comments in your compiled assemblies, populating basic API metadata like summaries, remarks, parameters, and return values.

Conceptual Loading

The DocumentationManager loads conceptual content from .mdz files in the configured ConceptualPath directory, enriching the documentation model with usage guides, examples, best practices, patterns, and considerations.

These two content sources are merged into a unified documentation model that renderers (like MintlifyRenderer) transform into beautiful, comprehensive documentation sites.

Configuration

Enabling Conceptual Documentation

Conceptual documentation is enabled by default in ProjectContext:

var context = new ProjectContext
{
    ConceptualPath = "conceptual",           // Where .mdz files are stored
    ConceptualDocsEnabled = true,            // Enable conceptual docs (default: true)
    ShowPlaceholders = true                  // Show placeholder content (default: true)
};

Configuration Properties

string

default:"conceptual"

The directory where conceptual documentation files (.mdz) are stored, relative to the documentation root.

bool

default:"true"

When true, DotNetDocs generates placeholder files for new types and loads existing conceptual content. When false, only XML comments are processed.

bool

default:"true"

Controls whether placeholder content is included in the final documentation. See Placeholders section below.

Conceptual Documentation Sections

DotNetDocs supports seven distinct conceptual sections, each with a specific purpose. These sections are available at three levels: namespace, type, and member.

Available Sections

Summary

File: summary.mdz Level: Namespace only Purpose: Brief description of what the namespace contains and its purposeThis section is only available at the namespace level since types and members already have summaries from XML <summary> tags.

<!-- summary.mdz -->
This namespace contains core documentation processing types including assembly management,
entity models, and the transformation pipeline.

Usage

File: usage.mdz Level: Namespace, Type, Member Purpose: Explains how to use the API elementUsage documentation provides step-by-step guides for common scenarios. This is where you explain HOW developers should interact with your API.

<!-- usage.mdz -->
## Basic Usage

To use the `DocumentationManager`, first create a `ProjectContext`:

1. Configure your project context with references
2. Create the manager with enrichers, transformers, and renderers
3. Call `ProcessAsync()` with your assembly paths

The manager orchestrates the entire documentation pipeline automatically.

Examples

File: examples.mdz Level: Namespace, Type, Member Purpose: Concrete code examples showing the API in actionExamples should be complete, runnable code snippets that demonstrate real-world usage patterns.

<!-- examples.mdz -->
## Basic Example

```csharp
var context = new ProjectContext
{
    ConceptualPath = "conceptual",
    ShowPlaceholders = false
};

var manager = new DocumentationManager(context);
await manager.ProcessAsync("MyAssembly.dll", "MyAssembly.xml");

Advanced Example

// Multi-assembly processing with custom configuration
var assemblies = new[]
{
    ("Core.dll", "Core.xml"),
    ("Extensions.dll", "Extensions.xml")
};

await manager.ProcessAsync(assemblies);

</Accordion>

<Accordion title="Best Practices" icon="star">
**File**: `best-practices.mdz`
**Level**: Namespace, Type, Member
**Purpose**: Recommendations for effective usage

Best practices guide developers toward optimal usage patterns and away from common pitfalls.

```markdown
<!-- best-practices.mdz -->
## Best Practices

- Always dispose of `DocumentationManager` when done to free assembly manager resources
- Use dependency injection containers to manage enricher and renderer lifecycles
- Set `ShowPlaceholders = false` for production documentation builds
- Cache `ProjectContext` instances when processing multiple assemblies

Patterns

File: patterns.mdz Level: Namespace, Type, Member Purpose: Common usage patterns and architectural guidancePatterns documentation explains recurring solutions and architectural approaches.

<!-- patterns.mdz -->
## Pipeline Pattern

The DocumentationManager implements a pipeline pattern with three stages:

1. **Enrichment**: Add metadata from external sources
2. **Transformation**: Modify the documentation model
3. **Rendering**: Generate output formats

Each stage operates on the complete model, allowing cross-assembly transformations.

Considerations

File: considerations.mdz Level: Namespace, Type, Member Purpose: Important notes, gotchas, performance, and security considerationsThis section highlights important things developers need to know before using the API.

<!-- considerations.mdz -->
## Performance Considerations

- Assembly loading is expensive; use `GetOrCreateAssemblyManager` for caching
- Conceptual file loading happens in parallel per assembly for better performance
- Large assemblies may benefit from setting `ConceptualDocsEnabled = false`

## Security Considerations

- Assembly reflection can trigger code execution; only process trusted assemblies
- File system access requires appropriate permissions for conceptual paths

File: related-apis.mdz Level: Type, Member Purpose: List of related API elementsRelated APIs are specified as one API per line in the markdown file. The renderer formats these appropriately.

<!-- related-apis.mdz -->
CloudNimble.DotNetDocs.Core.AssemblyManager
CloudNimble.DotNetDocs.Core.ProjectContext
CloudNimble.DotNetDocs.Core.IDocRenderer
CloudNimble.DotNetDocs.Core.IDocEnricher

File Organization

Conceptual documentation files follow a hierarchical folder structure that mirrors your code organization:

conceptual/
├── YourNamespace/
│   ├── summary.mdz                    # Namespace summary
│   ├── usage.mdz                      # Namespace usage guide
│   ├── examples.mdz                   # Namespace examples
│   ├── YourClass/
│   │   ├── usage.mdz                  # Type usage guide
│   │   ├── examples.mdz               # Type examples
│   │   ├── best-practices.mdz         # Type best practices
│   │   ├── patterns.mdz               # Type patterns
│   │   ├── considerations.mdz         # Type considerations
│   │   ├── related-apis.mdz           # Type related APIs
│   │   ├── YourMethod/
│   │   │   ├── usage.mdz              # Member usage guide
│   │   │   ├── examples.mdz           # Member examples
│   │   │   ├── best-practices.mdz     # Member best practices
│   │   │   ├── patterns.mdz           # Member patterns
│   │   │   ├── considerations.mdz     # Member considerations
│   │   │   └── related-apis.mdz       # Member related APIs
│   │   └── YourProperty/
│   │       └── usage.mdz              # Member usage guide
│   └── AnotherClass/
│       └── usage.mdz
└── AnotherNamespace/
    └── usage.mdz

Path Construction

The DocumentationManager constructs file paths based on the fully qualified names of your types:

Namespace: conceptual/{Namespace}/
Type: conceptual/{Namespace}/{TypeName}/
Member: conceptual/{Namespace}/{TypeName}/{MemberName}/

Dots in namespace names are converted to directory separators. For example, System.Text.Json becomes conceptual/System/Text/Json/.

Placeholders and the ShowPlaceholders Property

When ConceptualDocsEnabled = true, DotNetDocs automatically generates placeholder files for any conceptual sections that don’t exist yet. These placeholders help you identify documentation gaps and provide a starting point for writing.

Placeholder Format

Placeholder files include a special TODO comment marker:

<!-- TODO: REMOVE THIS COMMENT AFTER YOU CUSTOMIZE THIS CONTENT -->
# Usage

Describe how to use `DocumentationManager` here.

Consider including:
- Step-by-step instructions
- Common scenarios
- Configuration options

Controlling Placeholder Visibility

The ShowPlaceholders property controls whether placeholder content appears in your final documentation:

Development Mode
Production Mode

var context = new ProjectContext
{
    ShowPlaceholders = true  // Default
};

When to use: During development to see documentation gaps and track progress.Result: All conceptual content loads, including placeholders. You’ll see placeholder sections in your generated documentation.

var context = new ProjectContext
{
    ShowPlaceholders = false
};

When to use: For production documentation builds where you only want to show completed content.Result: Files containing the TODO comment marker are skipped during loading. Only customized content appears in documentation.

How Placeholder Detection Works

The DocumentationManager.IsTodoPlaceholderFile() method checks if a file starts with the TODO marker:

internal static bool IsTodoPlaceholderFile(string content)
{
    if (string.IsNullOrWhiteSpace(content))
        return false;

    var regex = new Regex(
        @"^\s*<!--\s*TODO:\s*REMOVE\s+THIS\s+COMMENT\s+AFTER\s+YOU\s+CUSTOMIZE\s+THIS\s+CONTENT\s*-->\s*$",
        RegexOptions.IgnoreCase
    );

    // Check first non-empty line
    foreach (var line in content.Split('\n'))
    {
        var trimmed = line.Trim();
        if (!string.IsNullOrWhiteSpace(trimmed))
            return regex.IsMatch(trimmed);
    }

    return false;
}

The TODO marker must be on the first non-empty line of the file to be recognized as a placeholder. Once you start customizing content, delete the TODO comment so DotNetDocs knows the file contains real documentation.

Using Markdown to Override Titles

Conceptual documentation files support full Markdown syntax, including headers. Renderers respect the structure of your Markdown, allowing you to override default section titles and organize content hierarchically.

Default Titles

By default, renderers use section names as titles:

<!-- usage.mdz -->
Describe how to use this API...

Rendered as: A section titled “Usage” with your content

Custom Titles with Markdown Headers

Add your own headers to customize the title and create subsections:

<!-- usage.mdz -->
## Getting Started with DocumentationManager

The `DocumentationManager` orchestrates the documentation pipeline...

### Basic Configuration

First, create a `ProjectContext`:

### Processing Assemblies

Call `ProcessAsync()` with your assembly paths:

Rendered as: Custom “Getting Started with DocumentationManager” title with “Basic Configuration” and “Processing Assemblies” subsections

Multi-Level Organization

Create deep hierarchies for complex topics:

<!-- patterns.mdz -->
## Architectural Patterns

The DocumentationManager supports several patterns:

### Pipeline Pattern

#### Enrichment Stage
Enrichers add metadata from external sources...

#### Transformation Stage
Transformers modify the documentation model...

#### Rendering Stage
Renderers generate output formats...

### Factory Pattern

The `GetOrCreateAssemblyManager` method implements a factory pattern...

Best Practices for Markdown Headers

Use Semantic Levels

Start with ## (H2) for main titles and nest logically with ### (H3) and #### (H4) for subsections.

Be Consistent

Use the same header style across all conceptual files in your project for a cohesive documentation experience.

Avoid H1

Reserve # (H1) for page titles. Start conceptual content with ## (H2) to maintain proper document hierarchy.

Include Code Fences

Use proper code fences with language identifiers for syntax highlighting: ```csharp

Including HTML and Components with `noescape`

Conceptual documentation often needs to include rich HTML content, JSX components, or other markup that should not be escaped. DotNetDocs provides the ```noescape code fence specifically for this purpose.

The Problem: HTML Gets Escaped

By default, the MarkdownXmlTransformer escapes HTML tags in your conceptual content to prevent conflicts with Markdown rendering. This is useful for XML documentation comments, but problematic when you want to include actual HTML or components:

<!-- This HTML will be escaped -->
<Note>
  This is a note component
</Note>

<!-- Renders as: &lt;Note&gt; This is a note component &lt;/Note&gt; -->

The Solution: `noescape` Code Fences

The noescape code fence tells the transformer to pass content through without escaping and without code fence markers:

<!-- usage.mdz -->
```noescape
<Note>
  This is a note component that will render correctly!
</Note>
```

Result: The HTML content is included in the output exactly as written, allowing components to render properly.

How It Works

When the MarkdownXmlTransformer processes conceptual content:

Regular content: HTML tags are escaped (< → <, > → >)
Code fences: Content is preserved with backticks for syntax highlighting
noescape fences: Content is extracted and passed through unchanged

From MarkdownXmlTransformer.cs:750-773:

var isNoEscape = text.IndexOf("noescape", fenceStart, Math.Min(20, text.Length - fenceStart),
    StringComparison.Ordinal) == fenceStart;

if (isNoEscape)
{
    // Extract content without delimiters and without escaping
    var contentStart = fenceStart + 8; // "noescape" is 8 chars
    if (contentStart < text.Length && text[contentStart] == '\r') contentStart++;
    if (contentStart < text.Length && text[contentStart] == '\n') contentStart++;

    var content = text.Substring(contentStart, closingPos - contentStart);
    result.Append(content);
}

Use Cases

Mintlify Components

Include Mintlify’s special components in your conceptual documentation:

<!-- usage.mdz -->
## Configuration Options

```noescape
<ParamField path="ConceptualPath" type="string" default="conceptual">
  The directory where conceptual documentation files are stored.
</ParamField>

<ParamField path="ShowPlaceholders" type="bool" default="true">
  Controls whether placeholder content is included in documentation.
</ParamField>
```

Custom HTML Components

Embed custom HTML when your renderer supports it:

<!-- examples.mdz -->
## Interactive Demo

```noescape
<div class="demo-container">
  <button onclick="runDemo()">Try It</button>
  <div id="output"></div>
</div>

<script>
  function runDemo() {
    document.getElementById('output').innerText = 'Demo running!';
  }
</script>
```

Warning and Info Boxes

Use callout components without worrying about escaping:

<!-- considerations.mdz -->
## Performance Considerations

```noescape
<Warning>
  Assembly loading is expensive. Cache `AssemblyManager` instances when processing multiple assemblies.
</Warning>

<Info>
  Set `ConceptualDocsEnabled = false` to skip placeholder generation and improve performance.
</Info>
```

Tabs and Steps

Create multi-step guides with structured components:

<!-- usage.mdz -->
## Setup Process

```noescape
<Steps>
  <Step title="Create Context">
    Configure your `ProjectContext` with the required settings.
  </Step>

  <Step title="Initialize Manager">
    Create a `DocumentationManager` with enrichers and renderers.
  </Step>

  <Step title="Process Assemblies">
    Call `ProcessAsync()` with your assembly paths.
  </Step>
</Steps>
```

Best Practices

Verify Component Support

Ensure your renderer (e.g., MintlifyRenderer) supports the components you’re using. noescape only prevents escaping—rendering is up to your output format.

One Component Per Fence

For clarity, use separate noescape blocks for distinct components rather than grouping multiple components together.

Validate HTML

The transformer doesn’t validate HTML. Ensure your markup is well-formed to avoid rendering issues.

Mix with Markdown

You can freely mix noescape blocks with regular Markdown content in the same file—only the content inside noescape fences is unescaped.

Example: Complete Conceptual File

Here’s a real-world example mixing Markdown and components:

<!-- TODO: REMOVE THIS COMMENT AFTER YOU CUSTOMIZE THIS CONTENT -->
## Using the DocumentationManager

The `DocumentationManager` orchestrates the entire documentation pipeline, from assembly loading through final output generation.

### Basic Setup

First, create and configure a `ProjectContext`:

```csharp
var context = new ProjectContext
{
    ConceptualPath = "conceptual",
    ShowPlaceholders = false,
    OutputPath = "docs"
};
```

### Configuration Options

```noescape
<ParamField path="ConceptualPath" type="string" default="conceptual">
  Directory where `.mdz` conceptual files are stored, relative to the documentation root.
</ParamField>

<ParamField path="ShowPlaceholders" type="bool" default="true">
  When `false`, placeholder files with TODO markers are excluded from output.
</ParamField>
```

### Processing Assemblies

```noescape
<Steps>
  <Step title="Load Assembly">
    The manager loads your compiled assembly and XML documentation.
  </Step>

  <Step title="Generate Placeholders">
    Missing conceptual files are created automatically (if enabled).
  </Step>

  <Step title="Transform Content">
    XML documentation is converted to Markdown format.
  </Step>

  <Step title="Render Output">
    Final documentation is generated in your chosen format.
  </Step>
</Steps>
```

### Important Considerations

```noescape
<Warning>
  Assembly reflection can trigger code execution. Only process assemblies from trusted sources.
</Warning>
```

Technical Details

The noescape feature is implemented in the EscapeRemainingXmlTags method of MarkdownXmlTransformer:

Detection: Checks for noescape immediately after the opening ``` (within the first 20 characters)
Extraction: Skips the noescape keyword and any following newline, then extracts content up to the closing ```
Processing: Appends the content directly to the output without modifications
Preservation: Regular code fences and inline code (single backticks) are preserved with their delimiters

The noescape functionality only applies to conceptual documentation properties that go through the MarkdownXmlTransformer. It does not affect XML documentation comments, which always have HTML escaped for safety.

Creating Conceptual Documentation

Automatic Placeholder Generation

When you process an assembly with ConceptualDocsEnabled = true, DotNetDocs automatically creates placeholder files:

var context = new ProjectContext
{
    ConceptualPath = "conceptual",
    ConceptualDocsEnabled = true
};

var manager = new DocumentationManager(context);

// This generates placeholder files for all types and members
await manager.ProcessAsync("MyAssembly.dll", "MyAssembly.xml");

After running, you’ll find a complete folder structure in your conceptual/ directory with placeholders for all sections.

Manual Placeholder Generation

Generate placeholders without running the full pipeline:

// Only create placeholder files, don't run full pipeline
await manager.CreateConceptualFilesAsync("MyAssembly.dll", "MyAssembly.xml");

// For multiple assemblies
await manager.CreateConceptualFilesAsync(new[]
{
    ("Core.dll", "Core.xml"),
    ("Extensions.dll", "Extensions.xml")
});

Customizing Conceptual Content

To customize a placeholder:

Open the .mdz file in your preferred Markdown editor
Delete the TODO comment from the first line
Replace the placeholder content with your documentation
Save the file

The next time you process your assembly, DotNetDocs will load your customized content instead of the placeholder.

Workflow Example

Here’s a complete workflow for adding conceptual documentation to a project:

Generate Placeholders

var context = new ProjectContext
{
    ConceptualPath = "conceptual",
    ShowPlaceholders = true
};

var manager = new DocumentationManager(context);
await manager.CreateConceptualFilesAsync("MyLib.dll", "MyLib.xml");

Review Generated Structure

# Examine the generated folder structure
ls -R conceptual/

conceptual/MyNamespace/MyClass/
├── usage.mdz
├── examples.mdz
├── best-practices.mdz
├── patterns.mdz
├── considerations.mdz
└── related-apis.mdz

Customize Priority Sections

Edit the most important conceptual files first (usually usage.mdz and examples.mdz), removing the TODO comments and adding your content.

Process and Preview

// Process with placeholders visible to see progress
await manager.ProcessAsync("MyLib.dll", "MyLib.xml");

Review the generated documentation to see which sections still need content.

Production Build

// Hide placeholders for production
context.ShowPlaceholders = false;
await manager.ProcessAsync("MyLib.dll", "MyLib.xml");

Only customized content appears in the final documentation.

Advanced Scenarios

Partial Documentation

You don’t need to fill in all seven sections for every API element. Only create the files that add value:

conceptual/
└── MyNamespace/
    └── MyClass/
        ├── usage.mdz              # Comprehensive usage guide
        └── examples.mdz           # Lots of examples
        # No best-practices.mdz - not needed for this simple class

Shared Content with Includes

Some renderers (like MintlifyRenderer) support includes for reusing content across multiple files:

<!-- usage.mdz -->
<Snippet file="common/setup-instructions.mdx" />

## Using MyClass

Now that you've completed setup, you can use MyClass...

Multi-Assembly Projects

When documenting multiple assemblies, organize conceptual content by assembly:

conceptual/
├── MyProject.Core/
│   └── CoreNamespace/
│       └── CoreClass/
│           └── usage.mdz
└── MyProject.Extensions/
    └── ExtensionsNamespace/
        └── ExtensionClass/
            └── usage.mdz

Then process assemblies together:

await manager.ProcessAsync(new[]
{
    ("MyProject.Core.dll", "MyProject.Core.xml"),
    ("MyProject.Extensions.dll", "MyProject.Extensions.xml")
});

Integration with the Pipeline

Conceptual content integrates seamlessly with DotNetDocs’ transformation pipeline:

var manager = new DocumentationManager(
    context,
    enrichers: new IDocEnricher[] { /* enrichers */ },
    transformers: new IDocTransformer[] { /* transformers */ },
    renderers: new IDocRenderer[] { new MintlifyRenderer(context) }
);

await manager.ProcessAsync("MyLib.dll", "MyLib.xml");

Pipeline execution order:

Extract XML: Load API metadata from XML comments
Generate Placeholders: Create missing conceptual files (if enabled)
Load Conceptual: Load conceptual content from .mdz files
Merge Models: Combine multiple assemblies if needed
Enrich: Run enrichers to add external metadata
Transform: Run transformers to modify the model
Render: Generate final documentation output

Conceptual content is loaded after placeholder generation but before enrichers and transformers run, allowing the entire pipeline to work with the complete documentation model.

Pipeline Overview

Learn about the complete documentation pipeline

Mintlify Provider

See how conceptual content renders in Mintlify

Placeholder Handling Spec

Technical specification for placeholder handling

Core Documentation Spec

Complete XML and conceptual mapping reference

​What is Conceptual Documentation?

​How Conceptual Documentation Works

​Configuration

​Enabling Conceptual Documentation

​Configuration Properties

​Conceptual Documentation Sections

​Available Sections

​Advanced Example

​File Organization

​Path Construction

​Placeholders and the ShowPlaceholders Property

​Placeholder Format

​Controlling Placeholder Visibility

​How Placeholder Detection Works

​Using Markdown to Override Titles

​Default Titles

​Custom Titles with Markdown Headers

​Multi-Level Organization

​Best Practices for Markdown Headers

Use Semantic Levels

Be Consistent

Avoid H1

Include Code Fences

​Including HTML and Components with noescape

​The Problem: HTML Gets Escaped

​The Solution: noescape Code Fences

​How It Works

​Use Cases

​Best Practices

Verify Component Support

One Component Per Fence

Validate HTML

Mix with Markdown

​Example: Complete Conceptual File

​Technical Details

​Creating Conceptual Documentation

​Automatic Placeholder Generation

​Manual Placeholder Generation

​Customizing Conceptual Content

​Workflow Example

​Advanced Scenarios

​Partial Documentation

​Shared Content with Includes

​Multi-Assembly Projects

​Integration with the Pipeline

​See Also

Pipeline Overview

Mintlify Provider

Placeholder Handling Spec

Core Documentation Spec

What is Conceptual Documentation?

How Conceptual Documentation Works

Configuration

Enabling Conceptual Documentation

Configuration Properties

Conceptual Documentation Sections

Available Sections

Advanced Example

File Organization

Path Construction

Placeholders and the ShowPlaceholders Property

Placeholder Format

Controlling Placeholder Visibility

How Placeholder Detection Works

Using Markdown to Override Titles

Default Titles

Custom Titles with Markdown Headers

Multi-Level Organization

Best Practices for Markdown Headers

Including HTML and Components with `noescape`

The Problem: HTML Gets Escaped

The Solution: `noescape` Code Fences

How It Works

Use Cases

Best Practices

Example: Complete Conceptual File

Technical Details

Creating Conceptual Documentation

Automatic Placeholder Generation

Manual Placeholder Generation

Customizing Conceptual Content

Workflow Example

Advanced Scenarios

Partial Documentation

Shared Content with Includes

Multi-Assembly Projects

Integration with the Pipeline

See Also