API Reference

Complete reference for every function, component, type, and CLI command exported by next-md-negotiate.

createMdVersion

Define a markdown route. This is the primary function you use in md.config.ts.

createMdVersion<T extends string>(
  pattern: T,
  handler: (params: ExtractParams<T>) => Promise<string>,
  options?: {
    hintText?: string;
    skipHint?: boolean;
  }
): MdVersionHandler

createMdHandler

Create an App Router route handler from your config. Use this in app/md-api/[[...path]]/route.ts.

createMdHandler(
  registry: MdVersionHandler[]
): (
  req: Request,
  ctx: { params: Promise<{ path?: string[] }> }
) => Promise<Response>

Returns a standard web Response with Content-Type: text/markdown; charset=utf-8 on match, or 404 if no route matches.

createMdApiHandler

Create a Pages Router API handler. Use this in pages/api/md-api/[...path].ts.

createMdApiHandler(
  registry: MdVersionHandler[]
): (
  req: NextApiRequest,
  res: NextApiResponse
) => Promise<void>

createRewritesFromConfig

Generate Next.js rewrite rules from your config. These rewrites match requests with markdown Accept headers and redirect them to the internal handler.

createRewritesFromConfig(
  handlers: MdVersionHandler[],
  options?: { internalPrefix?: string }
): Rewrite[]

The internalPrefix defaults to /md-api. Each rewrite includes a header condition matching text/markdown, application/markdown, or text/x-markdown in the Accept header.

createNegotiatorFromConfig

Create a middleware negotiation function from your config. Returns a rewrite response when a markdown request matches, or undefined to pass through.

createNegotiatorFromConfig(
  handlers: MdVersionHandler[],
  options?: { internalPrefix?: string }
): (
  request: Request
) => NextResponse | undefined

Lower-level APIs

For advanced use cases, these functions provide direct access to the rewrite and negotiation logic without requiring a config array:

createMarkdownRewrites

createMarkdownRewrites(options: {
  routes: string[],
  internalPrefix?: string
}): Rewrite[]

createMarkdownNegotiator

createMarkdownNegotiator(options: {
  routes: string[],
  internalPrefix?: string
}): (
  request: Request
) => NextResponse | undefined

LlmHint

React component that renders a hidden hint for LLM agents.

<LlmHint
  message?: string
/>

Renders <script type="text/llms.txt">message</script>. Invisible to browsers, readable by LLMs. See LLM Hints for details.

Types

ExtractParams<T>

Utility type that extracts parameter names from a route pattern string:

type ExtractParams<T extends string>

// Examples:
ExtractParams<'/products/[productId]'>
  → { productId: string }

ExtractParams<'/[org]/[repo]'>
  → { org: string; repo: string }

ExtractParams<'/docs/[...slug]'>
  → { slug: string }

MdVersionHandler

interface MdVersionHandler {
  pattern: string;
  handler: (params: Record<string, string>) => Promise<string>;
  hintText?: string;
  skipHint?: boolean;
}

CLI Commands

init

$ npx next-md-negotiate init [flags]

Flags:
  --rewrites     Use rewrites strategy (skip prompt)
  --middleware   Use middleware strategy (skip prompt)
  --add-hints    Inject LlmHint into pages

add-hints

$ npx next-md-negotiate add-hints

Injects <LlmHint /> into all pages with configured routes.

remove-hints

$ npx next-md-negotiate remove-hints

Removes all <LlmHint /> components and imports from pages.