feat(docs): GitHub mirror icon, README-sourced doc sections, auto-generated TOC #129

2026-09-04T20:34:56Z

rootiest commented

2026-09-04 20:34:56 +00:00

Summary

Added a GitHub social icon to the docs site header next to the existing Gitea one, linking to the github.com/rootiest/fish-config mirror.
README's Contributing section now states git.rootiest.dev is the base repo and GitHub is a one-way push-mirror, so forks/issues/PRs should go through Gitea (branches/merges made on GitHub risk being overwritten by the next mirror push).
Added Testing, Contributing, Attribution, and License sections to the manual, man page (config-help), and docs site — sourced directly from the corresponding ## sections in README.md via a new  placeholder mechanism in docs/build-manual.py, so README stays the single source of truth instead of a hand-copied duplicate that drifts.
Converted docs/manual/00-table-of-contents.md from a hand-typed list to a generated one (mt.walk()-driven), which also fixes a pre-existing numbering drift: Components Reference was omitted from the old TOC and every section after it was off by one relative to its own manTitle.

Non-goals

Two-way PR/issue sync between Gitea and GitHub — noted as a future item, not attempted here.
Folding Troubleshooting's in-page ## sub-headings (old TOC's 11.1–11.9) into the new generated TOC — those come from parsing a page's body, not its file/dir structure, and were deliberately left out of this generator's scope.
Removing section numbering (1., 2., …) — it's load-bearing for docs/fish-config.index lookups, _is_function_page's Section 5 special-case, and man-page convention; left as a separate, larger task if still wanted.

Verification

python3 docs/build-manual.py --concat -o docs/fish-config.md regenerated cleanly
python3 docs/verify-manual.py — 74/74 passed
fish tests/run-tests.fish — 317/317 passed
python3 docs/build-manual.py --site — spot-checked generated Testing/Contributing/Attribution/License pages, sidebar order, and link rewriting (CONTRIBUTING.md/LICENSE/.github/... now point at Gitea blob URLs)
docs/fish-config.1 (man page) is left stale — needs pandoc, not available locally; CI's build-docs job regenerates and auto-commits it after merge, per existing repo convention
Visually confirm the GitHub icon renders correctly in the deployed site header

## Summary - Added a GitHub social icon to the docs site header next to the existing Gitea one, linking to the `github.com/rootiest/fish-config` mirror. - README's Contributing section now states git.rootiest.dev is the base repo and GitHub is a one-way push-mirror, so forks/issues/PRs should go through Gitea (branches/merges made on GitHub risk being overwritten by the next mirror push). - Added Testing, Contributing, Attribution, and License sections to the manual, man page (`config-help`), and docs site — sourced directly from the corresponding `## ` sections in README.md via a new `` placeholder mechanism in `docs/build-manual.py`, so README stays the single source of truth instead of a hand-copied duplicate that drifts. - Converted `docs/manual/00-table-of-contents.md` from a hand-typed list to a generated one (`mt.walk()`-driven), which also fixes a pre-existing numbering drift: Components Reference was omitted from the old TOC and every section after it was off by one relative to its own `manTitle`. ## Non-goals - Two-way PR/issue sync between Gitea and GitHub — noted as a future item, not attempted here. - Folding Troubleshooting's in-page `##` sub-headings (old TOC's `11.1`–`11.9`) into the new generated TOC — those come from parsing a page's body, not its file/dir structure, and were deliberately left out of this generator's scope. - Removing section numbering (`1.`, `2.`, …) — it's load-bearing for `docs/fish-config.index` lookups, `_is_function_page`'s Section 5 special-case, and man-page convention; left as a separate, larger task if still wanted. ## Verification - [x] `python3 docs/build-manual.py --concat -o docs/fish-config.md` regenerated cleanly - [x] `python3 docs/verify-manual.py` — 74/74 passed - [x] `fish tests/run-tests.fish` — 317/317 passed - [x] `python3 docs/build-manual.py --site` — spot-checked generated Testing/Contributing/Attribution/License pages, sidebar order, and link rewriting (`CONTRIBUTING.md`/`LICENSE`/`.github/...` now point at Gitea blob URLs) - [x] `docs/fish-config.1` (man page) is left stale — needs `pandoc`, not available locally; CI's `build-docs` job regenerates and auto-commits it after merge, per existing repo convention - [x] Visually confirm the GitHub icon renders correctly in the deployed site header

rootiest added the Kind/Feature Area/Docs labels 2026-09-04 20:34:56 +00:00

rootiest added 1 commit 2026-09-04 20:34:57 +00:00

feat(docs): add GitHub mirror icon, README-sourced doc sections, auto-generated TOC 4912c4052f

Adds a GitHub social icon to the docs site header alongside the existing
Gitea one, and documents in the README's Contributing section that
git.rootiest.dev is the base repo while the GitHub copy is a one-way
mirror, so forks/issues/PRs should go through Gitea.

Adds Testing, Contributing, Attribution, and License sections to the
manual/man page/site, sourced directly from README.md via a new
`<!-- README: Heading -->` placeholder mechanism in build-manual.py, so
the README stays the single source of truth for those sections instead
of a hand-maintained copy drifting out of sync.

Also converts docs/manual/00-table-of-contents.md from a hand-typed list
to a generated one (mt.walk()-driven), fixing a numbering drift where
Components Reference was omitted and every section after it was off by
one relative to its own manTitle.

rootiest added 2 commits 2026-09-04 20:43:32 +00:00

style(docs): double the Gitea/GitHub header icon size 8c21d34943

--sl-nav-height is a fixed CSS var, not driven by icon content, so both
icons can grow without changing the header bar's height.

chore(docs): regenerate man page 23cae4bd10

pandoc wasn't available when this branch's earlier commit ran
build-manual.py --concat; regenerate docs/fish-config.1 from the
current docs/fish-config.md now that it is.

rootiest added 1 commit 2026-09-04 20:49:07 +00:00

fix(docs): make the Gitea icon override actually apply, tune GitHub to 1.5x 2ee2806e01

UnoCSS's .i-pajamas:gitea rule is unlayered CSS; our override lived in
@layer starlight.core, and unlayered rules always beat layered ones
regardless of specificity or source order. The Gitea icon has silently
stayed at UnoCSS's 1em default since it was first added -- confirmed via
computed style in the browser, not just reading the stylesheet source.
!important restores the override across the layer boundary.

Also drops the GitHub icon from 2x to 1.5x per visual feedback.

rootiest added 1 commit 2026-09-04 20:50:20 +00:00

style(docs): match Gitea icon size to GitHub's 24px (1.5rem) 54375a9530

rootiest added 1 commit 2026-09-04 21:14:30 +00:00

style(docs): add fish to logo icon e6d3fd80b3

rootiest merged commit c009bbf257 into main

2026-09-04 21:23:07 +00:00

rootiest deleted branch feat/docs-readme-sections

2026-09-04 21:23:07 +00:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: rootiest/fish-config#129