---
title: Next.js MDX content collections for AI-readable docs
description: Configure a local MDX content collection in Next.js, map files to routes, add useful frontmatter, and generate llms.txt, page Markdown, and JSON-LD.
canonical_url: https://nextaiready.com/en/docs/guides/mdx-content
url: https://nextaiready.com/en/docs/guides/mdx-content
last_updated: 2026-10-01
updated: 2026-10-01
author: next-ai-ready team
summary: Configure a local MDX content collection in Next.js, map files to routes, add useful frontmatter, and generate llms.txt, page Markdown, and JSON-LD.
topics: [nextjs, mdx, content-collections, frontmatter, llms.txt, ai-readable-docs]
---

# Next.js MDX content collections for AI-readable docs

An MDX content collection is a directory of Markdown or MDX source files that share a predictable schema and route convention. In a Next.js project, next-ai-ready can read that collection at build time and generate `llms.txt`, per-page Markdown, JSON-LD, and a searchable semantic graph without replacing the UI that already renders the content.

The minimal workflow is:

1. Keep the source `.md` or `.mdx` files in the repository.
2. Initialize the integration and match those files with `content` globs in `ai-ready.config.*`.
3. Add clear frontmatter and direct answers to each page.
4. Run `next-ai-ready build` and verify the generated routes.

## Create a local MDX collection

From an existing Next.js App Router project, install and initialize the integration once:

```bash
pnpm add next-ai-ready
pnpm exec next-ai-ready init
```

Skip `init` if the project already has the AI handlers and `withAiReady()` wiring. A content
configuration alone lets the CLI build artifacts, but does not install the runtime Markdown routes.

A small documentation collection can use this structure:

```text
content/
  docs/
    introduction.mdx
    installation.mdx
    deployment.mdx
```

For the endpoint check below, create `content/docs/installation.mdx` with this content:

```markdown
---
title: Install Acme
summary: Install dependencies for an existing Acme checkout.
---

# Install Acme

Run `pnpm install` from the application root to install the dependencies.
```

Edit the generated `ai-ready.config.ts` (TypeScript) or `ai-ready.config.mjs` (JavaScript) to scan
the source collection. Use the existing file rather than creating a second config:

```js
// ai-ready.config.ts or ai-ready.config.mjs
import { defineConfig } from "next-ai-ready"

export default defineConfig({
  site: {
    name: "Acme Docs",
    baseUrl: "https://docs.example.com",
  },
  content: ["content/docs/**/*.{md,mdx}"],
})
```

Use the source files, not JavaScript generated by another content tool. That keeps URLs, authorship, and Markdown output tied to material a maintainer can review.

## Add frontmatter that survives every output

Start with a small schema that is useful in HTML, search results, and machine-readable artifacts:

```yaml
---
title: Deploy Acme on Vercel
summary: Build and deploy the Acme Next.js app, then verify its public health endpoint.
updatedAt: 2026-09-26
author: Acme engineering
tags:
  - nextjs
  - vercel
  - deployment
questions:
  - q: Which command creates the production build?
    a: Run pnpm build from the application root.
---
```

| Field       | Use it for                                                     |
| ----------- | -------------------------------------------------------------- |
| `title`     | Page heading, `llms.txt`, JSON-LD, and search result title.    |
| `summary`   | Search description, page discovery, and concise agent context. |
| `updatedAt` | Visible freshness and `dateModified` metadata.                 |
| `author`    | Authorship in generated structured data.                       |
| `tags`      | Topics used by the semantic graph and page search.             |
| `questions` | Direct answers and optional `FAQPage` JSON-LD.                 |

Only publish metadata the visible page supports. A large generated FAQ block does not make thin content more useful.

## Understand route mapping

The default filesystem source derives a route from each matched path. Directories named `app`, `src/app`, `content`, and `src/content` are treated as source roots.

| Source file                        | Generated route         |
| ---------------------------------- | ----------------------- |
| `content/index.mdx`                | `/`                     |
| `content/docs/installation.mdx`    | `/docs/installation`    |
| `content/en/docs/installation.mdx` | `/en/docs/installation` |

Run the build and inspect the graph before deployment:

```bash
pnpm exec next-ai-ready build
pnpm exec next-ai-ready doctor --score
```

The mapping is ready when it appears in `public/llms.txt` and `.next-ai-ready/graph.json` with the
expected canonical URL. Creating files under `content/` does not create browser pages; your
existing MDX renderer must serve the corresponding HTML routes.

## Use an existing MDX stack

next-ai-ready is a machine-facing build layer, not a replacement for the component system that renders your pages.

- **Next.js with `@next/mdx`:** include routed MDX files with an `app/**/*.{md,mdx}` glob.
- **A local content collection:** scan the original `content/**/*.{md,mdx}` files.
- **Fumadocs:** keep its source configuration and follow the [Fumadocs integration guide](./fumadocs-ai-ready).
- **Nextra:** keep Nextra's theme and routing, then follow the [Nextra integration guide](./nextra-ai-ready).
- **Generated collection tools:** scan the original MDX directory instead of a generated `.content` or JavaScript output directory.

If the browser UI and the source collection use different route rules, add a custom content source adapter instead of publishing incorrect canonical URLs.

## Add semantic details when they are real

Frontmatter is enough for most pages. A code-owned source can also pass richer semantic data to the
compiler:

```ts
export const semantic = {
  topics: ["install", "quickstart", "pnpm"],
  questions: [
    { q: "How do I install Acme?", a: "Run `pnpm add acme`." },
  ],
  entities: [
    { name: "pnpm", type: "tool", url: "https://pnpm.io" },
  ],
}
```

The compiler extracts headings, sections, FAQs, entities, and token-aware chunks deterministically. It does not call an external model or require a database.

## Verify the public result

`init` adds `next-ai-ready build` to the app's build script. Build the app and start the production
server:

```bash
pnpm build
pnpm start
```

In another terminal, check the file created above:

```bash
curl -i http://localhost:3000/llms.txt
curl -i http://localhost:3000/docs/installation.md
```

Expect `200` and `Content-Type: text/markdown` for the page, with the `Install Acme` title and its
dependency-installation instructions, not a missing-page recovery document. If the UI serves
`/docs/installation`, check that its normal browser response is still HTML.

After deployment, run the audit against the real origin:

```bash
pnpm exec next-ai-ready audit https://docs.example.com --version 3
```

Confirm that normal page URLs still return HTML, `.md` URLs return Markdown, and generated canonical URLs use the production domain.

## Common content collection problems

- **The collection is empty.** Run the content glob against the project root and check ignored paths.
- **Routes contain `content/` or `src/app/`.** Upgrade the package and verify the source-root rules.
- **Generated output contains local URLs.** Set `site.baseUrl` to the production origin before build.
- **The UI route differs from the graph route.** Add a content source adapter with explicit routes.
- **Private drafts appear in `llms.txt`.** Exclude drafts from the matched source; generated artifacts are public unless the deployment protects them.
- **The page ranks for the wrong query.** Make the title, summary, H1, and first paragraph answer the same specific problem instead of adding more tags.

For a complete installation, continue with the [10-minute setup](../installation) and verify the result with `doctor` before deploying.