better-html-doc
Skill1 starsChanged 3 days agoMITView on GitHub
A whole documentation site in the better-html-style (the look and engine of the claude-cluster docs) generated from Markdown - site.toml (name, languages EN / FR / both, sections with icons, home, kinds of pages, contextual help map), one Markdown file per page and language with TOML front matter, optional gen/*.py generators reading the code, a home with hero search, section tiles and changelog, numbered section cards, a sidebar by section, previous / next, updated date, a typo-tolerant search over every page and section (/ or Ctrl+K), sitemap, --split mode, explanation and protocol pages in the same site, checks (links, anchors, both languages, html-style rules) and a search test; responsive. Use whenever the user wants a better / searchable / multi-page documentation site, "une doc comme celle de claude-cluster", docs with search, or to move a project's docs to that style; a single page: better-html-style; the older single-page technical doc: html-doc.
In this repository70 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- ask-at-endSkill
- clarifySkill
- continue-workSkill
- exportSkill
- full-permissionSkill
- ideationSkill
- interactive-questionsSkill
- onboardSkill
- pauseSkill
- presentationSkill
- rtkSkill
- setup-contextSkill
- write-like-meSkill
- audit-bugsSkill
- audit-depsSkill
- audit-qualitySkill
- audit-securitySkill
- benchmarkSkill
- cmake-styleSkill
- cpp-classSkill
- cpp-commentsSkill
- cpp-projectSkill
- cpp-styleSkill
- better-explain-docSkill
- better-html-styleSkill
- better-protocol-docSkill
- docs-updateSkill
- explain-docSkill
- html-docSkill
- html-styleSkill
- protocol-docSkill
- readme-styleSkill
- reportSkill
- wiki-styleSkill
- ci-cdSkill
- git-commitSkill
- git-conventionsSkill
- pre-commitSkill
- legal-checkSkill
- legal-setupSkill
- licenseSkill
- libutils-exceptionSkill
- libutils-installSkill
- libutils-setupSkill
- libutilsSkill
- python-classSkill
- python-commentsSkill
- python-projectSkill
- python-styleSkill
- auditSkill
- cppSkill
- devSkill
- docSkill
- gitSkill
- legalSkill
- pythonSkill
- setup-projectSkill
- styleSkill
- setup-studioSkill
- The first 60 shown.
The file
Files
Documentation site (better-html-doc)
SKILL_DIR = directory of this file. Built on better-html-style (search, home, site navigation) and html-style
(tokens, components, rules): both must sit next to this skill (../). Every fact of the site is read from the project
(its code, README, config, CHANGELOG, commands): never invented; what is planned is marked > [!PLANNED].
1. Ask (one AskUserQuestion call, French), unless already given
- Langues :
Bilingue EN / FR (Recommandé)·Anglais·Français. - Emplacement :
docs/site/ (Recommandé)(sources) +docs/or the gh-pages branch for the built pages · other. - Sections (multiSelect, the ones the project needs pre-described):
Guide utilisateur·Concepts / explications(pages ofbetter-explain-doc) ·Référence(configuration, commands, API, formats;Protocolewithbetter-protocol-doc) ·Ressources(FAQ, glossary, changelog, downloads). Four options at most in the popup: another section (Sécurité...) is typed in "Other", or asked in a second question when the project clearly needs it. - Logo: as
html-style"Logo of the brand" (repository logo / custom SVG / default), only when the site has none yet.
2. Create the site
cp -r SKILL_DIR/templates/site docs/site # site.toml, src/pages/{guide,reference,resources}/*.md, gen/_example.py
# fill site.toml ({{PROJECT}}, {{REPO_URL}}, taglines, sections), write the pages, then:
python3 SKILL_DIR/scripts/build_site.py --site docs/site --out docs/site/out [--version X.Y.Z] [--split]
python3 SKILL_DIR/scripts/check_site.py docs/site/out # 0 error
node SKILL_DIR/scripts/test_search.js docs/site/out [cases.json] # every page found by its title, also with a typo--split: the style / scripts shared by every page go tosite.css/site.js(a big site: smaller pages, one cache); without it each page is self-contained (offline,file://, attachable alone).- The build is deterministic (same sources, same output): commit the sources; build the pages in CI or before publishing.
- Version:
--version, else[site] version, else the last git tag; the commit is added when the site is in a git repository.
3. site.toml
| Table | Keys |
[site] | name, langs (["en","fr"] / ["en"] / ["fr"]), repo (code icon), edit_url (empty: no "Edit this page" link - set it, …/edit/main/docs/site/{path}, only when the user asks for that link), pages_url (sitemap), storage_key, logo (SVG), version, footer, css / js (project additions, tokens only), copy (files copied next to the pages), search_endpoint (a server search) |
[home] | title, tagline, changelog (a Keep a Changelog file: its last 5 versions), links ({href, text}) |
[[sections]] | id, title, desc, icon (the inside of a 24x24 stroke SVG) - in reading order |
[kinds.<name>] | css, js, actions, attrs, label - a kind of page with its own assets (explain, protocol are built in) |
[contexts] | screen = "page#id" → docs-map.json (the ? buttons of an application open the right page; checked) |
A text is a string (every language) or { en = "...", fr = "..." }. @skill/<skill>/<path> points into a sibling skill. |
4. Pages
src/pages/<folder>/<slug>.<en|fr>.md (<slug>.md on a site of one language); the folders are free, the slug is the file
name of the page (<slug>.html). Front matter (+++ TOML +++):
title, summary (the lead, the search description), section (an id of site.toml), order, keywords (search only),
kind (explain / protocol / a kind of site.toml), level (default level of an explanation page). The FR file needs only
the translated title / summary / keywords; the sections must have the same ids in every language (## Title {#id}).
Markdown (scripts/mdlib.py): #-###### headings ({#id}; # is a section like ##, the page has one h1, its title: a first # Title equal
to it is dropped, a number typed in a title is dropped when it is the number of the section), paragraphs (two spaces at the end of a line: a break),
lists (- * + 1. 1), any depth, blocks inside an item: a fence, a table, a callout, tasks - [ ] - [x]), tables (:---: aligned, outer pipes
optional, | | | = no head row), fences ``` ~~~ (```lang "File title" → title bar + Copy), indented code, > quotes and callouts > [!NOTE]
[!TIP] [!IMPORTANT] [!WARNING] [!CAUTION] [!WARN] [!OK] [!PLANNED] [!SOON] (or {: .warn} / {: .ok} under a quote; two kinds in a row are
two callouts), ---, raw HTML (a line opening a block tag: <details>, <figure>, <table>, <svg>...; closed by its end tag), <!-- comments -->;
inline code (``a`b``), bold, italic, ~~deleted~~, links [text](url "title") and [text](page:slug#id) (checked), images
, <https://autolink>, \* escapes, &entities;, <kbd> <mark> <abbr title> <small> <sub>... (a tag without its end tag is shown
as text); blocks closed by :::: :::html (raw HTML: figures, SVG, steppers), :::details Title (collapsed), :::simple / :::technical [tldr]
(explanation levels), :::message NAME code (a protocol message).
- A table keeps what its columns need (
min-widthon its first row, from its text: words whole, a phrase up to 20 characters on one line, never a word per line). One that can fit a phone stays on it; else it scrolls in its box there and a long text gets a column it reads well in; one too wide even for a tablet lets its long words break at a/or a-. The words are never squeezed, and on paper the table takes the width of the page. - What this Markdown writes and the style skills do not know (a task item, the title of the pager...) is in
templates/markdown.css, added to every page aftersite.css. - Structure of a page: the lead says what the page gives; 2-8
##sections, each a card numbered in the sidebar; a section answers one question; tables for anything with columns; one example per notion; links to the other pages instead of repeating them. - Writing: short sentences, the reader's words, the exact names of the code in
code; every page in both languages says the same (same sections, same examples).
5. Generated pages (gen/*.py)
What exists in the code is generated, not copied: options from the default config, commands from the command table,
API / MCP tools from their definitions, keys from the key map, the changelog. A generator is gen/<name>.py with
pages(ctx) -> [page dicts] (slug, section, order, kind, and per language title, summary, md, keywords) and
optionally search_entries(ctx) (results that are not pages: a setting, a command → {k, l, t, d, u, x}). ctx.site,
ctx.config, ctx.langs, ctx.version, ctx.tr(value, lang), ctx.git(...). See templates/site/gen/_example.py
(a leading _ = not run). A slug can't be both a Markdown page and a generated one.
6. Search
search-index.js holds every page and every section of every page (title, summary, keywords, text) per language, plus the
generator entries; site.js (better-html-style) ranks it (typos, prefixes, letters in order). test_search.js checks that
every page comes first for its title and stays in the top 3 with a typo; add the project's own cases in a JSON file
([["en", "sesend", "session_send"]]) for the words users type.
6b. Accessibility (RGAA 4.1)
Compliant without JavaScript, by the generator and the templates (skip link and <main id="main">, scope on every th,
focusable and named scrolling blocks, no skipped heading level, lang), plus the search shortcut / that the reader can turn off
(footer checkbox; <kbd>Ctrl</kbd>+<kbd>K</kbd> stays). Do not add a script that patches them: fix the template. A project
page written as raw :::html must follow the same rules (a th has its scope, a scrolling block its tabindex="0").
7. Check before delivering
check_site.py: links / anchors /page:links, the RGAA structure of every page (lang, oneh1, no skipped heading level, skip link,th scope, focusable scrolling blocks), EN and FR blocks balanced, no placeholder ({{X}}, TODO, lorem), every page in the index,docs-map.jsontargets, andcheck_style.pyof html-style on every page (contrast, tokens, responsive) - 0 error.test_search.js: 0 FAIL.check_site.py --render(orcheck_render.pyof html-style on the pages): every page really drawn, both themes, 1280 / 768 / 375 px, both languages: 0 error. It runs Firefox on every page: on a big site, first on the home, a page with big tables and a phone width (--render-pages index.html a.html).- Screenshots (
check_render.py --shots DIR): the home and a page, light and dark, desktop and phone, looked at; the search opened with a typo. A long or crowded content is worth a try: a table of 20 columns, a word of 100 characters, a very long title or project name. - The site of claude-cluster (
tools/claude-cluster/docs/siteof the ai-utils repository) is the reference of what a finished site looks like (generated pages, contextual help, embedded in a binary).
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

