Quick Start

Get content negotiation running in your Next.js app in under 2 minutes.

Prerequisites

• Node.js 18 or later
• A Next.js 14+ project (App Router or Pages Router)

1. Install the package

$ npm install next-md-negotiate

Or use your preferred package manager:

$ pnpm add next-md-negotiate
$ yarn add next-md-negotiate
$ bun add next-md-negotiate

2. Initialize your project

The CLI auto-detects your project structure and creates all necessary files:

$ npx next-md-negotiate init

This command will:

1. Detect whether you use App Router or Pages Router
2. Create a route handler at app/md-api/[[...path]]/route.ts
3. Create a config file at md.config.ts
4. Ask which routing strategy you prefer (rewrites or middleware)
5. Apply the selected strategy to your project

3. Define your first markdown route

Open md.config.ts and add a route:

import { createMdVersion } from 'next-md-negotiate';

export const mdConfig = [
  createMdVersion('/products/[productId]', async ({ productId }) => {
    const product = await getProduct(productId);
    return `# ${product.name}\n\n**Price:** $${product.price}`;
  }),
];

The handler receives fully type-safe parameters extracted from the route pattern. TypeScript knows that '/products/[productId]' gives you { productId: string }.

4. Test it

Start your dev server and test with curl:

# Start the dev server
$ npm run dev

# Request markdown from your route
$ curl -H "Accept: text/markdown" localhost:3000/products/42

# Response:
# Product 42

**Price:** $42.00

5. Add LLM hints (optional)

Help AI agents discover that markdown is available by adding the LlmHint component to your pages:

import { LlmHint } from 'next-md-negotiate';

export default function ProductPage() {
  return (
    <div>
      <LlmHint />
      { /* your page content */ }
    </div>
  );
}

Or run the CLI command to inject hints into all configured pages:

$ npx next-md-negotiate add-hints

Next steps