AlexandClaude Opus 4.8
5180dec43e
Some pandoc versions (incl. the pinned 3.5) render scdoc bullet lists as a series of `> ·` blockquotes instead of a Markdown list, which made the STYLE sections look broken. Post-process the generated Markdown to collapse that artifact back into real `- item` bullets, independent of the pandoc version. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Wiki sync
The scdoc man pages under man/ are the single source of truth
for module documentation. The GitHub wiki module pages are generated from them by
generate.py and kept in sync automatically by the
wiki.yml workflow on every push to master that
touches man/** or this tooling.
Files
mapping.json— maps each wiki page to the ordered list of man-page basenames that compose it. Several man pages are concatenated into one aggregated page (e.g.Module:-Hyprland← the fourwaybar-hyprland-*pages). Add an entry here when you add a new man page — the workflow fails the mapping check otherwise.generate.py—scdoc → roff → pandoc → gfm, strips theNAME/FILES/AUTHORman sections, and writes oneModule:-*.mdper mapping entry.extras/<Page>.md— optional hand-maintained appendix (screenshots, showcase snippets that have no man equivalent), appended verbatim after the generated body.
The generator also keeps _Sidebar.md in sync: any Module:-* page in the mapping
that is not yet linked in the sidebar is inserted alphabetically into the Modules:
list. Existing sidebar entries (custom labels, nested sub-entries, hand-written
non-module links) are never modified — so a new module auto-appears in navigation
without disturbing the curated structure.
What it touches
Only the pages listed in mapping.json are (re)written. Every other wiki page
(Home, Installation, user showcases, the hand-written Module:-Cava:-GLSL,
Module:-Group, Module:-Load, …) is left untouched.
To edit a module's docs
Edit the man page under man/, not the wiki. The wiki page is overwritten on the
next sync. Put anything with no man equivalent (images, etc.) in extras/.
Run locally
python3 .github/wiki/generate.py --check # validate mapping only
python3 .github/wiki/generate.py --out-dir /tmp/wiki-out # generate a preview
One-time setup
The repository wiki must be enabled (Settings → Features → Wikis) with at least
one initial page so the .wiki.git remote exists.