Skip to content

TsukiNi22/ai-utils / skills/docs/better-explain-doc

better-explain-doc

Verified

Explanation pages in a better-html-doc site

SKILL_DIR = directory of this file. The content rules are those of explain-doc (../explain-doc/SKILL.md: the two levels, the 8 sections, readable steps, accuracy - every number computed, never from memory): load it first. This skill only changes where the page lives: a page of a better-html-doc site (../better-html-doc), written in Markdown, with the components of explain-doc (explain.css / explain.js, loaded only on these pages by the built-in explain kind).

1. Ask (AskUserQuestion, French) unless known

  • Niveau par défaut : Simple (Recommandé) · Technique.
  • The site, its languages and its sections come from its site.toml (no site yet: create it with better-html-doc first, a Concepts section for the explanations).

2. Write the page

src/pages/concepts/<slug>.<lang>.md - start from SKILL_DIR/templates/pages/concepts/how-caching-works.*.md:

+++
title = "How the cache works"
summary = "Why a second run is fast, explained simply or technically."
section = "concepts"
kind = "explain"
level = "simple"          # the level shown at the first visit (the reader's choice is kept after)
+++

:::simple tldr
**In one sentence:** ...
:::

:::technical tldr
**Definition:** ...
:::

## The idea {#idea}
:::simple
analogy, plain words
:::
:::technical
model, vocabulary, comparison
:::
  • :::simple / :::technical = shown at that level only; text outside them is shown at both levels (diagrams, playgrounds, tables that fit both). A ### inside a level block belongs to that level.
  • The explain-doc components go in :::html blocks, unchanged: stepper (figure.stepper + ol.captions + svg with data-show / data-hl / data-at), formula (div.formula + MathML), playground (div.playground + a page script calling explain.play), dfn data-def, div.compare, details.quiz. Arrows by data-from / data-to (computed).
  • Bilingual site: each language file has its own copy of the figures - give their ids a language prefix (en-q, fr-q) so they stay unique on the page.
  • Sections in the order of explain-doc §3 (the idea, how it works, how fast, try it, worked example, pitfalls, check yourself, glossary and sources), 6-9 of them.

3. Build and check

The commands of better-html-doc (build_site.py, check_site.py, test_search.js), check_render.py of html-style on the built page (0 error: both levels, both languages, both themes), then look at the page: the stepper played to its end, a playground moved, at 1280 and 390 px, light and dark. The level switch sits in the top bar (?level=technical in a link opens that level; the choice is shared with the other explanation pages of the site); under 640px the search takes a row under the bar, under 400px a bilingual page gives the place of the logo to the two switches.

slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 196kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 193kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 193kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 193kUpdated Claude CodeCodexVerifiedInstall