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.

Custom messages

You can customize the hint message in three ways:

1. Per-component

<LlmHint message="Markdown available. Request with Accept: text/markdown." />

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:

1. Parse your md.config.ts for createMdVersion() calls
2. Find the corresponding page file for each route
3. Add the import and <LlmHint /> component (or remove them)
4. 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