feat(config-help): add section linking for HTML and man page
Generate documentation / build-docs (push) Successful in 30s
Offline docs drift reminder / remind (push) Successful in 10s

- Section keyword is now extracted early and shared across all three
  output modes (pager, HTML, man) rather than duplicated per branch
- --html with a section keyword resolves the heading to a pandoc anchor
  ID and looks it up in docs/html/sitemap.json; handles both sub-section
  fragment paths and top-level sections that are their own page
- --man with a section keyword overrides MANPAGER to `less +/pattern`
  so the page opens at the nearest heading match
- --help output updated to show [section] in USAGE and section+flag
  examples (help config keybindings --html, help config pkg --man)
- docs/fish-config.md §5.14 synopsis, flags, and examples updated
- docs/fish-config.md §11 "Viewing" sections updated for both HTML and
  man page to document the section+flag invocation
- README table updated with section+html and section+man rows
This commit is contained in:
2026-06-08 23:15:06 -04:00
parent f4157fb4ba
commit 831c7beb4d
3 changed files with 149 additions and 77 deletions
+18 -9
View File
@@ -1157,8 +1157,8 @@ Add -i (interactive confirmation) to destructive commands:
### config-help
Synopsis: config-help [SECTION]
config-help --html
config-help --man
config-help [SECTION] --html
config-help [SECTION] --man
config-help -h | --help
Opens the offline fish shell configuration manual. Without flags, opens
@@ -1168,16 +1168,20 @@ Add -i (interactive confirmation) to destructive commands:
Flags:
--html / -w Open docs/html/index.html in the default browser.
If SECTION is given, opens at the matching anchor.
Detects the browser via xdg-mime x-scheme-handler/https,
then known binaries, then xdg-open as last resort.
Respects $fish_help_browser and $BROWSER.
--man / -m Open docs/fish-config.1 via man -l directly.
If SECTION is given, jumps to the nearest match.
--help / -h Print usage and navigation key reference.
config-help keybindings
config-help pkg
config-help --html
config-help pkg --html
config-help --man
config-help pkg --man
Also available as: help config [SECTION] [FLAGS]
@@ -1603,10 +1607,12 @@ navigation.
## As a man page
help config --man
help config pkg --man
Opens the compiled docs/fish-config.1 directly via man -l, bypassing
the pager fallback chain. The symlink and MANPATH are also configured
automatically on shell start for the standard invocation:
the pager fallback chain. If a section keyword is given, the pager opens
at the nearest matching heading. The symlink and MANPATH are also
configured automatically on shell start for the standard invocation:
man fish-config
@@ -1617,12 +1623,15 @@ a completely separate command. Do not mix them up.
## In the browser (HTML)
help config --html
help config pkg --html
Opens docs/html/index.html in the default web browser. Browser detection
queries the system's x-scheme-handler/https MIME entry (via xdg-mime) to
find the real browser binary, then falls back through known browser
binaries (firefox, chromium, vivaldi, etc.), and finally xdg-open as a
last resort. Set $fish_help_browser or $BROWSER to override.
Opens docs/html/index.html in the default web browser. If a section
keyword is given, the browser opens directly at the matching anchor
(resolved via docs/html/sitemap.json). Browser detection queries the
system's x-scheme-handler/https MIME entry (via xdg-mime) to find the
real browser binary, then falls back through known browser binaries
(firefox, chromium, vivaldi, etc.), and finally xdg-open as a last
resort. Set $fish_help_browser or $BROWSER to override.
## As a wiki