Skip to main content

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.
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.
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.
1

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
2

Create a Route Handler

Create app/api/md/[[...path]]/route.ts and export a GET handler using createMarkdownHandler:
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.
3

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.
import { withAgentXP } from '@reaganhsu/agentxp-next'

export default withAgentXP()

​
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

OptionTypeDescription
overridesDirstringDirectory containing .md override files, relative to project root. Required.
baseUrlstringBase URL for link resolution. Auto-detected from the request if omitted.
siteHeaderSiteHeaderConfigManual site header prepended to every response. See Site Header.
bypassHeaderstringInternal bypass header name. Defaults to x-agentxp-internal.