From 987f131ce86a34acc1f59baf72b017c5663c6ea5 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 29 Jul 2026 00:56:23 +0000 Subject: [PATCH] docs(website): add keybindings guide to the docs site The site had no page for the [keybindings] remapping surface the README links repo docs for; add a compact guide covering the replacement rules and chord grammar, wire it into the Configure sidebar, and cross-link it from the keyboard page and docs index. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01KHY9ReVesQXwKdRU47MwJ9 --- .changeset/website-keybindings-docs.md | 2 ++ website/astro.config.mjs | 1 + .../docs/docs/configure/keybindings.md | 36 +++++++++++++++++++ website/src/content/docs/docs/index.mdx | 1 + .../docs/docs/start/keyboard-and-mouse.md | 4 +++ 5 files changed, 44 insertions(+) create mode 100644 .changeset/website-keybindings-docs.md create mode 100644 website/src/content/docs/docs/configure/keybindings.md diff --git a/.changeset/website-keybindings-docs.md b/.changeset/website-keybindings-docs.md new file mode 100644 index 000000000..a845151cc --- /dev/null +++ b/.changeset/website-keybindings-docs.md @@ -0,0 +1,2 @@ +--- +--- diff --git a/website/astro.config.mjs b/website/astro.config.mjs index f67ac169c..9eb5ecef2 100644 --- a/website/astro.config.mjs +++ b/website/astro.config.mjs @@ -89,6 +89,7 @@ export default defineConfig({ { label: "Configuration", slug: "docs/configure/configuration" }, { label: "Themes", slug: "docs/configure/themes" }, { label: "Layout and display", slug: "docs/configure/layout-and-display" }, + { label: "Keybindings", slug: "docs/configure/keybindings" }, ], }, { diff --git a/website/src/content/docs/docs/configure/keybindings.md b/website/src/content/docs/docs/configure/keybindings.md new file mode 100644 index 000000000..f2bb0294d --- /dev/null +++ b/website/src/content/docs/docs/configure/keybindings.md @@ -0,0 +1,36 @@ +--- +title: Keybindings +description: Remap Hunk's named commands to your own keys with the user-config keybindings table. +--- + +Every keyboard shortcut is a named command. A `[keybindings]` table in your user config maps command ids to the chords you want them on: + +```toml +[keybindings] +"hunk.app.quit" = "ctrl+x" # one chord +"hunk.review.nextHunk" = ["]", "ctrl+n"] # several chords for one command +"hunk.review.focusFilter" = "f" # takes "f" away from page-down +"hunk.view.toggleMenuBar" = false # unbind it entirely +"myext.toggle" = "ctrl+g" # extension commands too +``` + +Every id starts with the name of whoever owns the command: Hunk's own commands live under `hunk.`, and an extension's live under its extension id. `hunk` is a reserved extension id, so an extension can never shadow a built-in command. + +## Rules + +- **User bindings replace defaults.** The chords you list are the complete set of keys that command answers to. +- **A key you bind is yours.** Any command holding the same chord only as a default gives it up and keeps its other keys. +- **`false` (or `[]`) unbinds a command**, leaving its keys doing nothing. +- Two entries claiming one chord is a conflict: the first in the file wins and the session reports the other. Unknown ids and unusable chords are reported the same way, and the rest of the table still applies. + +## Chord grammar + +Chords join `ctrl`, `alt`/`option`, `cmd`/`meta`, and `shift` with `+` around a base key: a character (`"y"`, `"["`), an uppercase letter for its shifted form (`"G"`), or a named key (`"tab"`, `"pageup"`, `"left"`, `"f2"`). `shift` applies to letters and named keys only — for a shifted symbol or digit, write the character shift produces (`"!"`, not `"shift+1"`), since that is what terminals report. + +## Find command ids + +The menus and the in-app help (`?`) always show the keys each command currently holds, so a remap changes what they advertise. The full table of built-in command ids and their default keys lives in [`docs/keybindings.md`](https://github.com/modem-dev/hunk/blob/main/docs/keybindings.md) in the repository. Commands listed without a default key are menu items today; binding one gives it a shortcut like any other. + +Keys owned by a dialog, menu, or focused text input — `Esc`, `Enter`, `Ctrl-S` while writing a note — belong to those widgets and are not remappable. + +`[keybindings]` is read from your user config only, never from a repository's `.hunk/config.toml`: which keys do what is a property of your keyboard and habits, so a checkout you review cannot rearrange them. diff --git a/website/src/content/docs/docs/index.mdx b/website/src/content/docs/docs/index.mdx index 089ea2af4..a66e95ce5 100644 --- a/website/src/content/docs/docs/index.mdx +++ b/website/src/content/docs/docs/index.mdx @@ -54,5 +54,6 @@ Hunk is a terminal diff viewer for reviewing complete changesets and keeping age - [Configure Hunk as a Git pager or difftool](/docs/workflows/git-pager-and-difftool/) - [Review a live session with a coding agent](/docs/agents/review-with-an-agent/) - [Choose a theme and layout](/docs/configure/themes/) +- [Remap a keyboard shortcut](/docs/configure/keybindings/) - [Look up a command](/docs/reference/cli/) - [Troubleshoot terminal behavior](/docs/help/troubleshooting/) diff --git a/website/src/content/docs/docs/start/keyboard-and-mouse.md b/website/src/content/docs/docs/start/keyboard-and-mouse.md index 9bcd1cfa4..599b3842f 100644 --- a/website/src/content/docs/docs/start/keyboard-and-mouse.md +++ b/website/src/content/docs/docs/start/keyboard-and-mouse.md @@ -54,4 +54,8 @@ Press `c` on the selected hunk or use a visible add-note affordance with the mou - Use the wheel or scrollbar to move through the review; hold Shift while scrolling to move horizontally through unwrapped code. - Select diff text for copy where the terminal supports it. +## Remap the defaults + +Every shortcut above is a named command you can move to different keys with a `[keybindings]` table in your user config. See [Keybindings](/docs/configure/keybindings/). + Terminal mouse protocols vary; see [terminal compatibility](/docs/help/compatibility/) if clicks or selection do not behave as expected.