AI-agent support
.md version of each page and an llms.txt site index. Let readers open the current page in ChatGPT or Claude.An HTML page includes a sidebar, scripts, and styles. A model must remove that
shell before it reads the content. OINK can emit the same content as plain
Markdown. It provides one .md per page, one llms.txt index at the site root,
and a “copy as Markdown” button on the page. All three use build-time artifacts.
They require no runtime service or content negotiation.
The site must declare all three under outputs. The theme does not enable
them. Two other optional artifacts help an agent read more than one page:
a full-text bundle per section and a navigation tree per language.
A .md per page
markdown is one of Hugo’s built-in output formats. Add it to the page kinds
that need it:
This site uses the configuration above. Each key under outputs is a
wholesale replacement, not a merge. When you add markdown, include every
format that the page kind already used (RSS, print). If you omit a format,
you lose that output.
The URL rule is the page URL plus index.md:
| Page | Markdown |
|---|---|
/docs/customize/agents/ |
/docs/customize/agents/index.md |
/docs/customize/ (section index) |
/docs/customize/index.md |
/ (site home) |
/index.md |
Each HTML page’s <head> includes a discovery link. A crawler therefore does
not need to guess the URL:
What the .md contains
This output contains the source you wrote. It is not a conversion of rendered HTML. Front matter becomes an H1 and a blockquoted summary. The body follows verbatim. The theme expands shortcodes in place into their Markdown forms.
Native Markdown components retain their source in the .md. These include
callouts, tables, field lists, image attribute lines, code fences, and data
fences. The model reads the source you wrote. A section index also appends a
Section pages: list of child links after the body.
Each shortcode has a defined Markdown fallback. A
badge becomes emphasized text or a link. A
key becomes Ctrl + K.
Tabs become consecutive **Label** subsections.
Fields become an item list. Each component page
describes its fallback in the Output section.
If the site has not enabled LLMS output, the LLMS index: line does not
appear. The theme never links to a file that it did not publish.
llms.txt
llms.txt is a plain-text manifest at the site root.
It identifies site content and its machine-readable versions. To generate it,
add the LLMS output format to the home page:
A multilingual site gets one per language: /llms.txt and
/zh/llms.txt. The content is a generated site index:
The Site index contains this language’s home page and the site’s main menu
(menus.main). It links to an entry’s Markdown version when available. It
includes description when present. The Documentation index contains the
docs subsections and the level of pages beneath them. It indents entries by
level and includes each page’s description. The Site locales section lists
every configured language. The index omits off-site menu entries, such as
GitHub or an issue tracker. These entries belong to navigation, not site content.
To improve llms.txt, change the main menu and each section index’s
description. You do not need to change the template.
Full-text bundle
One .md per page suits an agent that knows which page it needs. To read the
whole manual, an agent would otherwise crawl each page. The LLMSFULL output
provides one llms-full.txt per top-level section. It contains every included
page in reading order. OINK 0.8.0 introduced this output. It remains off until
a section enables it.
The switch is the section index’s own front matter rather than the site configuration:
Front matter outputs replaces the page’s site-level list. Include the formats
that the section already used. If you omit markdown or print, the section
index loses those outputs. Front matter applies per language. For a bilingual
site, repeat the line in _index.zh.md to generate the Chinese bundle.
The output contains one file per language at the section root:
/docs/llms-full.txt and /zh/docs/llms-full.txt. It uses the sidebar and pager
reading order. For a docs or book section with an explicit
data/docs_nav.json tree, it uses that tree. Otherwise, it uses the weighted
content tree. Pages excluded from the sidebar with toc_hide are also excluded
from the bundle.
Each page is introduced by a separator carrying its source URL, and the body
that follows is byte-identical to that page’s own .md:
Source: points at the page’s Markdown output, falling back to its HTML URL
where the page publishes no .md.
Only a top-level section can publish a bundle. If you list LLMSFULL further
down the tree, the theme warns (“LLMSFULL output requires a top-level section”)
and emits nothing.
If at least one section has a bundle, llms.txt includes a ## Full-text bundles list for that language. An agent can discover bundles in the file it
already fetches.
This site’s docs section enables the bundle. https://oink.pgsty.com/docs/llms-full.txt contains the entire English documentation in one file.
Navigation JSON
The sidebar is the site’s table of contents. An agent can read it to plan
which pages to fetch. The NAVJSON output publishes the tree as
navigation.json, with one file per language at the language root. OINK 0.8.0
introduced this output. It is off by default. Enable it for the home page:
This produces /navigation.json and /zh/navigation.json. It uses the same
tree as the sidebar and pager. For a docs or book section with an explicit
data/docs_nav.json tree, it uses that tree. Elsewhere, it uses the weighted
content tree:
| Key | What it holds |
|---|---|
id |
The page path without its language prefix. The same page has the same id in every language |
url |
The absolute URL of this language’s HTML page |
markdown |
The absolute URL of the page’s .md, present only where the page publishes one |
title |
The navigation title (linkTitle, falling back to title) |
description |
The page’s description, where it has one |
kind |
home, section, or page for real pages. external or link for placeholders |
children |
The ordered children, where the node has any |
Array order is part of the contract. The theme never serializes weight
because it has already applied the order. If a consumer sorts the array again,
its order can differ from the source sidebar.
Placeholder rows retain the sidebar’s structure. A manual_link entry becomes
an external node with the authored URL. A manual_link_relref entry becomes
a link node with the resolved reference. Neither has page identity, an id,
or a markdown URL. The tree omits sidebar dividers and pages that Hugo never
renders. Their children remain in place.
The contract has a version. The value of schemaVersion is 1. The theme
repository ships its JSON Schema as
schema/nav.v1.schema.json.
If you consume the file, validate it against this schema. If the site publishes
it, llms.txt lists navigation.json for its language in the site index.
This site has it enabled: https://oink.pgsty.com/navigation.json is a live instance of the tree.
Agent actions on the page
Four entries in the action menu at the right of the breadcrumb row relate to agents:
| Entry | What it does | When it appears |
|---|---|---|
| Copy as Markdown | Copies this page’s .md to the clipboard. Prefetches on hover to avoid a perceptible wait after a click |
This page has a markdown output |
| View Markdown source | Opens the .md in a new tab |
This page has a markdown output |
| Open in ChatGPT | Opens ChatGPT with a prompt | assistant_links: true |
| Open in Claude | Opens Claude with a prompt | assistant_links: true |
The first two actions appear when markdown output is enabled. “Copy” is the
left half of the split button, with the clipboard icon. After a successful
copy, it briefly shows a check mark.
The last two are off by default and must be enabled explicitly:
When the reader clicks an enabled assistant action, the runtime creates a
prompt from the address bar’s full URL. It includes the real domain, query
string, and anchor. In English, the prompt is “Please read the contents of
A page may restrict the site policy but cannot reverse it. The front matter
page_context_menu: { assistant_links: false } disables assistant links for
that page. If the site has not enabled them, setting true has no effect.
To disable the entire menu for a page, use page_context_menu: false.
See Page parameters.
Both assistant actions are also searchable in the command palette, from the same action manifest — see Command palette.
Opting a page out of .md output
Replace outputs in the page’s front matter. This replaces the complete list.
Include only the formats that you want to keep:
To keep RSS and remove only Markdown, list the remaining formats:
Customizing the output
The theme renders Markdown output with layouts/all.md and generates
llms.txt with layouts/index.llms.txt. The two optional formats use
layouts/list.llmsfull.txt and layouts/index.navjson.json. To replace a
complete template, put a file with the same name under the site’s layouts/.
First consider an override with a smaller scope:
- Per content type: a typed path such as
layouts/blog/single.mdorlayouts/docs/list.mdaffects only that content kind. The theme specializes its print templates this way (layouts/blog/single.print.html). Check the template lookup order for your combination. - Per shortcode: a site shortcode can use an output-format-specific template. This can provide a more machine-readable form in Markdown output.
- Per page: for a few high-value pages, writing the output by hand requires less work than changing a template.
The content of llms.txt follows the site’s structure. Before changing the
template, check the main menu and each description for the problem. If you
replace index.navjson.json, you also take responsibility for the nav.v1
contract. Your output must still satisfy schema/nav.v1.schema.json for
consumers that validate it.
Verify
Run from your site’s root, with Markdown and LLMS outputs enabled. Replace
PAGE_MD with an actual page’s generated Markdown file. The section paths below
assume a docs section; adjust them and any language prefix to your site.
Against a running local preview or production, use your own base URL and page
path. BASE_URL includes the deployment subpath and, when testing a translated
site, the language prefix:
Then check four things:
- Confirm that the selected page’s HTML
<head>hasrel="alternate" type="text/markdown"; - Click the copy button beside the title and paste the result. Confirm that it is Markdown instead of HTML;
llms.txtcontains no off-site links;- If you enabled these outputs, confirm that each page in
llms-full.txtstarts with aSource:line. The same page must have the sameidin each language’snavigation.json.
Limits
- The theme produces four types of machine-readable build-time files: a
.mdper page,llms.txt, optionalllms-full.txtper top-level section, and optionalnavigation.jsonper language. Hugo still ownssitemap.xml. - A bundle belongs to a top-level section. There is no whole-site
llms-full.txt. To read everything, an agent reads the section bundles listed inllms.txt. LLMS,LLMSFULL, andNAVJSONare non-alternative formats. They have no<head>alternate links or page actions. Agents discover them through conventional paths and their entries inllms.txt.- Server-side content negotiation (one URL returning Markdown for
Accept: text/markdown) is outside the theme’s scope and belongs to the hosting layer. - Markdown output uses the source. Content generated only by browser JavaScript, such as a runtime-drawn chart, appears in the
.mdas fence source. It does not appear as a diagram.
Related
- Print — the other non-HTML output
- Command palette — the other entry point to the assistant actions
- Page parameters —
outputs/assistant_links/page_context_menu - Navigation and menus —
llms.txt’s site index comes from the main menu - Configuration — full definitions of
outputsandparams.ui.page_context_menu.*