From a9752fb2a45104f7101c1b9e3dd653a3dd5fab8c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?John=20Bj=C3=B6rk?= <john.bjork@wirelesscar.com>
Date: Sat, 6 Dec 2025 19:54:33 +0100
Subject: [PATCH] Exposing Vim from codemirror-vim

Docs for adding keybindings

Only expose Vim from keybindings
---
 packages/codemirror/index.mjs              |  1 +
 packages/codemirror/keybindings.mjs        |  2 ++
 website/src/pages/technical-manual/vim.mdx | 21 +++++++++++++++++++++
 3 files changed, 24 insertions(+)

diff --git a/packages/codemirror/index.mjs b/packages/codemirror/index.mjs
index 3a5f2a23c..2d5b3de21 100644
--- a/packages/codemirror/index.mjs
+++ b/packages/codemirror/index.mjs
@@ -4,3 +4,4 @@ export * from './flash.mjs';
 export * from './slider.mjs';
 export * from './themes.mjs';
 export * from './widget.mjs';
+export { Vim } from './keybindings.mjs';
diff --git a/packages/codemirror/keybindings.mjs b/packages/codemirror/keybindings.mjs
index d92e9c959..24437b7e1 100644
--- a/packages/codemirror/keybindings.mjs
+++ b/packages/codemirror/keybindings.mjs
@@ -131,6 +131,8 @@ const keymaps = {
   vscode: vscodeExtension,
 };
 
+export { Vim } from '@replit/codemirror-vim';
+
 export function keybindings(name) {
   const active = keymaps[name];
   const extensions = active ? [Prec.high(active())] : [];
diff --git a/website/src/pages/technical-manual/vim.mdx b/website/src/pages/technical-manual/vim.mdx
index fa53aa550..6ec41d4a2 100644
--- a/website/src/pages/technical-manual/vim.mdx
+++ b/website/src/pages/technical-manual/vim.mdx
@@ -35,3 +35,24 @@ Troubleshooting
 
 - If :w logs but evaluation doesn't apply, ensure Vim keybindings are active and try again. You can also use Ctrl+Enter as a fallback.
 - For :q / gc, ensure focus is inside the editor. If an error occurs, reload the page to reset editor state and try again.
+
+## Adding custom keybindings
+
+To add custom keybindings the `Vim` object can be used (either from within a pattern or in a prebake script)
+
+Example:
+
+```javascript
+// Map 'jk' to Escape in normal mode
+Vim.map('jk', '<Esc>', 'insert');
+// Map 'U' to :w (Evaluate the current code)
+Vim.map('U', ':w<CR>', 'normal');
+// Map 'Q' to :q — Stop/pause playback
+Vim.map('Q', ':q<CR>', 'normal');
+// Map 'J' to find next '$' (jump to next label)
+Vim.map('J', '/\\$<CR>', 'normal');
+// Map 'K' to find previous '$' (jump to previous label)
+Vim.map('K', '?\\$<CR>', 'normal');
+```
+
+For more information on how to use the `Vim` object see [CodeMirror Vim](https://github.com/replit/codemirror-vim)