2026-07-26 08:41:03 +00:00
3 changed files with 34 additions and 7 deletions
@@ -122,14 +122,19 @@ the watcher inert without uninstalling it.

 ### [📖 Documentation Site](https://fish-config-docs.pages.dev/)

-A Starlight-powered site generated from `docs/manual/**` — the single source
-of truth — on every push to `main`. It covers configuration variables, key
-bindings, abbreviations, all functions, the dependency catalog, customization,
-and more, with full-text search.
+A Starlight-powered site rebuilt on every push to `main`. It covers
+configuration variables, key bindings, abbreviations, all functions, the
+dependency catalog, customization, and more, with full-text search.

-Contributing to the docs? Edit files under `docs/manual/**`, never the
-generated `docs/fish-config.md` — it's rebuilt from the manual tree and any
-hand-edits are discarded.
+Contributing to the docs? There are two sources, split by content type:
+
+- **Function documentation** comes from the man-page-style comment header
+  above each function in `functions/*.fish`. Edit the function; the entry
+  and its site page are generated from the header.
+- **Everything else** lives under `docs/manual/**`.
+
+Never edit the generated `docs/fish-config.md` — it's rebuilt from both
+sources and any hand-edits are discarded.

 To browse the docs from the terminal:

@@ -3054,3 +3054,14 @@ editor, or from a shell:

    cd ~/.config/fish/docs/manual
    grep -rn "keybindings" .
+
+Section 5 is the exception. Function entries are generated from the
+man-page-style comment header above each function in `functions/*.fish`,
+so the documentation for a command lives beside the code that implements
+it and cannot drift from it. To read the source for a single function, or
+to correct its documentation, open the function itself:
+
+    functions/git-clean.fish
+
+The files under `docs/manual/05-functions/` carry only the category
+titles, ordering, and search keywords.
@@ -83,3 +83,14 @@ editor, or from a shell:

    cd ~/.config/fish/docs/manual
    grep -rn "keybindings" .
+
+Section 5 is the exception. Function entries are generated from the
+man-page-style comment header above each function in `functions/*.fish`,
+so the documentation for a command lives beside the code that implements
+it and cannot drift from it. To read the source for a single function, or
+to correct its documentation, open the function itself:
+
+    functions/git-clean.fish
+
+The files under `docs/manual/05-functions/` carry only the category
+titles, ordering, and search keywords.