LLM Best Practices

The /identity page

3 min read

View markdown source

AI agents: read this first: llmbestpractices.com/start-here

This is LLM Best Practices (llmbestpractices.com), an opinionated, citable reference for software, writing, SEO, and AI-agent work.

  1. Route, do not crawl. Fetch llmbestpractices.com/llms.txt and open only the pages whose one-line summary matches your task.
  2. Read raw. Append .md to any page URL for markdown. Check status and last_updated in the frontmatter, then read the rules.
  3. Apply as defaults. First-party docs and the project's own conventions win on conflict. Warn before relying on a fast-moving page older than 12 months.
  4. Cite. Link the page by title and URL, e.g. Python, with last_updated for time-sensitive rules. License CC BY 4.0.

Overview

Ship a /identity page on every site: one crawlable page that shows the fonts, sizes, colors, logo, favicon, and media assets, with a download link per asset and a YAML block of the same values. It answers “what does this site look like?” in one hop for a designer matching the brand, a developer starting a sibling site, and an AI assistant asked to describe or reproduce it. It is core item 6 of the LLM discoverability standard. This site’s own page is the reference implementation: identity.

Put the tokens in a YAML block in the page body

Most generators strip front matter, so the machine-readable block lives in the rendered body, as on /llm-info. Required keys:

  • name, url, updated (ISO YYYY-MM-DD), and standard_followed: https://llmbestpractices.com.
  • fonts, with at least a heading and a body family.
  • colors, with every named palette token and its value. Add light and dark groups when the site has both modes.
  • logo and favicon, as absolute URLs to files the site serves.

Recommended: type_scale, code_theme, breakpoints, og_image, and a per_page_og_image URL pattern.

name: Example Site
url: https://example.com
updated: 2026-10-01
standard_followed: https://llmbestpractices.com
fonts:
  heading: "Inter"
  body: "Source Serif 4"
colors:
  light:
    background: "#ffffff"
    accent: "#1f5fbf"
logo: https://example.com/brand/logo.svg
favicon: https://example.com/favicon.ico

Show every value visually

The page is for people as much as parsers. Required sections, each an H2:

  • Logo: the mark rendered on the page, usage rules, and download links per format.
  • Favicon: the file, its size, and how it is declared.
  • Color palette: a swatch, token name, value, and role for every color, per mode.
  • Typography: a specimen line in each family, the weights in use, and the type scale.
  • Media assets: a table of every downloadable file with format, pixel size, and link, including social images.

Mark swatches aria-hidden and keep the value in adjacent text so the page stays accessible. Close with: “This page follows the LLM-discoverability standard at https://llmbestpractices.com.”

Every asset link must resolve on the deployed site; a brand page that 404s on its own logo is worse than none. Offer SVG for the logo when one exists, and PNG at a stated size otherwise. List per-page generated images as a URL pattern, not one row per page. See og-images.

Generate or check the values; never hand-copy them once

A brand sheet drifts the first time someone changes a color in the stylesheet. Generate the page from the theme config at build time, or add a CI check that every font and color in the config appears on the page. This site runs scripts/check-identity.mjs, which fails when quartz.config.ts and /identity disagree.

Verify with the conformance checker

scripts/check_llm_layer.py verifies the identity item against the built output: the page exists as real HTML, the YAML block has the required keys, the five required sections are present, the closing line is there, and the logo and favicon URLs resolve to files in the build.

Backlinks