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:
@@ -0,0 +1,75 @@
|
||||
# Copyright (C) 2026 Rootiest
|
||||
# SPDX-License-Identifier: AGPL-3.0-or-later
|
||||
|
||||
# SYNOPSIS
|
||||
# config_help [section]
|
||||
#
|
||||
# DESCRIPTION
|
||||
# Opens the offline fish shell configuration manual in the best available
|
||||
# pager. Falls back through ov -> bat -> man -> less -> cat.
|
||||
# If a section keyword is provided, the pager opens at the first heading
|
||||
# that matches the keyword (case-insensitive).
|
||||
#
|
||||
# ARGUMENTS
|
||||
# section Optional keyword to jump to a matching section heading
|
||||
#
|
||||
# RETURNS
|
||||
# 0 Manual displayed
|
||||
# 1 Documentation file not found
|
||||
#
|
||||
# EXAMPLE
|
||||
# config_help
|
||||
# config_help keybindings
|
||||
# config_help pkg
|
||||
# config_help fish-deps
|
||||
function config_help --description 'Open the offline fish shell configuration manual'
|
||||
set -l doc_file "$__fish_config_dir/docs/fish-config.md"
|
||||
set -l man_file "$__fish_config_dir/docs/fish-config.1"
|
||||
|
||||
if not test -f "$doc_file"
|
||||
set_color red
|
||||
echo "error: documentation not found at $doc_file" >&2
|
||||
set_color normal
|
||||
return 1
|
||||
end
|
||||
|
||||
# ── Resolve section start line ───────────────────────────────
|
||||
set -l start_line 1
|
||||
if test -n "$argv[1]"
|
||||
set -l found (grep -n -im 1 "^#\+.*$argv[1]" "$doc_file" | cut -d: -f1)
|
||||
if test -n "$found"
|
||||
set start_line $found
|
||||
else
|
||||
set_color yellow
|
||||
echo "note: no section matching '$argv[1]' — opening at top" >&2
|
||||
set_color normal
|
||||
end
|
||||
end
|
||||
|
||||
# ── Viewer fallback chain ────────────────────────────────────
|
||||
if type -q ov
|
||||
ov --syntax --syntax-name markdown \
|
||||
--section-delimiter "^#" \
|
||||
--section-header \
|
||||
+"$start_line" "$doc_file"
|
||||
|
||||
else if type -q bat
|
||||
if test $start_line -gt 1
|
||||
# bat can't jump to a line in paging mode; show a hint instead
|
||||
set_color brblack
|
||||
echo "note: bat pager active — use / to search for your section" >&2
|
||||
set_color normal
|
||||
end
|
||||
bat --language=markdown --paging=always "$doc_file"
|
||||
|
||||
else if test -f "$man_file"
|
||||
# Pre-compiled man page as a pager-independent fallback
|
||||
man -l "$man_file"
|
||||
|
||||
else if type -q less
|
||||
less +"$start_line" "$doc_file"
|
||||
|
||||
else
|
||||
cat "$doc_file"
|
||||
end
|
||||
end
|
||||
Reference in New Issue
Block a user