Skip to content

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

better-html-doc

Verified

scripts/check_site.py

View on GitHub
#!/usr/bin/env python3
# =============================================================================
# check_site.py - checks of a built better-html-doc site
#   check_site.py <site dir> [--no-style] [--allow-placeholder PAGE ...] [--render] [--render-pages PAGE ...]
#   - every page passes check_style.py of html-style (self-contained, contrast, tokens, responsive rules)
#   - every local link (href / src) points to a file of the site, every #fragment to an id of its page
#   - a bilingual site: every page has as many EN as FR blocks; no placeholder text ({{X}}, a to-do mark, lorem ipsum...)
#   - docs-map.json (contextual help): every screen points to a page / id that exists
#   - the search index lists every page
#   - --render: the pages really drawn (check_render.py of html-style: contrast, what sticks out, words cut, both themes, 3 widths), all of them or --render-pages
# exit 1 when something is wrong
# =============================================================================

import argparse
import json
import re
import subprocess
import sys
import tempfile
from html.parser import HTMLParser
from pathlib import Path

CHECK_STYLE = Path(__file__).resolve().parents[2] / "html-style" / "scripts" / "check_style.py"
CHECK_RENDER = CHECK_STYLE.with_name("check_render.py")
PLACEHOLDER = re.compile(r"\{\{[A-Z_]+\}\}|\b(?:(?i:lorem ipsum)|TODO|FIXME|TBD|XXX)\b")

class Page(HTMLParser):
    def __init__(self) -> None:
        super().__init__()
        self.ids: set[str] = set()
        self.links: list[str] = []
        self.langs: dict[str, int] = {"en": 0, "fr": 0}
        self.text: list[str] = []
        self.skip = 0
        self.levels: list[int] = []  # RGAA 9.1: the headings
        self.lang = ""  # RGAA 8.3
        self.page = ""  # data-page of <html>: "graph" is the canvas application of html-doc, not a page of text
        self.skip_link = False  # RGAA 12.7
        self.main_id = ""
        self.no_scope = 0  # RGAA 5.7: th without scope
        self.not_focusable = 0  # RGAA 7.3: a block that scrolls without tabindex

    def handle_starttag(self, tag: str, attrs: list) -> None:
        a = dict(attrs)
        if "id" in a:
            self.ids.add(a["id"])
        for key in ("href", "src"):
            if a.get(key):
                self.links.append(a[key])
        if tag == "html":
            self.lang = a.get("lang", "")
            self.page = a.get("data-page", "")
        if re.fullmatch(r"h[1-6]", tag):
            self.levels.append(int(tag[1]))
        if tag == "main":
            self.main_id = a.get("id", "")
        if tag == "a" and "skip-link" in a.get("class", "").split():
            self.skip_link = a.get("href", "") == "#" + self.main_id or not self.main_id
        if tag == "th" and "scope" not in a:
            self.no_scope += 1
        if (tag == "pre" or (tag == "div" and "table-wrap" in a.get("class", "").split())) and "tabindex" not in a:
            self.not_focusable += 1
        if a.get("data-lang") in self.langs:
            self.langs[a["data-lang"]] += 1
        if tag in ("script", "style", "pre", "code"):
            self.skip += 1

    def handle_endtag(self, tag: str) -> None:
        if tag in ("script", "style", "pre", "code"):
            self.skip -= 1

    def handle_data(self, data: str) -> None:
        if not self.skip:
            self.text.append(data)

def accessibility(name: str, p: Page) -> list[str]:
    """The RGAA criteria that a page can break by its markup alone (the generator writes them: a failure is a bug of the skill)."""
    found: list[str] = []
    if p.page == "graph":  # an interactive canvas (html-doc build_graph.mjs): not covered by the checks of a text page
        return found
    if not p.lang:
        found.append("%s: <html> without lang (RGAA 8.3)" % name)
    if p.levels.count(1) != 1:
        found.append("%s: %d h1, one expected (RGAA 9.1)" % (name, p.levels.count(1)))
    for before, after in zip(p.levels, p.levels[1:]):
        if after > before + 1:
            found.append("%s: heading level h%d after h%d (RGAA 9.1)" % (name, after, before))
            break
    if not p.skip_link:
        found.append("%s: no skip link to the main region (RGAA 12.7)" % name)
    if not p.main_id:
        found.append("%s: <main> without id, the target of the skip link (RGAA 12.7)" % name)
    if p.no_scope:
        found.append("%s: %d th without scope (RGAA 5.7)" % (name, p.no_scope))
    if p.not_focusable:
        found.append("%s: %d scrolling block(s) (pre, table) without tabindex (RGAA 7.3)" % (name, p.not_focusable))
    return found

def main() -> int:
    ap = argparse.ArgumentParser(description="Check a built better-html-doc site")
    ap.add_argument("site")
    ap.add_argument("--no-style", action="store_true")
    ap.add_argument("--allow-placeholder", nargs="*", default=["changelog.html"], help="pages whose text may hold TODO / TBD (a changelog)")
    ap.add_argument("--render", action="store_true", help="also draw the pages in a browser (check_render.py, needs firefox)")
    ap.add_argument("--render-pages", nargs="*", default=[], help="with --render: only these pages (a big site: the home, a page with big tables)")
    args = ap.parse_args()
    site = Path(args.site)
    pages = sorted(site.glob("*.html"))
    if not pages:
        print("ERROR no page in %s" % site)
        return 1
    errors: list[str] = []
    parsed: dict[str, Page] = {}
    for path in pages:
        p = Page()
        p.feed(path.read_text(encoding="utf-8"))
        parsed[path.name] = p
    bilingual = any(p.langs["fr"] for p in parsed.values())
    for name, p in parsed.items():
        if bilingual and p.langs["en"] != p.langs["fr"]:
            errors.append("%s: %d EN blocks but %d FR blocks" % (name, p.langs["en"], p.langs["fr"]))
        errors += accessibility(name, p)
        found = PLACEHOLDER.search(" ".join(p.text)) if name not in args.allow_placeholder else None
        if found:
            errors.append("%s: placeholder text %r" % (name, found.group(0)))
        for link in p.links:
            if re.match(r"^(https?:|ftp:|tel:|mailto:|data:|javascript:)", link) or link.startswith("/"):
                continue
            target, _, frag = link.partition("#")
            target = target.split("?")[0]
            if not target:
                if frag and frag not in p.ids and frag != "top":
                    errors.append("%s: #%s not found" % (name, frag))
                continue
            if not (site / target).exists():
                errors.append("%s: link %s: no such file" % (name, link))
            elif frag and target in parsed and frag not in parsed[target].ids:
                errors.append("%s: link %s: no id %s" % (name, link, frag))
    mapping = site / "docs-map.json"
    if mapping.exists():
        for screen, target in json.loads(mapping.read_text(encoding="utf-8")).items():
            page, _, frag = target.partition("#")
            if page + ".html" not in parsed or (frag and frag not in parsed[page + ".html"].ids):
                errors.append("docs-map.json: %s -> %s does not exist" % (screen, target))
    index = site / "search-index.json"
    if not index.exists():
        errors.append("search-index.json missing")
    else:
        listed = {e["u"].split("#")[0] for e in json.loads(index.read_text(encoding="utf-8"))["entries"]}
        for name in parsed:
            if name != "index.html" and name not in listed:
                errors.append("%s: not in the search index" % name)
    if not args.no_style:
        if not CHECK_STYLE.exists():
            errors.append("html-style/scripts/check_style.py not found next to this skill (--no-style to skip)")
        else:
            shared = site / "site.css"
            with tempfile.TemporaryDirectory() as folder:
                for path in pages:
                    page = path.read_text(encoding="utf-8")
                    if shared.exists():  # a --split site: its style inlined in a copy, check_style reads the page alone
                        page = page.replace('<link rel="stylesheet" href="site.css">', "<style>" + shared.read_text(encoding="utf-8") + "</style>", 1)
                    copy = Path(folder) / path.name
                    copy.write_text(page, encoding="utf-8")
                    run = subprocess.run([sys.executable, str(CHECK_STYLE), str(copy)], capture_output=True, text=True)
                    if run.returncode != 0:
                        lines = [x for x in run.stdout.splitlines() if x.strip()]
                        errors.append("%s: check_style: %s" % (path.name, "; ".join(lines[-6:]) if lines else run.stderr.strip()))
    if args.render:
        chosen = [site / name for name in args.render_pages] or pages
        run = subprocess.run([sys.executable, str(CHECK_RENDER), *[str(path) for path in chosen]], capture_output=True, text=True)
        where = ""
        for line in run.stdout.splitlines():
            head = re.match(r"^== (?:.*/)?([^/]+?): (.*?): \d+ error", line)
            if head:
                where = "%s (%s)" % (head.group(1), head.group(2))
            elif line.startswith("  error: "):
                errors.append("%s: check_render: %s" % (where, line[9:]))
        if run.returncode == 2:
            errors.append("check_render: no result: " + run.stderr.strip())
    for e in sorted(set(errors), key=errors.index):
        print("ERROR " + e)
    print("%d pages checked, %d error(s)" % (len(pages), len(set(errors))))
    return 1 if errors else 0

if __name__ == "__main__":
    sys.exit(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: 197kUpdated 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