feat(docs): add offline documentation, config_help viewer, and CI pipelines

- docs/fish-config.md: curated terminal-optimized manual covering all
  public functions, keybindings, abbreviations, configuration variables,
  dependency catalog, and customization guide. Written for ov/bat/less
  readability rather than browser rendering — no callouts, no hyperlinks.
  Pandoc-compatible YAML front matter for man page compilation.

- functions/config_help.fish: viewer function with fallback chain
  ov -> bat -> man -l -> less -> cat. Accepts an optional section
  keyword to jump directly to the first matching heading.

- .gitea/workflows/man-page.yml: compiles docs/fish-config.md to
  docs/fish-config.1 via pandoc on every push to main that touches the
  source doc, then commits the result automatically.

- .gitea/workflows/docs-drift.yml: opens a reminder issue whenever
  README.md changes without a corresponding docs/fish-config.md update
  in the same push.

- README.md: documents config_help and the offline manual.
- AGENTS.md: adds Convention 10 requiring offline doc to be updated
  alongside any function, keybinding, or config change.
This commit is contained in:
2026-06-06 03:14:36 -04:00
parent b37f5c1d74
commit 02c27c6907
5 changed files with 1407 additions and 0 deletions
+45
View File
@@ -0,0 +1,45 @@
name: Offline docs drift reminder
on:
push:
branches:
- main
paths:
- 'README.md'
jobs:
remind:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
with:
fetch-depth: 2
- name: Check whether offline doc changed in same push
id: drift
run: |
if git diff --name-only HEAD~1 HEAD | grep -q '^docs/fish-config\.md$'; then
echo "synced=true" >> "$GITHUB_OUTPUT"
else
echo "synced=false" >> "$GITHUB_OUTPUT"
fi
- name: Open drift reminder issue
if: steps.drift.outputs.synced == 'false'
uses: actions/gitea-issue-create@v1
with:
token: ${{ secrets.GITEA_TOKEN }}
title: "docs: README updated — review docs/fish-config.md for drift"
body: |
README.md was modified in commit ${{ github.sha }} but
`docs/fish-config.md` (the offline manual) was not updated in
the same push.
Please review the README diff and update the offline documentation
if any functions, keybindings, abbreviations, or configuration
options were added, removed, or changed.
Commit: ${{ github.sha }}
Branch: ${{ github.ref_name }}
labels: documentation
+37
View File
@@ -0,0 +1,37 @@
name: Generate man page
on:
push:
branches:
- main
paths:
- 'docs/fish-config.md'
jobs:
build-manpage:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
with:
token: ${{ secrets.GITEA_TOKEN }}
- name: Install pandoc
run: sudo apt-get update -qq && sudo apt-get install -y pandoc
- name: Compile man page
run: |
pandoc --standalone \
--from markdown \
--to man \
docs/fish-config.md \
-o docs/fish-config.1
- name: Commit man page
run: |
git config user.name "Gitea Actions"
git config user.email "actions@gitea"
git add docs/fish-config.1
git diff --cached --quiet && echo "No changes to commit" && exit 0
git commit -m "chore(docs): regenerate fish-config.1 man page"
git push