Search and AI

Docs are read by people and by agents. Both are first-class here, and neither needs a plugin.

Full-text search

Every site has search at /search. There is no index to build, no external service to sign up for, no crawler to wait on, and no third-party API key to rotate. Indexing happens as part of the write, so a page is searchable the moment the push that created it returns.

How queries are treated. The query is trimmed and capped at 200 characters, split into at most eight terms, and every term must appear for a page to match. Results are ranked and capped at twenty. Punctuation is a separator, never syntax — there is nothing you can type that gets interpreted as a search operator, and a query that means nothing returns no results rather than an error.

Half-typed words. The last word of a query also matches as a beginning, so bluetoo finds Bluetooth and batter finds battery while you are still typing. Only the last word: the ones before it are words you finished, and quietly widening a finished word costs precision without telling you anything.

Phrases. Quote a run of words to require them together. "base station" finds pages that say base station; it drops the pages that merely contain both words three paragraphs apart.

Stemming. installing, installed, and install find each other, and accented text is handled correctly.

Titles outrank mentions. A page called "LoRa Radio" beats a page that mentions the LoRa radio in passing. Title matches are weighted heavily, because on a documentation site the page named after the thing you asked about is almost always the page you wanted.

Did you mean. A query that finds nothing is answered with the nearest real words from your own docs: base staton offers base station, firmwear offers firmware. Typing offers completions from the same list. Both run in the reader's browser against a compact list of the words your documentation actually uses — a few kilobytes, fetched once, and only when someone uses search at all. Neither is load-bearing: with JavaScript off the search form is an ordinary form, the results come from the server, and only the suggestions are missing.

What is indexed. The rendered plain text of the page plus its title. Markdown syntax is not searchable — a search for admonition will not match pages merely because they contain :::info, and code fences are indexed as their contents, not their fences.

Scope. Search is per version by default. /search searches the default version; /1.0/search searches the 1.0 pages and links results back into /1.0/. A reader on old docs is never handed a current-version answer without being told. When a site has more than one version, the results page also offers Search all versions, which spans every release, labels the hits that are not current, and shows a page that exists in several versions once — the current one.

Results. Each hit shows the page title and a snippet with the matched terms wrapped in <mark>. The results page is noindex.

What it does not do, honestly: no synonyms, no faceting, and no relevance tuning knobs. Beginning-of-word matching reaches as far as the stored root of a word and no further, so instal finds installation but installat does not. The suggestions need JavaScript; the results do not. And search needs the network — an offline reader can reread the pages they have already opened, but cannot run a new query. It is a good in-page find for a docs site, not a hosted search product.

Raw markdown at every URL

Append .md to any page URL to get its source:

https://docs.acme.com/guide/install       → rendered HTML
https://docs.acme.com/guide/install.md    → text/markdown

The root page is at /index.md. Non-default versions follow the same rule: /0.9/guide/install.md.

What you get back is the exact markdown that was pushed, front matter included, served as text/markdown; charset=utf-8. It is not a reconstruction from HTML, and it does not drift from the rendered page — both come from the same stored row.

This is what makes the docs usable as an agent tool without scraping. It is also a plain-text escape hatch: curl a page, diff two versions, or pipe a section into a script.

The markdown twin is declared, not merely available. Every page's <head> carries:

<link rel="alternate" type="text/markdown" href="https://docs.acme.com/guide/install.md">

so a client that reads heads finds the clean source without having to guess that appending .md might work.

llms.txt

/llms.txt is a compact index of the whole site for agents that need to decide what to read.

# Acme Docs

> Everything Acme does, written down.

Every page below links to its markdown source: the same content as the HTML
page, without navigation, styling, or scripts. Append `.md` to any
documentation URL to get it. These links are the 1.0 documentation, which is
the current version — older versions are under Optional at the end. For
everything at once in a single file, fetch https://docs.acme.com/llms-full.txt.
To look something up rather than read it all, /search?q=<terms> answers with
ranked pages.

## Start here

- [Welcome](https://docs.acme.com/index.md): What Acme is and how to get started.

## User Guide

- [Install](https://docs.acme.com/guide/install.md): From download to first run.
- [Configuration](https://docs.acme.com/guide/config.md): Every setting, and what it changes.

## Optional

- [/llms-full.txt](https://docs.acme.com/llms-full.txt): every page of the current version inline, in one file.
- [/sitemap.xml](https://docs.acme.com/sitemap.xml): every indexable URL, all versions included.
- [0.9 documentation](https://docs.acme.com/0.9): an older version, kept for readers still on it.

Three things are worth knowing about how it is built.

The summary is your own. The blockquote under the title is your home page's description. Nothing is invented for it.

Links are grouped by your navigation. Pages appear under the section they live in, named the way your sidebar names it, in your own ordering — so an agent reading it cold gets the shape of your documentation rather than an alphabetised list of files.

Older versions are demoted, not hidden. They sit under ## Optional with the current version's pages above them. On a site with several releases, listing every version at equal weight buries the docs almost everybody wants.

Each entry carries the page's description, which is exactly why writing a real description in front matter is worth the keystrokes: it is the summary an agent uses to decide whether to open the page.

llms-full.txt

/llms-full.txt is the entire current documentation in one plain-text response: every page of the default version only, in path order, as raw markdown, each preceded by its path and title.

# Acme Docs — full documentation

> Scope: every page of the 1.0 documentation, which is the current version.
> 1 older version is NOT included here; they are listed in
> https://docs.acme.com/llms.txt

---
page: /
title: Welcome
---

# Welcome
...

---
page: /quickstart
title: Quickstart
---

# Quickstart
...

It excludes older versions deliberately, and it says so in its own header rather than leaving you to notice. Three releases of the same page in one context window makes an agent's answers worse, not better. Agents that need an old release read that version's .md URLs directly.

Page tools

Every content page carries a set of controls — in the right rail on wide screens, inline above the content on narrow ones:

The Ask controls hand over a URL, not a copy of the page. The assistant fetches current source rather than reasoning over a stale paste.

These controls appear on documentation pages only, not on search results or the 404 page.

Crawler policy

robots.txt is generated per host.

On the site's primary host:

User-agent: *
Content-Signal: search=yes, ai-input=yes
Allow: /

Sitemap: https://docs.acme.com/sitemap.xml

search=yes and ai-input=yes grant indexing and use as model input at answer time. ai-train is deliberately left unstated rather than granted or denied — that is a per-site decision, not something the engine should assume.

On any non-primary host the file is User-agent: * / Disallow: /, so staging hostnames stay out of every index.

/sitemap.xml lists every page of every version with a last-modified date.

Social previews

Every page carries Open Graph and Twitter card metadata — title, description, canonical URL, site name — and an image, so a link to your docs unfurls as a card in chat, in a pull request, and on social platforms rather than as a bare URL.

The image is drawn for you. Each page gets one at /og/<page path>.png, and the site's home page card is at /og.png; both are 1200x630 PNGs carrying your site name, the page's title, and your colors.primary. There is nothing to generate, upload, or keep in sync — change the page title or the brand colour and the card follows on the next publish.

To use your own artwork instead, set og_image in site settings to its URL. It replaces the generated card on every page.

Structured data

Every page carries JSON-LD: a TechArticle describing the page, and a BreadcrumbList built from your navigation, so each step of the trail is named the way your sidebar names it rather than the way the URL spells it. The home page adds a WebSite block naming the site and declaring its search endpoint.

There is no FAQ or How-To markup, and that is deliberate: those describe specific page shapes, and emitting them for pages that are not actually questions-and-answers or numbered procedures is the kind of thing search engines penalise. If you want them for a page that genuinely is one, tell us.