Merge pull request 'docs: use aside syntax for caution block and update intro text' (#81) from docs-index-tweaks into main

Reviewed-on: #81

docs/build-manual.py

@@ -78,6 +78,7 @@ def build_concat(root: Path) -> str:
         if _is_function_page(path, root):
             body = _with_entries(body, path, entries)
         if body:
+            body = re.sub(r"<LinkButton.*?</LinkButton>\n*", "", body, flags=re.DOTALL)
             chunks.append(mt.shift_headings(body, depth))
     return "\n\n".join(chunks) + "\n"
 
@@ -597,7 +598,7 @@ def _split_entries(body: str) -> tuple[str, list[tuple[str, str]]]:
     return intro, entries
 
 
-ASTRO_ASIDE_COMPONENTS = {"<Aside": "Aside", "<FileTree": "FileTree"}
+ASTRO_ASIDE_COMPONENTS = {"<Aside": "Aside", "<FileTree": "FileTree", "<LinkButton": "LinkButton"}
 
 
 def _write_prettified(target: Path, fm: dict, content: str) -> None:

docs/fish-config.md

@@ -39,19 +39,17 @@ A production-grade Fish shell configuration targeting Fish 4.x. It provides:
 - AI session helpers for Claude Code and Antigravity
 - Catppuccin Mocha color theme throughout
 
-> **CAUTION - SESSION LOGGING IS ON BY DEFAULT**
+CAUTION: **SESSION LOGGING IS ON BY DEFAULT**
->
+This configuration silently records terminal output to `~/.terminal_history`:
-> This configuration silently records terminal output to `~/.terminal_history`:
+Kitty scrollback on window close, live tmux pane streams, zellij pane
-> Kitty scrollback on window close, live tmux pane streams, zellij pane
+snapshots on exit, and full paru/yay output. These logs can contain command
-> snapshots on exit, and full paru/yay output. These logs can contain command
+output, file contents, and secrets printed to the terminal. Nothing leaves
-> output, file contents, and secrets printed to the terminal. Nothing leaves
+your machine, but the files persist locally.
-> your machine, but the files persist locally.
+- Disable all logging with: `set -U __fish_config_op_logging off`
->
+- Prefer a menu? Run the interactive picker: `config-settings`
-> - Disable all logging with: `set -U __fish_config_op_logging off`
+- See Section 7 (C5 - Logging and Capture) for the full breakdown.
-> - Prefer a menu? Run the interactive picker: `config-settings`
-> - See Section 7 (C5 - Logging and Capture) for the full breakdown.
 
-The configuration is split across:
+The configuration uses a structured file tree:
 
     ~/.config/fish/
     ├── config.fish                 Main entry point; sets env vars and PATH

docs/manual/index.md

@@ -24,19 +24,20 @@ A production-grade Fish shell configuration targeting Fish 4.x. It provides:
 - AI session helpers for Claude Code and Antigravity
 - Catppuccin Mocha color theme throughout
 
-> **CAUTION - SESSION LOGGING IS ON BY DEFAULT**
+<LinkButton href="/09-installation/">Install now</LinkButton>
->
+<LinkButton href="/reference/" variant="secondary">Function reference</LinkButton>
-> This configuration silently records terminal output to `~/.terminal_history`:
-> Kitty scrollback on window close, live tmux pane streams, zellij pane
-> snapshots on exit, and full paru/yay output. These logs can contain command
-> output, file contents, and secrets printed to the terminal. Nothing leaves
-> your machine, but the files persist locally.
->
-> - Disable all logging with: `set -U __fish_config_op_logging off`
-> - Prefer a menu? Run the interactive picker: `config-settings`
-> - See Section 7 (C5 - Logging and Capture) for the full breakdown.
 
-The configuration is split across:
+CAUTION: **SESSION LOGGING IS ON BY DEFAULT**
+This configuration silently records terminal output to `~/.terminal_history`:
+Kitty scrollback on window close, live tmux pane streams, zellij pane
+snapshots on exit, and full paru/yay output. These logs can contain command
+output, file contents, and secrets printed to the terminal. Nothing leaves
+your machine, but the files persist locally.
+- Disable all logging with: `set -U __fish_config_op_logging off`
+- Prefer a menu? Run the interactive picker: `config-settings`
+- See Section 7 (C5 - Logging and Capture) for the full breakdown.
+
+The configuration uses a structured file tree:
 
     ~/.config/fish/
     ├── config.fish                 Main entry point; sets env vars and PATH