From 345d0086a53e431334cfacedb6dd7fa3f1b9a95d Mon Sep 17 00:00:00 2001 From: rootiest Date: Mon, 8 Jun 2026 16:46:48 -0400 Subject: [PATCH] docs: add Installation and Personalization sections; fix wiki index MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - docs/fish-config.md: add §10 Installation (clone, sentinel guard, config-update usage) and §11 Personalization (secrets.fish / local.fish examples); update TABLE OF CONTENTS - docs/split-wiki.py: strip trailing thematic break from DESCRIPTION body so index.md no longer renders a double --- separator - Regenerate docs/wiki/ with 11-installation.md and 12-personalization.md; all nav bars updated --- docs/fish-config.md | 88 ++++++++++++++++++++++++++ docs/split-wiki.py | 4 +- docs/wiki/1-configuration-variables.md | 2 +- docs/wiki/10-installation.md | 38 +++++++++++ docs/wiki/11-personalization.md | 52 +++++++++++++++ docs/wiki/2-path-setup.md | 2 +- docs/wiki/3-key-bindings.md | 2 +- docs/wiki/4-abbreviations.md | 2 +- docs/wiki/5-functions-reference.md | 2 +- docs/wiki/6-dependency-catalog.md | 2 +- docs/wiki/7-customization.md | 2 +- docs/wiki/8-fisher-plugins.md | 2 +- docs/wiki/9-viewing-this-manual.md | 4 +- docs/wiki/index.md | 4 +- 14 files changed, 194 insertions(+), 12 deletions(-) create mode 100644 docs/wiki/10-installation.md create mode 100644 docs/wiki/11-personalization.md diff --git a/docs/fish-config.md b/docs/fish-config.md index e692022..eef9414 100644 --- a/docs/fish-config.md +++ b/docs/fish-config.md @@ -104,6 +104,8 @@ The configuration is split across: 7. Customization 8. Fisher Plugins 9. Viewing This Manual + 10. Installation + 11. Personalization --- @@ -1494,3 +1496,89 @@ push to main that changes docs/fish-config.md. help config fish-deps The keyword is matched case-insensitively against section headings. + +--- + +# 10. INSTALLATION + +This configuration is managed as a git repository. To deploy on a new machine: + + mv ~/.config/fish ~/.config/fish.bak # back up any existing config + git clone https://git.rootiest.dev/rootiest/fish-config.git ~/.config/fish + +Then open a new Fish shell. Fisher and all plugins install automatically on +first launch and the Catppuccin Mocha theme is applied. + +## Return Sentinel + +config.fish ends with a return sentinel guard. Any lines appended after it by +a tool's setup command (starship init fish | source, zoxide init fish | source, +etc.) will have no effect. All integrations are managed via conf.d/ files. + +If a new tool's shell integration appears to do nothing, check whether its +setup command appended an init line below the sentinel and create a dedicated +conf.d/.fish instead. + +## Updating + +Pull the latest changes from the upstream repository without needing a +configured git remote: + + config-update Fetch and apply the latest commits from upstream + config-update --dry-run Preview available changes without applying them + config-update --force Stash local changes, pull, then restore the stash + +The remote URL (https://git.rootiest.dev/rootiest/fish-config.git) is +hard-coded, so this works on a fresh clone with no origin configured. All +git output is suppressed. Run exec fish after a successful update to reload. + +--- + +# 11. PERSONALIZATION + +Sensitive credentials and machine-specific settings are kept out of version +control in a private directory at ~/.config/.user-dots/fish/. Two files are +sourced automatically by config.fish if they exist: + + ~/.config/.user-dots/fish/ + ├── secrets.fish API keys, tokens, passwords, personal identifiers + └── local.fish Machine-specific paths and environment variables + +fish_variables (auto-managed by fish) is excluded from this repo via +.gitignore. Do not commit it. + +## secrets.fish + +Store anything you would not commit to a public repo: API keys, auth tokens, +passwords, and personal identifiers. + + set -gx MY_NAME "Your Name" + set -gx MY_EMAIL "you@example.com" + set -gx GPG_RECIPIENT "you@example.com" + set -gx GITHUB_TOKEN ghp_yourTokenHere + set -gx OPENAI_API_KEY sk-proj-yourKeyHere + set -gx GITEA_TOKEN yourGiteaTokenHere + set -gx GITEA_CHOSEN_LOGIN your.gitea.instance + set -gx KOPIA_PASSWORD yourKopiaPassword + +## local.fish + +Store paths and variables specific to one machine — things that would be +wrong on any other system. + + # CDPATH — directories searched by cd + set -gx CDPATH . /home/youruser/projects /home/youruser + + # Path to your shared .gitignore boilerplate + set -gx GITIGNORE_BOILERPLATE ~/.config/git/gitignore_boilerplate + + # SSH shortcuts + abbr -a sshr 'ssh you@your-server.local' + abbr -a sshw 'ssh you@work-server.example.com' + + # Docker context shortcuts + abbr -a dcr 'docker context use my-remote-server' + abbr -a dcw 'docker context use work-server' + +Both files are sourced at the end of config.fish with an existence check so +the public config works cleanly on any machine without the private repo. diff --git a/docs/split-wiki.py b/docs/split-wiki.py index dd727c6..933466f 100644 --- a/docs/split-wiki.py +++ b/docs/split-wiki.py @@ -92,7 +92,9 @@ def main() -> None: numbered_sections.append(s) # ── Write index.md ────────────────────────────────────────────────────── - intro_body = "\n\n".join(intro_parts) + intro_body = "\n\n".join(intro_parts).rstrip() + # Strip any trailing thematic break that the source adds before the ToC. + intro_body = re.sub(r"\n+---\s*$", "", intro_body) toc = build_full_toc(numbered_sections) index_content = f"# Fish Shell Configuration\n\n{intro_body}\n\n---\n\n{toc}\n" (out_dir / "index.md").write_text(index_content) diff --git a/docs/wiki/1-configuration-variables.md b/docs/wiki/1-configuration-variables.md index b69acdf..ecd2057 100644 --- a/docs/wiki/1-configuration-variables.md +++ b/docs/wiki/1-configuration-variables.md @@ -1,6 +1,6 @@ # 1. CONFIGURATION VARIABLES -**Sections:** [Index](index.md) | **1. Configuration Variables** | [2. Path Setup](2-path-setup.md) | [3. Key Bindings](3-key-bindings.md) | [4. Abbreviations](4-abbreviations.md) | [5. Functions Reference](5-functions-reference.md) | [6. Dependency Catalog](6-dependency-catalog.md) | [7. Customization](7-customization.md) | [8. Fisher Plugins](8-fisher-plugins.md) | [9. Viewing This Manual](9-viewing-this-manual.md) +**Sections:** [Index](index.md) | **1. Configuration Variables** | [2. Path Setup](2-path-setup.md) | [3. Key Bindings](3-key-bindings.md) | [4. Abbreviations](4-abbreviations.md) | [5. Functions Reference](5-functions-reference.md) | [6. Dependency Catalog](6-dependency-catalog.md) | [7. Customization](7-customization.md) | [8. Fisher Plugins](8-fisher-plugins.md) | [9. Viewing This Manual](9-viewing-this-manual.md) | [10. Installation](10-installation.md) | [11. Personalization](11-personalization.md) --- diff --git a/docs/wiki/10-installation.md b/docs/wiki/10-installation.md new file mode 100644 index 0000000..c24dd6d --- /dev/null +++ b/docs/wiki/10-installation.md @@ -0,0 +1,38 @@ +# 10. INSTALLATION + +**Sections:** [Index](index.md) | [1. Configuration Variables](1-configuration-variables.md) | [2. Path Setup](2-path-setup.md) | [3. Key Bindings](3-key-bindings.md) | [4. Abbreviations](4-abbreviations.md) | [5. Functions Reference](5-functions-reference.md) | [6. Dependency Catalog](6-dependency-catalog.md) | [7. Customization](7-customization.md) | [8. Fisher Plugins](8-fisher-plugins.md) | [9. Viewing This Manual](9-viewing-this-manual.md) | **10. Installation** | [11. Personalization](11-personalization.md) + +--- + +This configuration is managed as a git repository. To deploy on a new machine: + + mv ~/.config/fish ~/.config/fish.bak # back up any existing config + git clone https://git.rootiest.dev/rootiest/fish-config.git ~/.config/fish + +Then open a new Fish shell. Fisher and all plugins install automatically on +first launch and the Catppuccin Mocha theme is applied. + +## Return Sentinel + +config.fish ends with a return sentinel guard. Any lines appended after it by +a tool's setup command (starship init fish | source, zoxide init fish | source, +etc.) will have no effect. All integrations are managed via conf.d/ files. + +If a new tool's shell integration appears to do nothing, check whether its +setup command appended an init line below the sentinel and create a dedicated +conf.d/.fish instead. + +## Updating + +Pull the latest changes from the upstream repository without needing a +configured git remote: + + config-update Fetch and apply the latest commits from upstream + config-update --dry-run Preview available changes without applying them + config-update --force Stash local changes, pull, then restore the stash + +The remote URL (https://git.rootiest.dev/rootiest/fish-config.git) is +hard-coded, so this works on a fresh clone with no origin configured. All +git output is suppressed. Run exec fish after a successful update to reload. + +--- diff --git a/docs/wiki/11-personalization.md b/docs/wiki/11-personalization.md new file mode 100644 index 0000000..e25a9df --- /dev/null +++ b/docs/wiki/11-personalization.md @@ -0,0 +1,52 @@ +# 11. PERSONALIZATION + +**Sections:** [Index](index.md) | [1. Configuration Variables](1-configuration-variables.md) | [2. Path Setup](2-path-setup.md) | [3. Key Bindings](3-key-bindings.md) | [4. Abbreviations](4-abbreviations.md) | [5. Functions Reference](5-functions-reference.md) | [6. Dependency Catalog](6-dependency-catalog.md) | [7. Customization](7-customization.md) | [8. Fisher Plugins](8-fisher-plugins.md) | [9. Viewing This Manual](9-viewing-this-manual.md) | [10. Installation](10-installation.md) | **11. Personalization** + +--- + +Sensitive credentials and machine-specific settings are kept out of version +control in a private directory at ~/.config/.user-dots/fish/. Two files are +sourced automatically by config.fish if they exist: + + ~/.config/.user-dots/fish/ + ├── secrets.fish API keys, tokens, passwords, personal identifiers + └── local.fish Machine-specific paths and environment variables + +fish_variables (auto-managed by fish) is excluded from this repo via +.gitignore. Do not commit it. + +## secrets.fish + +Store anything you would not commit to a public repo: API keys, auth tokens, +passwords, and personal identifiers. + + set -gx MY_NAME "Your Name" + set -gx MY_EMAIL "you@example.com" + set -gx GPG_RECIPIENT "you@example.com" + set -gx GITHUB_TOKEN ghp_yourTokenHere + set -gx OPENAI_API_KEY sk-proj-yourKeyHere + set -gx GITEA_TOKEN yourGiteaTokenHere + set -gx GITEA_CHOSEN_LOGIN your.gitea.instance + set -gx KOPIA_PASSWORD yourKopiaPassword + +## local.fish + +Store paths and variables specific to one machine — things that would be +wrong on any other system. + + # CDPATH — directories searched by cd + set -gx CDPATH . /home/youruser/projects /home/youruser + + # Path to your shared .gitignore boilerplate + set -gx GITIGNORE_BOILERPLATE ~/.config/git/gitignore_boilerplate + + # SSH shortcuts + abbr -a sshr 'ssh you@your-server.local' + abbr -a sshw 'ssh you@work-server.example.com' + + # Docker context shortcuts + abbr -a dcr 'docker context use my-remote-server' + abbr -a dcw 'docker context use work-server' + +Both files are sourced at the end of config.fish with an existence check so +the public config works cleanly on any machine without the private repo. diff --git a/docs/wiki/2-path-setup.md b/docs/wiki/2-path-setup.md index 69ef752..1180b0f 100644 --- a/docs/wiki/2-path-setup.md +++ b/docs/wiki/2-path-setup.md @@ -1,6 +1,6 @@ # 2. PATH SETUP -**Sections:** [Index](index.md) | [1. Configuration Variables](1-configuration-variables.md) | **2. Path Setup** | [3. Key Bindings](3-key-bindings.md) | [4. Abbreviations](4-abbreviations.md) | [5. Functions Reference](5-functions-reference.md) | [6. Dependency Catalog](6-dependency-catalog.md) | [7. Customization](7-customization.md) | [8. Fisher Plugins](8-fisher-plugins.md) | [9. Viewing This Manual](9-viewing-this-manual.md) +**Sections:** [Index](index.md) | [1. Configuration Variables](1-configuration-variables.md) | **2. Path Setup** | [3. Key Bindings](3-key-bindings.md) | [4. Abbreviations](4-abbreviations.md) | [5. Functions Reference](5-functions-reference.md) | [6. Dependency Catalog](6-dependency-catalog.md) | [7. Customization](7-customization.md) | [8. Fisher Plugins](8-fisher-plugins.md) | [9. Viewing This Manual](9-viewing-this-manual.md) | [10. Installation](10-installation.md) | [11. Personalization](11-personalization.md) --- diff --git a/docs/wiki/3-key-bindings.md b/docs/wiki/3-key-bindings.md index d0dd132..dbb7a06 100644 --- a/docs/wiki/3-key-bindings.md +++ b/docs/wiki/3-key-bindings.md @@ -1,6 +1,6 @@ # 3. KEY BINDINGS -**Sections:** [Index](index.md) | [1. Configuration Variables](1-configuration-variables.md) | [2. Path Setup](2-path-setup.md) | **3. Key Bindings** | [4. Abbreviations](4-abbreviations.md) | [5. Functions Reference](5-functions-reference.md) | [6. Dependency Catalog](6-dependency-catalog.md) | [7. Customization](7-customization.md) | [8. Fisher Plugins](8-fisher-plugins.md) | [9. Viewing This Manual](9-viewing-this-manual.md) +**Sections:** [Index](index.md) | [1. Configuration Variables](1-configuration-variables.md) | [2. Path Setup](2-path-setup.md) | **3. Key Bindings** | [4. Abbreviations](4-abbreviations.md) | [5. Functions Reference](5-functions-reference.md) | [6. Dependency Catalog](6-dependency-catalog.md) | [7. Customization](7-customization.md) | [8. Fisher Plugins](8-fisher-plugins.md) | [9. Viewing This Manual](9-viewing-this-manual.md) | [10. Installation](10-installation.md) | [11. Personalization](11-personalization.md) --- diff --git a/docs/wiki/4-abbreviations.md b/docs/wiki/4-abbreviations.md index f55e529..00c95dc 100644 --- a/docs/wiki/4-abbreviations.md +++ b/docs/wiki/4-abbreviations.md @@ -1,6 +1,6 @@ # 4. ABBREVIATIONS -**Sections:** [Index](index.md) | [1. Configuration Variables](1-configuration-variables.md) | [2. Path Setup](2-path-setup.md) | [3. Key Bindings](3-key-bindings.md) | **4. Abbreviations** | [5. Functions Reference](5-functions-reference.md) | [6. Dependency Catalog](6-dependency-catalog.md) | [7. Customization](7-customization.md) | [8. Fisher Plugins](8-fisher-plugins.md) | [9. Viewing This Manual](9-viewing-this-manual.md) +**Sections:** [Index](index.md) | [1. Configuration Variables](1-configuration-variables.md) | [2. Path Setup](2-path-setup.md) | [3. Key Bindings](3-key-bindings.md) | **4. Abbreviations** | [5. Functions Reference](5-functions-reference.md) | [6. Dependency Catalog](6-dependency-catalog.md) | [7. Customization](7-customization.md) | [8. Fisher Plugins](8-fisher-plugins.md) | [9. Viewing This Manual](9-viewing-this-manual.md) | [10. Installation](10-installation.md) | [11. Personalization](11-personalization.md) --- diff --git a/docs/wiki/5-functions-reference.md b/docs/wiki/5-functions-reference.md index 62f6bf8..e1959f2 100644 --- a/docs/wiki/5-functions-reference.md +++ b/docs/wiki/5-functions-reference.md @@ -1,6 +1,6 @@ # 5. FUNCTIONS REFERENCE -**Sections:** [Index](index.md) | [1. Configuration Variables](1-configuration-variables.md) | [2. Path Setup](2-path-setup.md) | [3. Key Bindings](3-key-bindings.md) | [4. Abbreviations](4-abbreviations.md) | **5. Functions Reference** | [6. Dependency Catalog](6-dependency-catalog.md) | [7. Customization](7-customization.md) | [8. Fisher Plugins](8-fisher-plugins.md) | [9. Viewing This Manual](9-viewing-this-manual.md) +**Sections:** [Index](index.md) | [1. Configuration Variables](1-configuration-variables.md) | [2. Path Setup](2-path-setup.md) | [3. Key Bindings](3-key-bindings.md) | [4. Abbreviations](4-abbreviations.md) | **5. Functions Reference** | [6. Dependency Catalog](6-dependency-catalog.md) | [7. Customization](7-customization.md) | [8. Fisher Plugins](8-fisher-plugins.md) | [9. Viewing This Manual](9-viewing-this-manual.md) | [10. Installation](10-installation.md) | [11. Personalization](11-personalization.md) --- diff --git a/docs/wiki/6-dependency-catalog.md b/docs/wiki/6-dependency-catalog.md index 6bf5a2b..d83e2ff 100644 --- a/docs/wiki/6-dependency-catalog.md +++ b/docs/wiki/6-dependency-catalog.md @@ -1,6 +1,6 @@ # 6. DEPENDENCY CATALOG -**Sections:** [Index](index.md) | [1. Configuration Variables](1-configuration-variables.md) | [2. Path Setup](2-path-setup.md) | [3. Key Bindings](3-key-bindings.md) | [4. Abbreviations](4-abbreviations.md) | [5. Functions Reference](5-functions-reference.md) | **6. Dependency Catalog** | [7. Customization](7-customization.md) | [8. Fisher Plugins](8-fisher-plugins.md) | [9. Viewing This Manual](9-viewing-this-manual.md) +**Sections:** [Index](index.md) | [1. Configuration Variables](1-configuration-variables.md) | [2. Path Setup](2-path-setup.md) | [3. Key Bindings](3-key-bindings.md) | [4. Abbreviations](4-abbreviations.md) | [5. Functions Reference](5-functions-reference.md) | **6. Dependency Catalog** | [7. Customization](7-customization.md) | [8. Fisher Plugins](8-fisher-plugins.md) | [9. Viewing This Manual](9-viewing-this-manual.md) | [10. Installation](10-installation.md) | [11. Personalization](11-personalization.md) --- diff --git a/docs/wiki/7-customization.md b/docs/wiki/7-customization.md index 1331855..273c666 100644 --- a/docs/wiki/7-customization.md +++ b/docs/wiki/7-customization.md @@ -1,6 +1,6 @@ # 7. CUSTOMIZATION -**Sections:** [Index](index.md) | [1. Configuration Variables](1-configuration-variables.md) | [2. Path Setup](2-path-setup.md) | [3. Key Bindings](3-key-bindings.md) | [4. Abbreviations](4-abbreviations.md) | [5. Functions Reference](5-functions-reference.md) | [6. Dependency Catalog](6-dependency-catalog.md) | **7. Customization** | [8. Fisher Plugins](8-fisher-plugins.md) | [9. Viewing This Manual](9-viewing-this-manual.md) +**Sections:** [Index](index.md) | [1. Configuration Variables](1-configuration-variables.md) | [2. Path Setup](2-path-setup.md) | [3. Key Bindings](3-key-bindings.md) | [4. Abbreviations](4-abbreviations.md) | [5. Functions Reference](5-functions-reference.md) | [6. Dependency Catalog](6-dependency-catalog.md) | **7. Customization** | [8. Fisher Plugins](8-fisher-plugins.md) | [9. Viewing This Manual](9-viewing-this-manual.md) | [10. Installation](10-installation.md) | [11. Personalization](11-personalization.md) --- diff --git a/docs/wiki/8-fisher-plugins.md b/docs/wiki/8-fisher-plugins.md index 81d38c2..190f061 100644 --- a/docs/wiki/8-fisher-plugins.md +++ b/docs/wiki/8-fisher-plugins.md @@ -1,6 +1,6 @@ # 8. FISHER PLUGINS -**Sections:** [Index](index.md) | [1. Configuration Variables](1-configuration-variables.md) | [2. Path Setup](2-path-setup.md) | [3. Key Bindings](3-key-bindings.md) | [4. Abbreviations](4-abbreviations.md) | [5. Functions Reference](5-functions-reference.md) | [6. Dependency Catalog](6-dependency-catalog.md) | [7. Customization](7-customization.md) | **8. Fisher Plugins** | [9. Viewing This Manual](9-viewing-this-manual.md) +**Sections:** [Index](index.md) | [1. Configuration Variables](1-configuration-variables.md) | [2. Path Setup](2-path-setup.md) | [3. Key Bindings](3-key-bindings.md) | [4. Abbreviations](4-abbreviations.md) | [5. Functions Reference](5-functions-reference.md) | [6. Dependency Catalog](6-dependency-catalog.md) | [7. Customization](7-customization.md) | **8. Fisher Plugins** | [9. Viewing This Manual](9-viewing-this-manual.md) | [10. Installation](10-installation.md) | [11. Personalization](11-personalization.md) --- diff --git a/docs/wiki/9-viewing-this-manual.md b/docs/wiki/9-viewing-this-manual.md index 56b975f..1643ddb 100644 --- a/docs/wiki/9-viewing-this-manual.md +++ b/docs/wiki/9-viewing-this-manual.md @@ -1,6 +1,6 @@ # 9. VIEWING THIS MANUAL -**Sections:** [Index](index.md) | [1. Configuration Variables](1-configuration-variables.md) | [2. Path Setup](2-path-setup.md) | [3. Key Bindings](3-key-bindings.md) | [4. Abbreviations](4-abbreviations.md) | [5. Functions Reference](5-functions-reference.md) | [6. Dependency Catalog](6-dependency-catalog.md) | [7. Customization](7-customization.md) | [8. Fisher Plugins](8-fisher-plugins.md) | **9. Viewing This Manual** +**Sections:** [Index](index.md) | [1. Configuration Variables](1-configuration-variables.md) | [2. Path Setup](2-path-setup.md) | [3. Key Bindings](3-key-bindings.md) | [4. Abbreviations](4-abbreviations.md) | [5. Functions Reference](5-functions-reference.md) | [6. Dependency Catalog](6-dependency-catalog.md) | [7. Customization](7-customization.md) | [8. Fisher Plugins](8-fisher-plugins.md) | **9. Viewing This Manual** | [10. Installation](10-installation.md) | [11. Personalization](11-personalization.md) --- @@ -66,3 +66,5 @@ push to main that changes docs/fish-config.md. help config fish-deps The keyword is matched case-insensitively against section headings. + +--- diff --git a/docs/wiki/index.md b/docs/wiki/index.md index da76d37..05b0568 100644 --- a/docs/wiki/index.md +++ b/docs/wiki/index.md @@ -41,8 +41,6 @@ The configuration is split across: --- ---- - ## Table of Contents - [1. Configuration Variables](1-configuration-variables.md) @@ -54,3 +52,5 @@ The configuration is split across: - [7. Customization](7-customization.md) - [8. Fisher Plugins](8-fisher-plugins.md) - [9. Viewing This Manual](9-viewing-this-manual.md) +- [10. Installation](10-installation.md) +- [11. Personalization](11-personalization.md)