> ## Documentation Index
> Fetch the complete documentation index at: https://motherfuckingsideproject.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Markdown Overrides

> Serve hand-written markdown for specific pages instead of auto-generated content.

# Markdown Overrides

> Serve hand-written markdown for specific pages instead of auto-generated content.

Sometimes auto-generated markdown doesn't capture your page exactly right. Overrides let you provide hand-written markdown files for specific routes that AgentXP serves directly — skipping HTML conversion entirely.

There are two approaches:

* **File-based overrides** — place `.md` files in a directory and serve them via a Route Handler (requires Node.js runtime)
* **Edge middleware only** — configure `withAgentXP()` as normal; auto-generation handles everything

## File-based overrides

Use `createMarkdownHandler` when you need full control over specific pages. The handler checks your overrides directory first; if no file matches, it falls back to auto-converting the page HTML.

<Warning>
  File-based overrides require Node.js runtime because they read from disk. If your middleware runs on Edge Runtime, use the Route Handler approach below and configure it separately from your middleware.
</Warning>

<Steps>
  <Step title="Create your override files">
    Place `.md` files in a directory that mirrors your URL structure. The filename (without extension) maps directly to the URL path. Use `index.md` for the root path.

    ```
    content/
      markdown/
        index.md
        pricing.md
        docs/
          getting-started.md
    ```
  </Step>

  <Step title="Create a Route Handler">
    Create `app/api/md/[[...path]]/route.ts` and export a `GET` handler using `createMarkdownHandler`:

    ```typescript theme={null}
    import { createMarkdownHandler } from '@reaganhsu/agentxp-next/route-handler'

    export const GET = createMarkdownHandler({
      overridesDir: 'content/markdown',
      baseUrl: 'https://yoursite.com',
    })
    ```

    The `overridesDir` path is relative to your project root (`process.cwd()`). The `baseUrl` is used for link resolution when auto-converting pages that don't have an override file.
  </Step>

  <Step title="Configure your middleware">
    Your middleware still uses `withAgentXP()` as normal. The Route Handler and the middleware operate in parallel — the middleware serves agent requests for any routes not handled by your Route Handler, and the Route Handler at `/api/md/[[...path]]` serves requests that are rewritten to it by your routing logic (e.g., via `next.config.js` rewrites or a custom matcher).

    For a simple setup where all agent traffic goes through the Route Handler, you can configure Next.js rewrites to send agent requests to `/api/md/[...path]` based on the `Accept` header.

    ```typescript theme={null}
    import { withAgentXP } from '@reaganhsu/agentxp-next'

    export default withAgentXP()
    ```
  </Step>
</Steps>

## How it works

When an AI agent requests a page, AgentXP resolves the URL path to a filename and checks your `overridesDir`:

1. If `content/markdown/<path>.md` exists, it's served directly. If you've configured a `siteHeader`, AgentXP prepends the generated navigation preamble before the file content.
2. If no override file exists, AgentXP fetches the page HTML and auto-converts it to markdown as normal.

This means you can override as few or as many pages as you need — the rest continue to work without any extra configuration.

## `RouteHandlerConfig` reference

| Option         | Type               | Description                                                                             |
| -------------- | ------------------ | --------------------------------------------------------------------------------------- |
| `overridesDir` | `string`           | Directory containing `.md` override files, relative to project root. Required.          |
| `baseUrl`      | `string`           | Base URL for link resolution. Auto-detected from the request if omitted.                |
| `siteHeader`   | `SiteHeaderConfig` | Manual site header prepended to every response. See [Site Header](/docs/guides/site-header). |
| `bypassHeader` | `string`           | Internal bypass header name. Defaults to `x-agentxp-internal`.                          |