Documentation Collections

When combining multiple documentation projects into a unified site, the Mintlify provider goes beyond simple file copying. It automatically restructures content, relocates shared resources, and rewrites internal paths to ensure everything works seamlessly together.

The Challenge

Documentation projects (especially Mintlify-targeted ones) are typically designed as standalone sites. They reference images, snippets, and internal pages using absolute paths like /images/logo.png or /guides/quickstart. When you combine multiple projects, these paths collide:

Without intelligent handling

/images/logo.png      <- Which project's logo?
/snippets/Hero.jsx    <- Which project's component?
/guides/quickstart    <- Which project's guide?

How Mintlify Collections Work

The MintlifyDocReferenceHandler solves this by performing three key operations during the build process:

Resource Relocation

Shared resource directories (images/, snippets/) are moved to central locations with project-specific namespacing:

/images/{DestinationPath}/logo.png
/snippets/{DestinationPath}/Hero.jsx

Content Path Rewriting

All absolute paths in MDX files are automatically rewritten to reference the relocated resources and prefixed pages:

Original Path	Rewritten Path
`/images/logo.png`	`/images/product-1/logo.png`
`/snippets/Hero.jsx`	`/snippets/product-1/Hero.jsx`
`/guides/quickstart`	`/product-1/guides/quickstart`

Navigation Integration

The referenced project’s navigation is merged into the parent’s docs.json, appearing as a Tab or Product based on your configuration.

Supported Path Patterns

The handler rewrites paths in all common MDX patterns:

ES Imports
Markdown Links & Images
JSX Attributes
CSS url()

// Before
import { Hero } from '/snippets/Hero.jsx';

// After
import { Hero } from '/snippets/product-1/Hero.jsx';

// Before
![Logo](/images/logo.png)
[Getting Started](/guides/quickstart)

// After
![Logo](/images/product-1/logo.png)
[Getting Started](/product-1/guides/quickstart)

// Before
<Card href="/guides/intro" />
<img src="/images/banner.png" />

// After
<Card href="/product-1/guides/intro" />
<img src="/images/product-1/banner.png" />

// Before
<div style={{backgroundImage: 'url(/images/bg.svg)'}} />

// After
<div style={{backgroundImage: 'url(/images/product-1/bg.svg)'}} />

Paths inside fenced code blocks are not rewritten, ensuring your documentation examples remain accurate.

Output Structure

After processing, your collection has a clean, conflict-free structure:

docs/
├── docs.json                    # Unified navigation
├── index.mdx                    # Collection landing page
├── images/
│   ├── collection-logo.png      # Collection's own images
│   ├── product-1/               # Product 1's images
│   │   ├── logo.png
│   │   └── screenshots/
│   │       └── demo.png
│   └── product-2/               # Product 2's images
│       └── banner.png
├── snippets/
│   ├── SharedComponent.jsx      # Collection's components
│   ├── product-1/               # Product 1's snippets
│   │   └── Hero.jsx
│   └── product-2/               # Product 2's snippets
│       └── Features.jsx
├── product-1/                   # Product 1's content
│   ├── index.mdx
│   └── guides/
│       └── quickstart.mdx
└── product-2/                   # Product 2's content
    ├── index.mdx
    └── api/
        └── overview.mdx

Configuration Example

MyPlatform.docsproj

<Project Sdk="DotNetDocs.Sdk/1.2.0">
  <PropertyGroup>
    <DocumentationType>Mintlify</DocumentationType>
    <MintlifyTemplate>
      <Name>My Platform</Name>
      <Theme>maple</Theme>
      <Navigation Mode="Unified" Type="Tabs" Name="Platform">
        <Pages>
          <Groups>
            <Group Name="Getting Started" Icon="rocket">
              <Pages>index;quickstart</Pages>
            </Group>
          </Groups>
        </Pages>
      </Navigation>
    </MintlifyTemplate>
  </PropertyGroup>

  <ItemGroup>
    <DocumentationReference
      Include="..\Product1\Product1.Docs.docsproj"
      DestinationPath="product-1"
      IntegrationType="Tabs"
      Name="Product 1" />

    <DocumentationReference
      Include="..\Product2\Product2.Docs.docsproj"
      DestinationPath="product-2"
      IntegrationType="Tabs"
      Name="Product 2" />
  </ItemGroup>
</Project>

Best Practices

Use Descriptive Destination Paths

Choose short, URL-friendly names like product-1 rather than full project names. These become part of every URL in the referenced content.

Organize Shared Resources

Keep images and snippets in their respective directories. The handler specifically looks for images/ and snippets/ folders to relocate.

Test Path References

After building, verify that imports, images, and links resolve correctly. Check the browser console for 404 errors.

Keep Code Examples Accurate

Since code blocks aren’t rewritten, your documentation examples will show the original paths - which is usually what you want for copy-paste accuracy.

Comparison with Base Markdown

The Mintlify handler extends the base MarkdownDocReferenceHandler with additional patterns:

Feature	Markdown Handler	Mintlify Handler
Markdown images	Yes	Yes
Markdown links	Yes	Yes
ES imports	No	Yes
JSX src/href	No	Yes
CSS url()	No	Yes
.mdx files	No	Yes

Collections Guide

Complete guide to Documentation Collections including configuration, integration types, and troubleshooting

DocumentationReference

Complete reference for the DocumentationReference tag and its properties

Navigation Generation

Learn how navigation from multiple projects is merged

Getting Started

Guides

Providers

Plugins

Learnings

API Reference

Documentation Collections

The Challenge

How Mintlify Collections Work

Supported Path Patterns

Output Structure

Configuration Example

Best Practices

Use Descriptive Destination Paths

Organize Shared Resources

Test Path References

Keep Code Examples Accurate

Comparison with Base Markdown

See Also

Collections Guide

DocumentationReference

Navigation Generation

​The Challenge

​How Mintlify Collections Work

​Supported Path Patterns

​Output Structure

​Configuration Example

​Best Practices

Use Descriptive Destination Paths

Organize Shared Resources

Test Path References

Keep Code Examples Accurate

​Comparison with Base Markdown

​See Also

Collections Guide

DocumentationReference

Navigation Generation

The Challenge

How Mintlify Collections Work

Supported Path Patterns

Output Structure

Configuration Example

Best Practices

Comparison with Base Markdown

See Also