Skip to content

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

better-html-doc

Verified

scripts/build_site.py

View on GitHub
#!/usr/bin/env python3
# =============================================================================
# build_site.py - generator of a documentation site in the better-html-style (deterministic, no dependency)
#
#   build_site.py [--site DIR] --out DIR [--version X] [--commit H] [--split]
#
#   DIR/site.toml                     the site: name, languages, sections, home, kinds, contextual help map
#   DIR/src/pages/**/<slug>.<lang>.md the pages (+++ TOML front matter +++: title, summary, section, order, keywords, kind, level)
#                                     (<slug>.md on a site of one language)
#   DIR/gen/*.py                      optional generators: pages(ctx) -> pages, search_entries(ctx) -> extra search entries
#   -> OUT/<slug>.html (self-contained, every language in one file), index.html, search-index.json / .js, sitemap.xml,
#      docs-map.json, logo.svg; --split: the style / script every page repeats moved to site.css / site.js
# html-style (new_page.py) and better-html-style (site.css, site.js, search.html) are sibling skills of this one
# =============================================================================

import argparse
import html
import importlib.util
import json
import re
import subprocess
import sys
import tempfile
import tomllib
from pathlib import Path

HERE = Path(__file__).resolve().parent
SKILLS = HERE.parent.parent          # the folder holding the skills (docs/ in the repository, ~/.claude/skills installed)
sys.path.insert(0, str(HERE))
import mdlib  # noqa: E402

NEW_PAGE = SKILLS / "html-style" / "scripts" / "new_page.py"
STYLE = SKILLS / "better-html-style" / "templates"
MARKDOWN_CSS = HERE.parent / "templates" / "markdown.css"  # what mdlib.py writes and the style skills do not know (a task item, the title of the pager)
KNOWN_LANGS = ("en", "fr")
# the kinds of page the sibling skills bring (a [kinds.<name>] table of site.toml adds / overrides one)
BUILTIN_KINDS = {
    "explain": {"css": ["@skill/explain-doc/templates/explain.css", "@skill/better-explain-doc/templates/explain-site.css"],
                "js": ["@skill/explain-doc/templates/explain.js"], "actions": "@skill/explain-doc/templates/actions.html",
                "attrs": {"data-page": "explain"}, "label": {"en": "Explanation", "fr": "Explication"}},
    "protocol": {"css": ["@skill/better-protocol-doc/templates/protocol.css"], "js": [], "actions": "", "attrs": {"data-page": "protocol"},
                 "label": {"en": "Protocol", "fr": "Protocole"}},
}
SEARCH_SVG = '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" aria-hidden="true"><circle cx="11" cy="11" r="7"/><path d="M20 20l-4-4"/></svg>'
TILE_SVG = '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">%s</svg>'
DEFAULT_ICON = '<path d="M5 4h14v16H5zM9 8h6M9 12h6M9 16h4"/>'
REPO_LINK = ('<a class="icon-btn" href="%s" aria-label="GitHub repository" data-i18n-aria-label title="GitHub repository" data-i18n-title>'
             '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">'
             '<path d="M8 6l-5 6 5 6M16 6l5 6-5 6"/></svg></a>')

# ----- context -----
class Context:
    """What a generator (gen/*.py) gets: the config, the folders, the languages, the version, tr() and the Markdown renderer."""

    def __init__(self, args: argparse.Namespace):
        self.site = Path(args.site).resolve()
        config = self.site / "site.toml"
        if not config.exists():
            raise SystemExit("%s: no site.toml (start from the template of better-html-doc)" % self.site)
        self.config = tomllib.loads(config.read_text(encoding="utf-8"))
        self.out = Path(args.out).resolve()
        self.split = args.split
        s = self.config.setdefault("site", {})
        self.langs = list(s.get("langs", ["en"]))
        for lang in self.langs:
            if lang not in KNOWN_LANGS:
                raise SystemExit("site.toml: language %r (the switch of html-style knows %s)" % (lang, ", ".join(KNOWN_LANGS)))
        self.name = s.get("name", self.site.name)
        self.version = args.version or s.get("version", "") or self.git("describe", "--tags", "--abbrev=0")
        self.commit = args.commit or self.git("rev-parse", "--short", "HEAD")
        self.renderer = {lang: mdlib.Renderer(lang) for lang in self.langs}

    def git(self, *cmd: str) -> str:
        try:
            return subprocess.run(["git", "-C", str(self.site), *cmd], capture_output=True, text=True, check=True).stdout.strip()
        except (OSError, subprocess.CalledProcessError):
            return ""

    def tr(self, value: str | dict, lang: str) -> str:
        """A text of site.toml: a plain string (every language) or {en = "...", fr = "..."}."""
        if isinstance(value, dict):
            return value.get(lang) or value.get("en") or next(iter(value.values()), "")
        return value or ""

def both(ctx: Context, texts: dict) -> str:
    """One text per language: a span per language on a bilingual site, the text alone else."""
    if len(ctx.langs) == 1:
        return texts[ctx.langs[0]]
    return "".join('<span data-lang="%s">%s</span>' % (lang, texts[lang]) for lang in ctx.langs)

def both_tr(ctx: Context, value: str | dict) -> str:
    return both(ctx, {lang: esc(ctx.tr(value, lang)) for lang in ctx.langs})

def blocks(ctx: Context, parts: dict) -> str:
    """Block content per language (divs on a bilingual site)."""
    if len(ctx.langs) == 1:
        return parts[ctx.langs[0]]
    return "".join('<div data-lang="%s">%s</div>' % (lang, parts[lang]) for lang in ctx.langs)

def esc(text: str) -> str:
    return html.escape(text, quote=True)

def resolve(ctx: Context, path: str) -> Path:
    """@skill/<skill>/... = a file of a sibling skill, else a path relative to the site."""
    if path.startswith("@skill/"):
        return SKILLS / path[len("@skill/"):]
    return (ctx.site / path).resolve()

# ----- pages -----
def load_static_pages(ctx: Context) -> dict[str, dict]:
    pages: dict[str, dict] = {}
    root = ctx.site / "src" / "pages"
    for path in sorted(root.rglob("*.md")):
        stem = path.name[:-3]
        slug, _, lang = stem.rpartition(".")
        if not slug or lang not in KNOWN_LANGS:
            if len(ctx.langs) > 1:
                raise SystemExit("%s: on a site of several languages the name is <slug>.<%s>.md" % (path, "|".join(ctx.langs)))
            slug, lang = stem, ctx.langs[0]
        if lang not in ctx.langs:
            raise SystemExit("%s: language %s is not in [site] langs" % (path, lang))
        front, body = mdlib.split_front(path.read_text(encoding="utf-8"))
        for key in ("title", "section"):
            if key not in front and (key == "title" or lang == ctx.langs[0]):
                raise SystemExit("%s: '%s' missing in the front matter" % (path, key))
        page = pages.setdefault(slug, {"slug": slug, "section": "", "order": 100, "kind": "", "level": "", "source": path})
        page[lang] = {"title": front["title"], "summary": front.get("summary", ""), "md": body, "keywords": front.get("keywords", "")}
        if lang == ctx.langs[0]:
            page.update(section=front["section"], order=front.get("order", 100), kind=front.get("kind", ""), level=front.get("level", ""), source=path)
    return pages

def load_generated_pages(ctx: Context) -> tuple[dict[str, dict], list[dict]]:
    pages: dict[str, dict] = {}
    extra: list[dict] = []
    folder = ctx.site / "gen"
    if folder.is_dir():
        sys.path.insert(0, str(folder))
    for path in sorted(folder.glob("*.py")) if folder.is_dir() else []:
        if path.name.startswith("_"):
            continue
        spec = importlib.util.spec_from_file_location("gen_" + path.stem, path)
        module = importlib.util.module_from_spec(spec)
        spec.loader.exec_module(module)
        for page in module.pages(ctx) if hasattr(module, "pages") else []:
            page.setdefault("order", 100)
            page.setdefault("kind", "")
            page.setdefault("level", "")
            pages[page["slug"]] = page
        if hasattr(module, "search_entries"):
            extra += module.search_entries(ctx)
    return pages, extra

def split_sections(blocks_: list[dict]) -> tuple[list[str], list[dict]]:
    """The blocks before the first section (intro) and the sections (id, title, raw, html): a ## line, or a # line (the page has one h1, its title)."""
    intro: list[str] = []
    sections: list[dict] = []
    for b in blocks_:
        if b.get("h") in (1, 2):
            number = len(sections) + 1
            sections.append({"id": b["id"], "title": mdlib.unnumbered(b["title"], number), "raw": mdlib.unnumbered(b["raw"], number), "html": [], "level": b.get("level", "")})
        elif b.get("h"):
            level = ' data-level="%s"' % b["level"] if b.get("level") else ""
            html_b = '<h%d id="%s"%s>%s</h%d>' % (b["h"], b["id"], level, b["title"], b["h"])
            (sections[-1]["html"] if sections else intro).append(html_b)
        else:
            (sections[-1]["html"] if sections else intro).append(b["html"])
    return intro, sections

def parse_page(ctx: Context, page: dict) -> None:
    for lang in ctx.langs:
        if lang not in page:
            raise SystemExit("page %s: the %s version is missing" % (page["slug"], lang))
        d = page[lang]
        markdown = mdlib.without_title(d["md"], d["title"])
        d["intro"], d["sections"] = split_sections(ctx.renderer[lang].render(markdown))
        parts = mdlib.section_texts(markdown)  # the text of each section, for the search index
        for n, s in enumerate(d["sections"]):
            s["text"] = mdlib.plain_text(parts[n + 1] if n + 1 < len(parts) else "")
        d["lead_text"] = mdlib.plain_text(parts[0])
    ids = {lang: [s["id"] for s in page[lang]["sections"]] for lang in ctx.langs}
    if len({tuple(v) for v in ids.values()}) > 1:
        raise SystemExit("page %s: the sections differ between the languages %s" % (page["slug"], ids))
    if page["kind"] and page["kind"] not in kinds(ctx):
        raise SystemExit("page %s: unknown kind %r (%s)" % (page["slug"], page["kind"], ", ".join(kinds(ctx))))

def kinds(ctx: Context) -> dict[str, dict]:
    out = {k: dict(v) for k, v in BUILTIN_KINDS.items()}
    for name, value in ctx.config.get("kinds", {}).items():
        out[name] = {**out.get(name, {"css": [], "js": [], "actions": "", "attrs": {}, "label": name}), **value}
    return out

def ordered(ctx: Context, pages: dict[str, dict]) -> list[dict]:
    rank = {s["id"]: n for n, s in enumerate(ctx.config.get("sections", []))}
    for p in pages.values():
        if p["section"] not in rank:
            raise SystemExit("page %s: unknown section %r (sections of site.toml: %s)" % (p["slug"], p["section"], ", ".join(rank)))
    return sorted(pages.values(), key=lambda p: (rank[p["section"]], p["order"], p["slug"]))

# ----- html -----
def sidebar(ctx: Context, page: dict | None, all_pages: list[dict]) -> str:
    out = ['<aside class="sidebar" id="sidebar">']
    if page and page[ctx.langs[0]]["sections"]:
        out.append('<p data-i18n>On this page</p>')
        for n, s in enumerate(page[ctx.langs[0]]["sections"], 1):
            texts = {lang: esc(page[lang]["sections"][n - 1]["raw"]) for lang in ctx.langs}
            level = ' data-level="%s"' % s["level"] if s.get("level") else ""
            out.append('<a href="#%s"%s>%d. %s</a>' % (s["id"], level, n, both(ctx, texts)))
        out.append("<hr>")
    for sec in ctx.config.get("sections", []):
        out.append('<div class="grp">%s</div>' % both_tr(ctx, sec["title"]))
        for p in all_pages:
            if p["section"] == sec["id"]:
                cls = ' class="cur" aria-current="page"' if page and p["slug"] == page["slug"] else ""
                out.append('<a href="%s.html"%s>%s</a>' % (p["slug"], cls, both(ctx, {lang: esc(p[lang]["title"]) for lang in ctx.langs})))
    out.append("</aside>")
    return "".join(out)

def page_meta(ctx: Context, page: dict) -> str:
    """Last change (git) and the edit link of a page written by hand."""
    source = page.get("source")
    if not source:
        return ""
    items = []
    date = ctx.git("log", "-1", "--format=%cs", "--", str(source))
    if date:
        items.append('<span><span data-i18n>Updated</span> %s</span>' % esc(date))
    edit = ctx.config["site"].get("edit_url", "")
    if edit:
        rel = Path(source).relative_to(ctx.site).as_posix()
        items.append('<a class="edit" href="%s" data-i18n>Edit this page</a>' % esc(edit.replace("{path}", rel)))
    return '<div class="page-meta">%s</div>' % "".join(items) if items else ""

def page_body(ctx: Context, page: dict, all_pages: list[dict]) -> str:
    sec = next(s for s in ctx.config["sections"] if s["id"] == page["section"])
    idx = all_pages.index(page)
    first = ctx.langs[0]
    out = [sidebar(ctx, page, all_pages), "<main>"]
    out.append('<header><div class="page-eyebrow">%s</div><h1>%s</h1><p class="lead">%s</p>%s</header>' % (
        both_tr(ctx, sec["title"]), both(ctx, {lang: esc(page[lang]["title"]) for lang in ctx.langs}),
        both(ctx, {lang: esc(page[lang]["summary"]) for lang in ctx.langs}), page_meta(ctx, page)))
    if any(page[lang]["intro"] for lang in ctx.langs):
        out.append(blocks(ctx, {lang: "".join(page[lang]["intro"]) for lang in ctx.langs}))
    for n, s in enumerate(page[first]["sections"], 1):
        level = ' data-level="%s"' % s["level"] if s.get("level") else ""
        title = both(ctx, {lang: page[lang]["sections"][n - 1]["title"] for lang in ctx.langs})
        out.append('<section id="%s"%s><h2>%d. %s</h2>%s</section>' % (s["id"], level, n, title,
                   blocks(ctx, {lang: "".join(page[lang]["sections"][n - 1]["html"]) for lang in ctx.langs})))
    pager = []
    if idx > 0:
        p = all_pages[idx - 1]
        pager.append('<a href="%s.html"><span data-i18n>Previous</span>%s</a>' % (p["slug"], both(ctx, {lang: esc(p[lang]["title"]) for lang in ctx.langs})))
    else:
        pager.append('<a href="index.html"><span data-i18n>Previous</span><span data-i18n>Home</span></a>')
    if idx + 1 < len(all_pages):
        p = all_pages[idx + 1]
        pager.append('<a class="next" href="%s.html"><span data-i18n>Next</span>%s</a>' % (p["slug"], both(ctx, {lang: esc(p[lang]["title"]) for lang in ctx.langs})))
    out.append('<nav class="pager">%s</nav></main>' % "".join(pager))
    return "".join(out)

def changelog(ctx: Context) -> list[dict]:
    """The versions of a Keep a Changelog file (## [1.2.0] - date / ## 1.2.0): the first line or bullet of each."""
    path = ctx.config.get("home", {}).get("changelog", "")
    if not path or not resolve(ctx, path).exists():
        return []
    out = []
    for m in re.finditer(r"^##\s+\[?v?([\w.\-]+)\]?[^\n]*\n(.*?)(?=^##\s|\Z)", resolve(ctx, path).read_text(encoding="utf-8"), re.S | re.M):
        if m.group(1).lower() == "unreleased":
            continue
        line = next((re.sub(r"^[-*]\s+|^###\s+", "", x).strip() for x in m.group(2).splitlines() if x.strip() and not x.startswith("###")), "")
        text = mdlib.plain_text(line)
        out.append({"version": m.group(1), "text": text if len(text) <= 160 else text[:159].rstrip() + "…"})
    return out

def home_body(ctx: Context, all_pages: list[dict]) -> str:
    home = ctx.config.get("home", {})
    badge = ' <span class="badge">%s%s</span>' % (esc(ctx.version), (" · " + esc(ctx.commit)) if ctx.commit and ctx.version else "") if ctx.version else ""
    out = ['<main><header class="hero"><div class="page-eyebrow">%s%s</div>' % (esc(ctx.name), badge)]
    out.append("<h1>%s</h1>" % both_tr(ctx, home.get("title", {"en": "Documentation", "fr": "Documentation"})))
    if home.get("tagline"):
        out.append('<p class="lead">%s</p>' % both_tr(ctx, home["tagline"]))
    out.append('<div class="sbox">%s<input type="search" autocomplete="off" aria-label="Search" data-i18n-aria-label placeholder="Search the documentation…  ( / )" '
               'data-ph-fr="Rechercher dans la documentation…  ( / )"><ul class="results" hidden></ul></div></header>' % SEARCH_SVG)
    out.append('<div class="grid">')
    for sec in ctx.config.get("sections", []):
        mine = [p for p in all_pages if p["section"] == sec["id"]]
        if not mine:
            continue
        count = '<span class="count">%d <span data-i18n>pages</span></span>' % len(mine) if len(mine) > 1 else ""
        out.append('<a class="tile" href="%s.html">%s%s<h2>%s</h2><p>%s</p></a>' % (
            mine[0]["slug"], count, TILE_SVG % sec.get("icon", DEFAULT_ICON), both_tr(ctx, sec["title"]), both_tr(ctx, sec.get("desc", ""))))
    out.append("</div>")
    changes = changelog(ctx)
    if changes:
        out.append('<section id="changelog"><h2 data-i18n>Changelog</h2><ul class="cl">')
        for c in changes[:5]:
            out.append("<li><b>%s</b><span>%s</span></li>" % (esc(c["version"]), esc(c["text"])))
        out.append("</ul></section>")
    links = home.get("links", [])
    if links:
        out.append('<div class="links">%s</div>' % "".join('<a href="%s">%s</a>' % (esc(link["href"]), both_tr(ctx, link["text"])) for link in links))
    out.append("</main>")
    return "".join(out)

def make_page(ctx: Context, body: str, out: Path, title: str, kind: str = "", level: str = "", wide: bool = False) -> None:
    site = ctx.config["site"]
    known = kinds(ctx)
    k = known.get(kind, {}) if kind else {}
    actions = (STYLE / "search.html").read_text(encoding="utf-8")
    if k.get("actions"):
        actions = resolve(ctx, k["actions"]).read_text(encoding="utf-8") + actions
    if site.get("repo"):
        actions += REPO_LINK % esc(site["repo"])
    with tempfile.TemporaryDirectory() as folder:
        tmp_body, tmp_actions = Path(folder) / "body.html", Path(folder) / "actions.html"
        tmp_body.write_text(re.sub(r"\{\{(?=[A-Z_]+\}\})(?!(?:PROJECT|VERSION)\}\})", "&#123;&#123;", body), encoding="utf-8")  # what a page says of {{NAME}} is text
        tmp_actions.write_text(actions, encoding="utf-8")
        footer = site.get("footer", "") or " · ".join(esc(x) for x in (ctx.name + (" " + ctx.version if ctx.version else ""), ctx.commit, "docs") if x)
        cmd = [sys.executable, str(NEW_PAGE), str(tmp_body), "-o", str(out), "--force",
               "--css", str(STYLE / "site.css"), str(MARKDOWN_CSS), *[str(resolve(ctx, c)) for c in site.get("css", [])],
               "--js", str(STYLE / "site.js"), *[str(resolve(ctx, j)) for j in site.get("js", [])],
               "--actions", str(tmp_actions),
               "--set", "PROJECT=%s" % esc(ctx.name), "TITLE=%s" % esc(title), "STORAGE_KEY=%s" % esc(site.get("storage_key", re.sub(r"\W+", "-", ctx.name.lower()) + "-docs")),
               "FOOTER=%s" % footer, "VERSION=%s" % esc(ctx.version)]
        if len(ctx.langs) > 1:
            cmd.append("--lang-switch")
        attrs = ["%s=%s" % (n, v) for n, v in k.get("attrs", {}).items()]
        if level:
            attrs.append("data-default-level=%s" % level)
        if attrs:
            cmd += ["--attr", *attrs]
        run = subprocess.run(cmd, capture_output=True, text=True)
        if run.returncode != 0:
            raise SystemExit("%s: new_page.py failed: %s%s" % (out.name, run.stdout, run.stderr))
    text = out.read_text(encoding="utf-8")
    text = re.sub(r'(<html\b[^>]*\blang=")[^"]*"', lambda m: m.group(1) + ctx.langs[0] + '"', text, count=1)  # RGAA 8.3, and the words of the page in that language
    logo = site.get("logo", "")
    if logo:
        svg = resolve(ctx, logo).read_text(encoding="utf-8")
        svg = re.sub(r"<\?xml.*?\?>|<!--.*?-->", "", svg, flags=re.S).strip()
        svg = svg if 'class="logo"' in svg else svg.replace("<svg", '<svg class="logo" aria-hidden="true"', 1)
        text = re.sub(r'<svg class="logo".*?</svg>', lambda m: svg, text, count=1, flags=re.S)
    if wide:
        text = text.replace('<div class="layout" id="top">', '<div class="layout wide" id="top">', 1)
    text = text.replace('<a class="brand" href="#top">', '<a class="brand" href="index.html">', 1)
    if logo:
        text = text.replace("</title>", '</title><link rel="icon" type="image/svg+xml" href="logo.svg">', 1)
    if site.get("search_endpoint"):
        text = text.replace("</title>", '</title><meta name="docs-search" content="%s">' % esc(site["search_endpoint"]), 1)
    if k:  # the assets of the kind: a style / script block of their own (the shared ones stay identical on every page)
        css = "\n".join(resolve(ctx, c).read_text(encoding="utf-8") for c in k.get("css", []))
        js = "\n".join(resolve(ctx, j).read_text(encoding="utf-8") for j in k.get("js", []))
        if css:
            text = text.replace("</head>", '<style data-kind="%s">\n%s\n</style>\n</head>' % (kind, css), 1)
        if js:
            text = text.replace("</body>", '<script data-kind="%s">\n%s\n</script>\n</body>' % (kind, js), 1)
    text = text.replace("</body>", '<script src="search-index.js" defer></script>\n</body>', 1)
    out.write_text(text, encoding="utf-8")

# ----- search index -----
def build_index(ctx: Context, all_pages: list[dict], extra: list[dict]) -> list[dict]:
    entries: list[dict] = []
    known = kinds(ctx)
    for p in all_pages:
        kind = p["kind"] or "docs"
        for lang in ctx.langs:
            d = p[lang]
            label = ctx.tr(known[p["kind"]]["label"], lang) if p["kind"] else ""
            entries.append({"k": kind, "l": lang, "t": d["title"], "d": d["summary"] or label, "u": "%s.html" % p["slug"], "x": (d["keywords"] + " " + d["lead_text"])[:300]})
            for s in d["sections"]:
                entries.append({"k": kind, "l": lang, "t": "%s › %s" % (d["title"], s["raw"]), "d": s["text"][:110], "u": "%s.html#%s" % (p["slug"], s["id"]), "x": s["text"][:600]})
    entries += extra
    if len(ctx.langs) == 1:
        for e in entries:
            e.pop("l", None)
    return entries

def split_assets(ctx: Context, names: list[str]) -> None:
    """--split: the style and the scripts every page repeats move to site.css / site.js (the pages stay valid on file://).
    Only the pages of this build: an other page of the folder (the graph.html of html-doc, an app) keeps its own style."""
    style = script = ""
    for path in sorted(ctx.out / name for name in names):
        text = path.read_text(encoding="utf-8")
        m_style = re.search(r"<style>\n(.*?)\n</style>", text, re.S)
        scripts = re.findall(r"<script>\n(.*?)\n</script>", text, re.S)
        if not m_style or len(scripts) != 2:
            raise SystemExit("%s: the page layout changed, cannot split its assets" % path.name)
        if style and (style != m_style.group(1) or script != "\n".join(scripts)):
            raise SystemExit("%s: its style / script differ from the other pages" % path.name)
        style, script = m_style.group(1), "\n".join(scripts)
        text = text.replace(m_style.group(0), '<link rel="stylesheet" href="site.css">', 1)
        text = re.sub(r"<script>\n.*?\n</script>\n", "", text, flags=re.S)
        text = text.replace('<script src="search-index.js" defer></script>', '<script src="site.js"></script>\n<script src="search-index.js" defer></script>', 1)
        path.write_text(text, encoding="utf-8")
    (ctx.out / "site.css").write_text(style, encoding="utf-8")
    (ctx.out / "site.js").write_text(script, encoding="utf-8")

def write_site(ctx: Context) -> None:
    if not NEW_PAGE.exists() or not (STYLE / "site.css").exists():
        raise SystemExit("the skills html-style and better-html-style must sit next to better-html-doc (%s)" % SKILLS)
    ctx.out.mkdir(parents=True, exist_ok=True)
    pages, extra = load_generated_pages(ctx)
    static = load_static_pages(ctx)
    for slug in static:
        if slug in pages:
            raise SystemExit("page %s exists as source and as generated page" % slug)
    pages.update(static)
    if not pages:
        raise SystemExit("no page: write src/pages/<slug>.<lang>.md")
    for p in pages.values():
        parse_page(ctx, p)
    all_pages = ordered(ctx, pages)
    for p in all_pages:
        title = "%s - %s" % (p[ctx.langs[0]]["title"], ctx.name)
        make_page(ctx, page_body(ctx, p, all_pages), ctx.out / ("%s.html" % p["slug"]), title, p["kind"], p["level"])
    make_page(ctx, home_body(ctx, all_pages), ctx.out / "index.html", "%s documentation" % ctx.name, wide=True)
    payload = {"version": ctx.version, "commit": ctx.commit, "entries": build_index(ctx, all_pages, extra)}
    dumped = json.dumps(payload, ensure_ascii=False, separators=(",", ":"), sort_keys=True)
    (ctx.out / "search-index.json").write_text(dumped, encoding="utf-8")
    (ctx.out / "search-index.js").write_text("window.DOCS_INDEX=" + dumped + ";", encoding="utf-8")
    site = ctx.config["site"]
    if site.get("logo"):
        (ctx.out / "logo.svg").write_text(resolve(ctx, site["logo"]).read_text(encoding="utf-8"), encoding="utf-8")
    if ctx.config.get("contexts"):
        (ctx.out / "docs-map.json").write_text(json.dumps(ctx.config["contexts"], indent=1, sort_keys=True), encoding="utf-8")
    if site.get("pages_url"):
        urls = ["index.html"] + ["%s.html" % p["slug"] for p in all_pages]
        (ctx.out / "sitemap.xml").write_text('<?xml version="1.0" encoding="UTF-8"?>\n<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n'
                                             + "".join("<url><loc>%s%s</loc></url>\n" % (site["pages_url"], u) for u in urls) + "</urlset>\n", encoding="utf-8")
    for name in site.get("copy", []):  # files given as they are (downloads, images)
        source = resolve(ctx, name)
        target = ctx.out / source.name
        target.write_bytes(source.read_bytes())
    if ctx.split:
        split_assets(ctx, ["index.html"] + ["%s.html" % p["slug"] for p in all_pages])
    print("built %d pages + home + index in %s (%s%s)" % (len(all_pages), ctx.out, ctx.name, (" " + ctx.version) if ctx.version else ""))

def main() -> None:
    ap = argparse.ArgumentParser(description="Generator of a documentation site in the better-html-style")
    ap.add_argument("--site", default=".", help="the folder of site.toml (default: the current one)")
    ap.add_argument("--out", required=True)
    ap.add_argument("--version", default="", help="shown in the top bar and on the home (default: [site] version, else the last git tag)")
    ap.add_argument("--commit", default="")
    ap.add_argument("--split", action="store_true", help="the shared style / script in site.css / site.js (smaller pages)")
    write_site(Context(ap.parse_args()))

if __name__ == "__main__":
    main()
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: 198kUpdated 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: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated 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: 194kUpdated Claude CodeCodexVerifiedInstall