Skip to content

feat(site): generate docs pages and cards from each mod's README - #33

Merged
munza merged 1 commit into
mainfrom
chore/generate-docs-from-readmes
Nov 19, 2026
Merged

munza merged 1 commit into
mainfrom
chore/generate-docs-from-readmes

Conversation

@munza

@munza munza commented Nov 19, 2026

Copy link
Copy Markdown
Owner

Important

Before merging, switch Settings → Pages → Build and deployment → Source to GitHub Actions. Until then the deleted docs pages 404 on the live site.

Summary

Docs pages and home-page cards are generated from each mod's README. A change edits the README once, not the README plus its HTML page plus every page's sidebar.

<mod>/README.md ─┐
mod.json         ├─ site/build.cjs ─▶ _site/docs/<mod>.html   (page, sidebar, pager)
mod.schema.json  │                    _site/index.html        (filters + cards)
site/mods.json ──┘                         │
                                           └─ .github/workflows/site.yml ─▶ GitHub Pages
 site/                     # plain Node, no packages
+├── mods.json             # the one list: sidebar, pager, cards, "Needs"
+├── build.cjs             # docs/ → _site/, fills in generated pages + cards
+├── page.cjs              # README → page, settings table vs mod.schema.json
+├── markdown.cjs          # only the Markdown the READMEs use; anything else fails with its line
+└── tests/site.test.cjs
 docs/
-├── docs/<9 mods>.html    # generated now; the build refuses a committed copy
 ├── docs/estro.html       # still hand-written (no README); sidebar rebuilt
 └── index.html            # cards replaced by a marker comment

Every mod README now follows one layout, written up in site/README.md:

# Name / summary (lead + card text) / picture
## Quick start  ## Install  ## Use  ## Settings  ## Update  ## For developers

The READMEs pick up what only the hand-written pages said: Quick start, Update, settings tables, props/command tables. Where a page and its README disagreed, the code decided (e.g. Better Changes' diff tab is per space; Branch Issue worktrees start from the remote's default branch, not main).

Evidence

Merge Danger

Door: two-way

Revert the commit and switch the Pages source back to main:/docs. The deleted HTML comes back with the revert.

Blast Radius: docs site

  • If this merges before the Pages source is switched, the 9 mod pages 404 and the home page shows no cards. The deploy job will fail until the switch; re-run it from the Actions tab afterwards.
  • The deploy workflow hasn't run on GitHub yet.
  • Card text is now each README's summary, a bit longer than the old blurbs. Better Changes and Better Files READMEs show their GIF instead of preview.png.
  • No mod code changes. Found while converting, not fixed here: Better Files' schema types editors as strings while the code reads objects; Branch Issue's schema says "Start work" where the button says "Create worktree".
  • Not addressed: RECIPE.md still restates behaviour and changed in all six replayed PRs; it's now the biggest repeat.

🤖 Generated with Claude Code

Each mod's docs page and home-page card is built from its README.md by a
plain-Node generator (site/), with the sidebar, pager and cards built from
one list (site/mods.json). The hand-written pages are deleted, and a
GitHub Actions workflow builds and deploys the site, so a PR edits the
README once instead of the README, its HTML page and every page's sidebar.

All nine READMEs are rearranged into one layout (Quick start, Install, Use,
Settings, Update, For developers), carrying over what only the hand-written
pages said. The build checks each settings table against mod.schema.json
and fails on broken links or Markdown it can't draw.

Needs the Pages source switched to "GitHub Actions" before merging.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@munza munza changed the title Generate the docs site from each mod's README feat(site): generate docs pages and cards from each mod's README Nov 19, 2026
@munza
munza merged commit 5d00276 into main Nov 19, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant