---
title: Nextra llms.txt and Markdown endpoint setup
description: Integrate next-ai-ready with a Nextra 4 App Router documentation site without replacing Nextra navigation, search, themes, or MDX rendering.
canonical_url: https://nextaiready.com/en/docs/guides/nextra-ai-ready
url: https://nextaiready.com/en/docs/guides/nextra-ai-ready
last_updated: 2026-09-28
updated: 2026-09-28
author: next-ai-ready team
summary: Integrate next-ai-ready with a Nextra 4 App Router documentation site without replacing Nextra navigation, search, themes, or MDX rendering.
topics: [nextra, nextjs, llms.txt, mdx]
---

# Nextra llms.txt and Markdown endpoint setup

[Nextra 4](https://nextra.site/docs) is a Next.js App Router framework for content-focused sites.
Keep Nextra responsible for the human-facing documentation experience. Add `next-ai-ready` beside it
when you want synchronized `/llms.txt`, page Markdown, semantic discovery, and optional MCP resources.

Not using Nextra? Start with the framework-neutral
[Next.js App Router llms.txt walkthrough](./nextjs-llms-txt).

This guide supports Nextra's root `content/` and `app/` layouts as well as their `src/` equivalents.
It does not support Nextra 1-3 sites that still use the Pages Router.

## Executable reference

The repository includes an [executable Nextra 4 fixture](https://github.com/mustcanbedo/next-ai-ready/tree/main/examples/nextra-docs)
validated with Nextra `4.6.1`, Next.js `16.2.6`, and React `19.2.4`. One `content/` MDX collection
drives both the Nextra UI and the next-ai-ready semantic graph. Its production smoke test covers HTML,
`/llms.txt`, `/llms-full.txt`, explicit Markdown and AI JSON URLs, content negotiation, and the separate
browser/agent missing-page contracts.

Run the same contract from the repository root:

```bash
pnpm --filter @next-ai-ready/example-nextra-docs build
pnpm --filter @next-ai-ready/example-nextra-docs test
```

## 1. Install and initialize

From the Nextra application directory:

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

`init` adds the AI routes and an `ai-ready.config.mjs` file. It does not replace Nextra's theme,
catch-all page, search configuration, or MDX components.

## 2. Point both systems at the same content

Nextra supports Markdown and MDX in `content/`, `src/content/`, `app/`, or `src/app/`. The default
next-ai-ready scanner covers those locations. For an explicit Nextra content directory, keep the
configuration narrow:

```js
import { defineConfig } from "next-ai-ready"

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

Use `src/content/**/*.{md,mdx}` instead when the Nextra project uses a `src/` directory. Frontmatter
`description` is accepted as a page summary, so existing Nextra content does not need duplicate
metadata solely for next-ai-ready.

## 3. Compose the Next.js plugins

Keep Nextra's existing plugin and wrap the resulting Next.js config with `withAiReady()`:

```js
import nextra from "nextra"
import { withAiReady } from "next-ai-ready/config"

const withNextra = nextra({
  // Existing Nextra options stay here.
})

const nextConfig = withNextra({})

export default withAiReady({ agentReadable: true })(nextConfig)
```

This composition preserves Nextra's MDX handling and adds content negotiation for AI-readable page
responses. Do not enable Next.js `output: "export"`; the generated runtime handlers require a server.

### Nextra 4.6.1 and Zod 4.4 compatibility

Nextra `4.6.1` currently declares a Zod range that can resolve its private dependency to Zod `4.4.x`.
That combination can fail `nextra-theme-docs` layout validation before a page renders. Until the
upstream fix ships, pin only Nextra's private copies in the workspace root:

```json
{
  "pnpm": {
    "overrides": {
      "nextra>zod": "4.3.6",
      "nextra-theme-docs>zod": "4.3.6"
    }
  }
}
```

Keep next-ai-ready's Zod 4 dependency unchanged. This workaround is scoped only to Nextra's private copies and is
tracked upstream in [Nextra #4989](https://github.com/shuding/nextra/issues/4989) and
[#5036](https://github.com/shuding/nextra/issues/5036); remove the override once a fixed Nextra
release passes the fixture.

## 4. Build and verify

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

After deployment, verify one real page and the discovery files:

```bash
curl -I https://docs.example.com/llms.txt
curl -I https://docs.example.com/docs/getting-started.md
pnpm exec next-ai-ready audit https://docs.example.com/docs/getting-started --version 3
```

The Nextra HTML page must remain unchanged for browsers. The corresponding `.md` URL should return
clean Markdown, and an unknown browser URL must continue to return a real `404`.

## Start with the Knowledge plane

For an initial Nextra integration, ship only content discovery and page retrieval. Add MCP or callable
actions later when the site has a concrete agent workflow and an authentication policy.