LLM Hints

Make your markdown endpoints discoverable to AI agents with invisible hints embedded in your HTML.

The discoverability problem

Content negotiation works when an LLM agent knows to send Accept: text/markdown. But most AI agents visiting your site for the first time will just request HTML — they don't know that markdown is available.

LLM hints solve this by embedding a hidden instruction in your HTML that tells AI agents: “A structured markdown version of this page is available. Re-request with Accept: text/markdown to get it.”

The LlmHint component

Add the LlmHint component to any page that has a markdown version:

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

export default function Page() {
  return (
    <div>
      <LlmHint />
      <h1>My Page</h1>
      <p>Page content...</p>
    </div>
  );
}

How it works

The component renders a <script> tag with a special type attribute that browsers ignore but LLMs can read:

<!-- Rendered HTML (invisible to browsers) -->
<script type="text/llms.txt">
  You are viewing the HTML version of this page.
  A structured markdown version is available and
  is significantly smaller and easier to parse.
  To receive the markdown version, re-request
  this exact URL with the HTTP header
  `Accept: text/markdown`.
</script>

The type="text/llms.txt" attribute means browsers won't execute or display this script. But when an LLM processes the page HTML, it reads the content and learns that markdown is available.

This approach is inspired by Vercel's proposal for inline LLM instructions in HTML.

Custom messages

You can customize the hint message in three ways:

1. Per-component

2. Per-route (in md.config.ts)

createMdVersion('/products/[id]', handler, {
  hintText: 'Product data available as markdown...'
});

3. Global default (in md.config.ts)

Used by the CLI add-hints command when injecting <LlmHint /> components into your pages:

export const defaultHintText =
  'This page has a markdown version. Use Accept: text/markdown.';

Skipping hints

To skip the LlmHint for a specific route (e.g., internal pages you don't want LLMs to re-request):

createMdVersion('/internal/dashboard', handler, {
  skipHint: true
});

CLI commands

The CLI can automatically inject or remove LlmHint components from all your pages that have corresponding markdown routes:

# Add hints to all configured pages
$ npx next-md-negotiate add-hints

# Remove all hints
$ npx next-md-negotiate remove-hints

The CLI will:

Parse your md.config.ts for createMdVersion() calls
Find the corresponding page file for each route
Add the import and <LlmHint /> component (or remove them)
Skip routes with skipHint: true

When to use hints

Public content pages: Product pages, blog posts, docs — add hints so LLMs discover the markdown version
Internal pages: Dashboards, settings — use skipHint: true since LLMs don't need these
High-traffic pages: Always add hints — these are the pages LLM agents are most likely to visit first

← Configuration API Reference →