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

2026-06-06T07:15:01Z

rootiest commented

2026-06-06 07:15:01 +00:00

Summary

docs/fish-config.md — curated terminal-optimized manual covering every public function, all keybindings, all abbreviations, configuration variables, the dependency catalog, and the customization guide. Written specifically for terminal readability: no GitHub callouts, no hyperlinks, clean plain-text prose with fenced code examples. Pandoc-compatible YAML front matter so the same file compiles directly to a groff man page.
docs/fish-config.index — keyword-to-heading map with 100+ aliases (keybindings, abbr, git, fzf, fish-deps, etc.). config_help does an index lookup first, then falls back to a normalized heading scan (strips non-alphanumeric chars, lowercases both sides) for unknown terms. Line numbers are resolved at runtime via grep -F so the index only needs updating when a heading is renamed, not when surrounding content changes.
functions/config_help.fish — viewer with a full fallback chain: ov (syntax highlight + section navigation) → bat (syntax highlight, paging) → man -l (pre-compiled man page) → less → cat. Accepts an optional keyword argument to jump directly to the first matching section heading (config_help keybindings, config_help pkg, etc.). A persistent navigation hint is pinned at the top of the ov screen via --header 1. Pass --help or -h for full usage and key reference.
.gitea/workflows/man-page.yml — automatically compiles docs/fish-config.md → docs/fish-config.1 via pandoc on every push to main that touches the source doc, commits the result back to the repo.
.gitea/workflows/docs-drift.yml — opens a reminder issue whenever README.md changes on main without a corresponding change to docs/fish-config.md in the same push.
README.md — adds an "Offline Documentation" subsection documenting config_help and its fallback chain.
AGENTS.md — adds Convention 10 requiring the offline doc to be updated alongside any function, keybinding, abbreviation, or config change. Also documents the CI workflows.

ov Navigation Keys

Key	Action
`Space`	next section
`^`	previous section
`Alt+u`	toggle section list sidebar
`/`	search forward
`n` / `N`	next / previous search match
`g`	go to line number
`q`	quit

Manual Verification

Run config_help — confirm it opens in ov with syntax highlighting, a dim nav hint pinned at the top, and the section sidebar populated (press Alt+u)
Run config_help keybindings — confirm ov opens at the Key Bindings section (# 3. KEY BINDINGS) rather than the top of the file
Run config_help pkg — confirm it jumps to the pkg function entry
Run config_help fish-deps — confirm it jumps to the fish-deps entry
Press Space and ^ to navigate forward and backward through sections; confirm the section header pins correctly below the nav hint
Run config_help --help — confirm the usage, examples, navigation key reference, and fallback chain all print correctly
Temporarily alias ov to a nonexistent command and run config_help — confirm fallback to bat with a paged Markdown view
Check that docs/fish-config.md renders cleanly: bat --language=markdown docs/fish-config.md | head -60
After merge to main, confirm the man-page.yml workflow runs and commits docs/fish-config.1, then verify man -l ~/.config/fish/docs/fish-config.1 displays the man page

## Summary - **`docs/fish-config.md`** — curated terminal-optimized manual covering every public function, all keybindings, all abbreviations, configuration variables, the dependency catalog, and the customization guide. Written specifically for terminal readability: no GitHub callouts, no hyperlinks, clean plain-text prose with fenced code examples. Pandoc-compatible YAML front matter so the same file compiles directly to a groff man page. - **`docs/fish-config.index`** — keyword-to-heading map with 100+ aliases (`keybindings`, `abbr`, `git`, `fzf`, `fish-deps`, etc.). `config_help` does an index lookup first, then falls back to a normalized heading scan (strips non-alphanumeric chars, lowercases both sides) for unknown terms. Line numbers are resolved at runtime via `grep -F` so the index only needs updating when a heading is renamed, not when surrounding content changes. - **`functions/config_help.fish`** — viewer with a full fallback chain: `ov` (syntax highlight + section navigation) → `bat` (syntax highlight, paging) → `man -l` (pre-compiled man page) → `less` → `cat`. Accepts an optional keyword argument to jump directly to the first matching section heading (`config_help keybindings`, `config_help pkg`, etc.). A persistent navigation hint is pinned at the top of the ov screen via `--header 1`. Pass `--help` or `-h` for full usage and key reference. - **`.gitea/workflows/man-page.yml`** — automatically compiles `docs/fish-config.md` → `docs/fish-config.1` via pandoc on every push to `main` that touches the source doc, commits the result back to the repo. - **`.gitea/workflows/docs-drift.yml`** — opens a reminder issue whenever `README.md` changes on `main` without a corresponding change to `docs/fish-config.md` in the same push. - **`README.md`** — adds an "Offline Documentation" subsection documenting `config_help` and its fallback chain. - **`AGENTS.md`** — adds Convention 10 requiring the offline doc to be updated alongside any function, keybinding, abbreviation, or config change. Also documents the CI workflows. ## ov Navigation Keys | Key | Action | |-----|--------| | `Space` | next section | | `^` | previous section | | `Alt+u` | toggle section list sidebar | | `/` | search forward | | `n` / `N` | next / previous search match | | `g` | go to line number | | `q` | quit | ## Manual Verification - [x] Run `config_help` — confirm it opens in ov with syntax highlighting, a dim nav hint pinned at the top, and the section sidebar populated (press `Alt+u`) - [x] Run `config_help keybindings` — confirm ov opens at the Key Bindings section (`# 3. KEY BINDINGS`) rather than the top of the file - [x] Run `config_help pkg` — confirm it jumps to the `pkg` function entry - [x] Run `config_help fish-deps` — confirm it jumps to the `fish-deps` entry - [x] Press `Space` and `^` to navigate forward and backward through sections; confirm the section header pins correctly below the nav hint - [x] Run `config_help --help` — confirm the usage, examples, navigation key reference, and fallback chain all print correctly - [x] Temporarily alias ov to a nonexistent command and run `config_help` — confirm fallback to bat with a paged Markdown view - [x] Check that `docs/fish-config.md` renders cleanly: `bat --language=markdown docs/fish-config.md | head -60` - [x] After merge to `main`, confirm the `man-page.yml` workflow runs and commits `docs/fish-config.1`, then verify `man -l ~/.config/fish/docs/fish-config.1` displays the man page

rootiest added 1 commit 2026-06-06 07:15:02 +00:00

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

- 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.

rootiest added 1 commit 2026-06-06 08:09:24 +00:00

fix(config_help): reliable section lookup and jump via index + tail-slice 368b714a98

- Add docs/fish-config.index mapping 100+ keyword aliases to exact heading
  text; config_help looks up here first, falls back to normalized heading
  scan (strips non-alphanumeric, lowercases both sides) for unknown terms.
- Resolve line numbers at runtime with grep -F so the index never goes
  stale from doc edits — only heading renames require an update.
- Fix section jump: --section-header pins delimiter lines as sticky headers
  removing them from ov pattern-search scope. Replace --pattern with
  tail -n +$start_line piped before ov; the target section is the first
  line so no search is needed and forward section nav still works.
- Fix empty sections sidebar: ov matches --section-delimiter against
  logical (ANSI-stripped) text, so "^#" is correct for bat-colored output;
  the previous ANSI escape-sequence regex never matched anything.

rootiest force-pushed feat/offline-documentation from d21d685090 to 368b714a98

2026-06-06 08:09:24 +00:00

Compare

rootiest added 1 commit 2026-06-06 08:16:17 +00:00

feat(config_help): add --help flag and persistent nav hint header cb4d74423a

- config_help --help / -h prints full usage, section keyword examples,
  ov navigation key reference, and the pager fallback chain.
- Prepend a dim nav hint line to the ov input stream and pin it with
  --header 1 so "Space=next section  ^=prev  Alt+u=sections  /=search
  q=quit" is always visible at the top of the screen.

rootiest added 1 commit 2026-06-06 08:24:06 +00:00

feat(config_help): colorize --help output ba92267a80

Section headers in bold blue, argument/flag names in yellow, command
examples in green, navigation keys in cyan, fallback chain numbers
dimmed. All reset to normal after each colored span.

rootiest force-pushed feat/offline-documentation from a4e0c04de4 to ba92267a80

2026-06-06 08:24:06 +00:00

Compare

rootiest merged commit 103f99b9f7 into main

2026-06-06 08:24:35 +00:00

rootiest deleted branch feat/offline-documentation

2026-06-06 08:24:35 +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#32