For the complete documentation index, see llms.txt. This page is also available as Markdown.

SEO & AEO optimization

When publishing a Quarkdown document as a website, especially plain and docs projects with multiple subdocuments, a few setup steps make the site easier to find and index. This page collects the recommended settings for both search engines (SEO) and AI agents (AEO).

Most of these are already taken care of by Quarkdown’s project creator when picking the docs document type.

Base URL

Set the site’s canonical base URL through .htmloptions:

.htmloptions baseurl:{https://example.com}

This has two effects:

1. Every generated page gets a <link rel="canonical"> pointing to its final URL, which helps search engines pick the preferred address for each page.
2. When the project contains at least one subdocument, Quarkdown emits a sitemap.xml, listing every page for crawlers to discover.

The base URL should point to the directory where index.html is served from.

Robots.txt

Search engines and AI crawlers check for a robots.txt file at the root of your site to learn which pages they may access, and where to find the sitemap generated from the base URL.

Ship it as a static asset by placing it in the project’s public/ directory:

A minimal file that welcomes all crawlers and points them to the sitemap:

User-agent: *
Allow: /

Sitemap: https://example.com/sitemap.xml

The Sitemap line should use the same URL passed to .htmloptions baseurl:{...}, so crawlers pick up every subdocument.

Document metadata

Filling in the metadata fields on populate the corresponding HTML <meta> tags, consumed both by search engines and by AI agents.

.docname {My site}
.doclang {English}
.docauthor {Jane Doe}
.docdescription {A short summary of what this site is about, ideally under 160 characters.}

.dockeywords
    - typesetting
    - markdown
    - documentation

See Document metadata for the full reference, including per-subdocument overrides.

Shipping a Markdown copy

Modern AI agents and LLM-based crawlers prefer plain Markdown over HTML because it strips away layout noise and preserves the document structure. Quarkdown can produce both artifacts from the same source in two runs of the compiler:

quarkdown c main.qd -r html --clean
quarkdown c main.qd -r markdown

The second run writes .md files alongside the HTML output, so the result is a single directory containing both formats:

Generating llms.txt

The llms.txt convention proposes a single Markdown file at the root of a site (/llms.txt) that curates the most useful entry points for LLM-based crawlers.

The .llmstxt function takes care of:

1. Generating the llms.txt file at the site root, listing the root document and every subdocument as an absolute link.
2. On every page, it emits a hidden discoverability directive so agents that land on a rendered page can find llms.txt.

Place the call in a shared setup file so both effects apply to every page:

.llmstxt markdownavailable:{yes}
    A short summary of what this site is about, used as the blockquote at the top of llms.txt.

Set markdownavailable to yes when the site also ships .md files (see Shipping a Markdown copy. In that case, the directive tells agents how to fetch the Markdown version of the current page.

llms.txt uses absolute URLs, so .llmstxt requires .htmloptions baseurl:{...} to be set.

Per-subdocument page titles

By default, every page in a multi-subdocument project shows its own name in search engines and browser tabs, defined by its .docname.

.docname {My document}

The recommended pattern combines the subdocument’s own name with the site name, and lives in a common setup file (such as _setup.qd in docs documents).

.ifnot {.docname::equals {My site}}
    .htmloptions title:{.docname | My site}