Guides
AI agents
Every docs page is published as Markdown, with an llms.txt index and JSON sitemaps, so coding agents can read the docs as specs.
Markdown pages#
Add .md to any docs URL to get the page as Markdown: /docs/components/button.md,
/docs.md. Each file starts with frontmatter (title, description, URL, section). Live
examples become their source code, and reference tables become Markdown tables. The
Copy Markdown button at the top of every page copies it for pasting into a chat.
---
title: "Badge"
description: "A small label for status, counts or categories."
url: "/docs/components/badge"
section: "Components"
---
# Badge
A small label for status, counts or categories.
```html
<span class="badge badge-primary">New</span>
```Indexes#
Each opens in a new tab.
| URL | Contents |
|---|---|
| /llms.txt | llms.txt index (llmstxt.org): every docs page as a Markdown link with its description, grouped by section. Start here. |
| /llms-full.txt | Every docs page's Markdown in one file, for loading the whole library into context. |
| /sitemap.json | Every page with URL, Markdown URL, title, description, section, heading outline and section text, plus the list of docs versions. The index for site search. |
| /docs/sitemap.json | The same for the latest docs only. Each older version has its own, e.g. /docs/v0.1/sitemap.json. |
| /docs/versions.json | Every docs version with its URL prefix, its sitemap and the pages it contains. |
| /sitemap.xml | Standard XML sitemap for search engines. |
| /robots.txt | Allows crawling and points at the sitemap. |
{
"name": "HTMX UI",
"url": "https://example.com",
"version": "0.1",
"versions": [
{ "id": "0.1", "label": "v0.1", "path": "/docs", "latest": true, "sitemap": "/docs/sitemap.json" }
],
"pages": [
{
"url": "/docs/components/tabs",
"markdown": "/docs/components/tabs.md",
"title": "Tabs",
"section": "Components",
"headings": [{ "level": 2, "id": "markup", "text": "Markup" }],
"sections": [{ "id": "markup", "title": "Markup", "text": "Each [data-tab] button shows the [data-tab-panel]…" }]
}
]
}
Every sections[].id is a heading anchor, so url + "#" + id opens that exact section.
This site's own search (Ctrl K) works this way, and an MCP server can list pages from these files and link straight to the right place.
Prompts#
These work with any agent that can fetch URLs (Claude, ChatGPT, Cursor, Copilot and others). Copy, then replace the task.
Use the docs for one task#
Read https://susonwaiba.github.io/htmx-ui/llms.txt. It indexes the htmx-ui docs; every link is a Markdown page.
Fetch the pages relevant to the task below and follow their markup and class names exactly.
Use htmx-ui's design tokens (bg-primary, text-muted-foreground, border-border) instead of raw colours.
Task: build a settings page with tabs for Profile and Billing, and a danger-zone card with a delete button.Point at specific pages#
Build a settings page using htmx-ui. Follow these specs exactly:
https://susonwaiba.github.io/htmx-ui/docs/components/card.md
https://susonwaiba.github.io/htmx-ui/docs/components/tabs.mdMake it a skill#
Save the lookup steps as a skill so your agent uses the docs automatically, every time you work on UI, without pasting URLs again. Ask your agent to create it:
Create a skill named "htmx-ui" for this project (for Claude Code: .claude/skills/htmx-ui/SKILL.md).
It should trigger whenever I build or change UI with htmx-ui components, classes, theming or dark mode.
The skill must tell you to:
1. Fetch https://susonwaiba.github.io/htmx-ui/llms.txt to find the relevant docs pages.
2. Fetch those pages as Markdown (https://susonwaiba.github.io/htmx-ui/docs/<page>.md) and follow their markup exactly.
3. Check the htmx-ui version in package.json; if it's older than the latest docs, read
https://susonwaiba.github.io/htmx-ui/docs/versions.json and use that version's pages instead.
4. Prefer design tokens over raw Tailwind colours, and call initComponents() for new htmx content.
Keep the skill short and link to the docs rather than copying them.Or create the file yourself:
---
name: htmx-ui
description: Build UI with the htmx-ui component library (Tailwind CSS v4 + htmx). Use when adding or changing buttons, cards, alerts, tabs, dropdowns, tables, prose, theming or dark mode in this project.
---
# htmx-ui
The docs are written for agents. Don't guess class names; look them up.
1. Fetch the index: https://susonwaiba.github.io/htmx-ui/llms.txt
2. Fetch the pages you need as Markdown, e.g. https://susonwaiba.github.io/htmx-ui/docs/components/tabs.md
3. Match the docs to the installed version: read "htmx-ui" in package.json. If it's older than the
latest docs, use the matching version from https://susonwaiba.github.io/htmx-ui/docs/versions.json (pages live under its "path").
4. Search for a topic in https://susonwaiba.github.io/htmx-ui/sitemap.json: `pages[].sections[]` hold the text of every section.
Rules:
- Copy markup and class names from the docs exactly.
- Use design tokens (bg-primary, text-muted-foreground, border-border), not raw palette colours.
- Wrap long-form text in .prose; give components inside it not-prose.
- After htmx inserts new content, components initialise via initComponents() on htmx:after:process..cursor/rules/htmx-ui.mdc), a GitHub Copilot instruction file
(.github/copilot-instructions.md) or a section in AGENTS.md.
How it's generated#
Nothing is written by hand. At build time the site's engine config (site/htmx-ui.config.ts) renders every page, converts the article
body to Markdown (site/lib/markdown.ts), and writes the indexes (site/lib/site.ts). The dev server generates the same files on request.
- Page order follows the docs navigation in
site/data/docs-nav.json. - Absolute URLs (and the URLs in the prompts above) use the
SITE_URLenvironment variable, falling back tourlinsite/data/site.json. - Every docs heading gets an id and a
#link, so sections can be linked directly. - Add
data-md-skipto an element to leave it out of the Markdown and the search text (purely visual blocks).
SITE_URL=https://htmx-ui.example bun run build