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:

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

Flags: Use --rewrites or --middleware to skip the strategy prompt. Add --add-hints to inject LlmHint components automatically.

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

Core Concepts →Configuration →SEO & Crawling →