Skip to content

TsukiNi22/ai-utils / skills/docs/wiki-style

wiki-style

Flagged

FileKindSize
SKILL.mdskill md8.7 KB
requires.txtmarkdown13 B
scripts/check_wiki.pyexecutablescript8.7 KB
templates/Guide.mdmarkdown1.3 KB
templates/Home.mdmarkdown1.6 KB
templates/Section.mdmarkdown839 B
templates/Sections.mdmarkdown666 B
templates/Tools-Preview.mdmarkdown355 B
templates/Workflow.mdmarkdown744 B
templates/_Footer.mdmarkdown259 B
templates/_Sidebar.mdmarkdown510 B

scripts/check_wiki.py

View on GitHub
#!/usr/bin/env python3
"""
Check a GitHub wiki folder (the clone of <repo>.wiki.git) against the rules of the user's wiki style.

Usage:
    check_wiki.py <wiki-folder> [--strict]

Checks:
- Home.md, _Sidebar.md and _Footer.md exist; Home starts with the version stamp (`> [!WARNING]` up to date as of ...);
- every page is linked from _Sidebar.md;
- links to a page (`[x](Page)`, `[x](Page#anchor)`, `[x](#anchor)`): the page exists (no `.md`), the anchor is a heading
  of the page (GitHub slug: lower case, punctuation removed, spaces -> `-`);
- a page does not start with a `# Title` (GitHub shows the file name);
- callouts are `> [!NOTE|TIP|IMPORTANT|WARNING|CAUTION]`;
- fenced code blocks have a language and are closed;
- tables: the same number of columns on every row, the header separator right below the header;
- a Table of Contents lists every `##` of the page (warning);
- no emoji.
Errors fail (exit 1); the warnings fail only with --strict.
"""

import argparse
import re
import sys
import unicodedata
from collections.abc import Iterator
from pathlib import Path
from urllib.parse import unquote

CALLOUTS = {"NOTE", "TIP", "IMPORTANT", "WARNING", "CAUTION"}
EMOJI = re.compile("[\U0001F300-\U0001FAFF☀-➿⭐⭕]")
HEADING = re.compile(r"^(#{1,6})\s+(.*?)\s*#*\s*$")
LINK = re.compile(r"(?<!!)\[[^\]]*\]\(([^()\s]*(?:\([^()\s]*\)[^()\s]*)*)\)")
CODE_SPAN = re.compile(r"`[^`]*`")

def slug(heading: str) -> str:
    """Anchor GitHub gives to a heading."""
    text = re.sub(r"[`*_]", "", heading.strip().lower())
    text = re.sub(r"\[([^\]]*)\]\([^)]*\)", r"\1", text)
    text = "".join(c for c in text if c in " -" or unicodedata.category(c)[0] in "LN")
    return text.replace(" ", "-")

def split_row(line: str) -> list[str]:
    line = re.sub(r"`[^`]*`", lambda m: m.group(0).replace("|", "\0"), line.strip())
    line = re.sub(r"\\\|", "\0", line)
    return line.strip("|").split("|")

class Page:
    def __init__(self, path: Path) -> None:
        self.path = path
        self.name = path.stem
        self.lines = path.read_text(encoding="utf-8").splitlines()
        self.headings: list[tuple[int, int, str]] = []  # (line, level, text)
        self.anchors: set[str] = set()
        self.code: set[int] = set()  # lines inside a fenced block (fences included)
        self.problems: list[tuple[str, int, str]] = []  # (kind, line, message)
        self.scan()

    def problem(self, kind: str, line: int, message: str) -> None:
        self.problems.append((kind, line, message))

    def scan(self) -> None:
        fence = None
        seen: dict[str, int] = {}
        for i, line in enumerate(self.lines, 1):
            m = re.match(r"^\s*(`{3,}|~{3,})\s*(\S*)", line)
            if m and fence is None:
                fence = (m.group(1)[0], len(m.group(1)), i)
                self.code.add(i)
                if not m.group(2):
                    self.problem("error", i, "code block without a language")
                continue
            if fence is not None:
                self.code.add(i)
                if re.match(r"^\s*" + re.escape(fence[0]) + "{" + str(fence[1]) + r",}\s*$", line):
                    fence = None
                continue
            h = HEADING.match(line)
            if h:
                text = h.group(2)
                self.headings.append((i, len(h.group(1)), text))
                base = slug(text)
                n = seen.get(base, 0)
                seen[base] = n + 1
                self.anchors.add(base if n == 0 else f"{base}-{n}")
        if fence is not None:
            self.problem("error", fence[2], "code block never closed")

    def text_lines(self) -> Iterator[tuple[int, str]]:
        for i, line in enumerate(self.lines, 1):
            if i not in self.code:
                yield i, line

    def check_style(self) -> None:
        first = next((l for l in self.lines if l.strip()), "")
        if re.match(r"^# ", first) and not self.name.startswith("_"):
            self.problem("warning", 1, "starts with a `# Title` (GitHub shows the file name as the title)")
        for i, line in self.text_lines():
            m = re.match(r"^>\s*\[!(\w+)\]", line)
            if m and m.group(1) not in CALLOUTS:
                self.problem("error", i, f"unknown callout [!{m.group(1)}]")
            if EMOJI.search(line):
                self.problem("error", i, "emoji")
        self.check_tables()
        self.check_toc()

    def check_tables(self) -> None:
        rows: list[tuple[int, str]] = []
        for i, line in list(self.text_lines()) + [(len(self.lines) + 1, "")]:
            if line.lstrip().startswith("|"):
                rows.append((i, line))
                continue
            if rows:
                self.check_table(rows)
                rows = []

    def check_table(self, rows: list[tuple[int, str]]) -> None:
        head = rows[0][0]
        if len(rows) < 2 or not re.match(r"^\s*\|?\s*:?-+", rows[1][1]):
            self.problem("error", head, "table without a header separator right below the header")
            return
        count = len(split_row(rows[0][1]))
        for i, line in rows[1:]:
            if len(split_row(line)) != count:
                self.problem("error", i, f"table row with {len(split_row(line))} columns (header: {count})")

    def check_toc(self) -> None:
        toc = next((i for i, lv, t in self.headings if lv == 2 and t.lower() == "table of contents"), None)
        if toc is None:
            return
        linked = set()
        for i, line in self.text_lines():
            if i > toc and line.startswith(" - ") or (i > toc and re.match(r"^\s+- ", line)):
                linked.update(unquote(a) for a in re.findall(r"\(#([^)]*)\)", line))
            elif i > toc and linked and line.strip() and not line.lstrip().startswith("-"):
                break
        for i, lv, t in self.headings:
            if lv == 2 and i != toc and slug(t) not in linked:
                self.problem("warning", i, f"`## {t}` is not in the Table of Contents")

def main() -> int:
    parser = argparse.ArgumentParser(description="Check a GitHub wiki folder against the user's wiki style")
    parser.add_argument("folder", type=Path)
    parser.add_argument("--strict", action="store_true", help="the warnings fail too")
    args = parser.parse_args()
    folder: Path = args.folder
    if not folder.is_dir():
        sys.stderr.write(f"error: {folder} is not a folder\n")
        return 2
    pages = {p.stem.lower(): Page(p) for p in sorted(folder.glob("*.md"))}
    if not pages:
        sys.stderr.write(f"error: no .md page in {folder}\n")
        return 2
    missing = [f"{need}.md" for need in ("Home", "_Sidebar", "_Footer") if need.lower() not in pages]
    for name in missing:
        print(f"error: {name} is missing")
    for page in pages.values():
        page.check_style()
        for i, line in page.text_lines():
            for target in LINK.findall(CODE_SPAN.sub("", line)):
                if re.match(r"^(https?:|mailto:|//)", target):
                    continue
                name, _, anchor = unquote(target).partition("#")
                if name.endswith(".md"):
                    page.problem("error", i, f"link to `{name}`: no `.md` in a wiki link")
                    name = name[:-3]
                dest = page if not name else pages.get(name.replace("%20", "-").lower())
                if dest is None:
                    page.problem("error", i, f"link to a page that does not exist: `{name}`")
                elif anchor and anchor.lower() not in {a.lower() for a in dest.anchors}:
                    page.problem("error", i, f"link to `{name or page.name}#{anchor}`: no such heading")
    home = pages.get("home")
    if home is not None:
        first = next((l for l in home.lines if l.strip()), "")
        stamp = "\n".join(home.lines[:3])
        if not (first.startswith("> [!WARNING]") and "up to date as of" in stamp):
            home.problem("warning", 1, "Home does not start with the version stamp (`> [!WARNING]` up to date as of ...)")
    side = pages.get("_sidebar")
    if side is not None:
        linked = {unquote(t).partition("#")[0].lower() for _, l in side.text_lines() for t in LINK.findall(CODE_SPAN.sub("", l))}
        for key, page in pages.items():
            if not key.startswith("_") and key != "home" and key not in linked:
                page.problem("warning", 0, "page not linked from _Sidebar.md")
    errors, warnings = len(missing), 0
    for page in pages.values():
        for kind, line, message in sorted(page.problems, key=lambda p: p[1]):
            print(f"{page.path.name}:{line}: {kind}: {message}")
            errors += kind == "error"
            warnings += kind == "warning"
    print(f"== {len(pages)} page(s): {errors} error(s), {warnings} warning(s)")
    return 1 if errors or (args.strict and warnings) 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: 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