CONTRIBUTING.md

@@ -243,8 +243,21 @@ Write doc-headers as plain text — no backticks. `-a/--all`,
 `__fish_config_op_aliases` and `~/.config/fish/config.fish` are typed
 bare, because the header is also read as-is by `config-help` and by
 anyone opening the file. `docs/codespans.py` adds the inline code spans
-the docs site wants when it renders, so the SSOT never carries them; see
+when it renders, so the SSOT never carries them; see
-`docs/site/README.md` for which shapes it recognises.
+`docs/site/README.md` for which shapes it recognises. That pass runs for
+every output — the site, the man page and `config-help` — so a token is
+typeset the same way wherever it is read.
+
+Two rules apply to backticks you write under `docs/manual/` as well:
+
+- **Never inside an indented block.** A four-space block is verbatim in
+  every renderer, so a backtick there is a literal character on the page
+  rather than markup.
+- **Never wrapped across a line break.** Markdown accepts a span split
+  over two lines, but `config-help` pairs backticks one line at a time
+  and would show the halves literally. Reflow the sentence instead.
+
+`docs/verify-manual.py` enforces both.
 
 ## Testing
 

docs/site/README.md

@@ -25,8 +25,13 @@ first if you've touched a header or a manual page.
 Function headers are read as plain text (by `config-help`, by `funcsave`,
 by anyone opening the `.fish` file), so they're authored without backticks
 — `-a/--all`, not `` `-a`/`--all` ``. `docs/codespans.py` puts the
-backticks on at render time, as the last step of `prettify()`, so only the
+backticks on at render time, as the last step of `prettify()`.
-site sees them.
+
+`build_concat()` runs the same pass, so the man page and `config-help`
+mark code the way the site does rather than only where the SSOT happened
+to backtick something by hand. `config-help` then renders those spans
+bold and drops the delimiters, since a terminal pager would otherwise
+show them as literal punctuation.
 
 It recognises flags, `$vars`, `SCREAMING_SNAKE` env vars, snake_case
 identifiers (`__fish_config_op_aliases`, `fish_greeting`), paths and
@@ -41,10 +46,14 @@ Names that also read as English (`find`, `top`, `screen`) are listed in
 where position already proves they're a command. Add to that list rather
 than removing a rule if a wrap ever reads wrong.
 
-Fenced blocks, existing code spans, headings, link targets, URLs,
+Fenced blocks, indented blocks, existing code spans, headings, link
-component markup, and `<FileTree>` bodies are never touched. Leaving a
+targets, URLs, component markup, and `<FileTree>` bodies are never
-token alone is always the safe outcome, so every rule bails out when it
+touched. Leaving a token alone is always the safe outcome, so every rule
-isn't sure.
+bails out when it isn't sure.
+
+Indented blocks matter only to the concat — `prettify()` has already
+fenced them by the time the site is rendered — but there they are the
+table of contents and every section 5 entry, which must stay verbatim.
 
 ## llms.txt
 

functions/config-help.fish

@@ -247,6 +247,22 @@ function config-help --description 'Open the offline fish shell configuration ma
     set -l nav_hint \
         " \033[2mNAVIGATION: [ Space=next section  ^=prev  Alt+u=sections  /=search  q=quit ]\033[0m"
 
+    # ── Inline code spans ────────────────────────────────────────
+    # The document carries backticks for pandoc and the docs site, but
+    # nothing in this chain consumes them: bat dims the delimiters and
+    # leaves the content the same colour as the surrounding prose, so
+    # they arrive as literal punctuation. Render each span bold instead.
+    #
+    # Two forms are matched. After bat, every backtick carries its own
+    # SGR sequence, and a fence survives because it puts three of them
+    # inside one sequence. On raw Markdown a fence survives because it
+    # offers no non-backtick content to capture. Both substitutions are
+    # line-preserving, so the tail-slice below still lands on the
+    # requested section.
+    set -l span_ansi '\e\[[0-9;]*m`\e\[0m(.*?)\e\[[0-9;]*m`\e\[0m'
+    set -l span_raw '`([^`]+)`'
+    set -l span_bold (printf '\e[1m$1\e[0m')
+
     # ── Viewer fallback chain ────────────────────────────────────
     # When jumping to a section, slice the file from start_line so ov
     # opens with that section at the top without needing --pattern.
@@ -261,12 +277,14 @@ function config-help --description 'Open the offline fish shell configuration ma
             begin
                 printf "$nav_hint\n"
                 bat --color=always --style=plain --language=markdown "$doc_file" \
-                    | tail -n +$start_line
+                    | tail -n +$start_line \
+                    | string replace -ra $span_ansi $span_bold
             end | ov $ov_args
         else
             begin
                 printf "$nav_hint\n"
-                bat --color=always --style=plain --language=markdown "$doc_file"
+                bat --color=always --style=plain --language=markdown "$doc_file" \
+                    | string replace -ra $span_ansi $span_bold
             end | ov $ov_args
         end
 
@@ -279,12 +297,13 @@ function config-help --description 'Open the offline fish shell configuration ma
         if test $start_line -gt 1
             begin
                 printf "$nav_hint\n"
-                tail -n +$start_line "$doc_file"
+                tail -n +$start_line "$doc_file" \
+                    | string replace -ra $span_raw $span_bold
             end | ov $ov_args
         else
             begin
                 printf "$nav_hint\n"
-                cat "$doc_file"
+                string replace -ra $span_raw $span_bold <"$doc_file"
             end | ov $ov_args
         end
 
@@ -295,16 +314,23 @@ function config-help --description 'Open the offline fish shell configuration ma
             echo "note: bat pager — use / to search for your section" >&2
             set_color normal
         end
-        bat --language=markdown --paging=always "$doc_file"
+        # bat owns the pager here, so the spans are flattened on the way
+        # in rather than styled on the way out — bat would escape any
+        # SGR sequence handed to it as input.
+        string replace -ra $span_raw '$1' <"$doc_file" \
+            | bat --language=markdown --paging=always
 
         # Pre-compiled man page (generated by CI after merge).
+        # pandoc consumed the backticks when it built this, so there is
+        # nothing to strip.
     else if test -f "$man_file"
         man -l "$man_file"
 
     else if type -q less
-        less +"$start_line" "$doc_file"
+        string replace -ra $span_raw $span_bold <"$doc_file" \
+            | less -R +"$start_line"
 
     else
-        cat "$doc_file"
+        string replace -ra $span_raw $span_bold <"$doc_file"
     end
 end