Customization

This wiki is a place to share snippets that enhance the usability of the vim - IPython integration, but aren't so general that they are part of the binding.

Disable automatic insertion of closing brackets and quotes

Jupyter automatically pairs the delimiters ( [ { ' " when typed in code cells. Add the following to ~/.jupyter/custom/custom.js to disable this feature:

IPython.CodeCell.options_default.cm_config.autoCloseBrackets = false;

See https://codemirror.net/doc/manual.html#addon_closebrackets for a complete description of this option.

Swap j/k and gj/gk

require([
  'nbextensions/vim_binding/vim_binding',   // depends your installation
], function() {
  // Swap j/k and gj/gk (Note that <Plug> mappings)
  CodeMirror.Vim.map("j", "<Plug>(vim-binding-gj)", "normal");
  CodeMirror.Vim.map("k", "<Plug>(vim-binding-gk)", "normal");
  CodeMirror.Vim.map("gj", "<Plug>(vim-binding-j)", "normal");
  CodeMirror.Vim.map("gk", "<Plug>(vim-binding-k)", "normal");
});

Emacs like binding in Insert Mode

require([
  'nbextensions/vim_binding/vim_binding',
], function() {
  // Emacs like binding
  CodeMirror.Vim.map("<C-a>", "<Esc>^i", "insert");
  CodeMirror.Vim.map("<C-e>", "<Esc>$a", "insert");
  //CodeMirror.Vim.map("<C-f>", "<Esc>lwi", "insert"); // This seems more likely to M-f (move forward one word)
  //CodeMirror.Vim.map("<C-b>", "<Esc>lbi", "insert"); // This seems more likely to M-b (move backward one word)
  CodeMirror.Vim.map("<C-f>", "<Esc>2li", "insert");
  CodeMirror.Vim.map("<C-b>", "<Esc>i", "insert");
  CodeMirror.Vim.map("<C-d>", "<Esc>lxi", "insert");
  CodeMirror.Vim.map("<C-h>", "<Esc>xi", "insert");
});

Move around in Insert mode with Ctrl-h/j/k/l

require([
  'nbextensions/vim_binding/vim_binding',
], function() {
  // Use Ctrl-h/l/j/k to move around in Insert mode
  CodeMirror.Vim.defineAction('[i]<C-h>', function(cm) {
    var head = cm.getCursor();
    CodeMirror.Vim.handleKey(cm, '<Esc>');
    if (head.ch <= 1) {
      CodeMirror.Vim.handleKey(cm, 'i');
    } else {
      CodeMirror.Vim.handleKey(cm, 'h');
      CodeMirror.Vim.handleKey(cm, 'a');
    }
  });
  CodeMirror.Vim.defineAction('[i]<C-l>', function(cm) {
    var head = cm.getCursor();
    CodeMirror.Vim.handleKey(cm, '<Esc>');
    if (head.ch === 0) {
      CodeMirror.Vim.handleKey(cm, 'a');
    } else {
      CodeMirror.Vim.handleKey(cm, 'l');
      CodeMirror.Vim.handleKey(cm, 'a');
    }
  });
  CodeMirror.Vim.mapCommand("<C-h>", "action", "[i]<C-h>", {}, { "context": "insert" });
  CodeMirror.Vim.mapCommand("<C-l>", "action", "[i]<C-l>", {}, { "context": "insert" });
  CodeMirror.Vim.map("<C-j>", "<Esc>ja", "insert");
  CodeMirror.Vim.map("<C-k>", "<Esc>ka", "insert");

  // Use Ctrl-h/l/j/k to move around in Normal mode
  // otherwise it would trigger browser shortcuts
  CodeMirror.Vim.map("<C-h>", "h", "normal");
  CodeMirror.Vim.map("<C-l>", "l", "normal");
  // Updated for v2.0.0
  // While jupyter-vim-binding use <C-j>/<C-k> to move around cell
  // The following key mappings should not be defined
  //CodeMirror.Vim.map("<C-j>", "j", "normal");
  //CodeMirror.Vim.map("<C-k>", "k", "normal");
});

Selecting all

require([
  'nbextensions/vim_binding/vim_binding',
], function() {
   CodeMirror.Vim.map("<C-a>", "ggVG", "normal");
});

Map Y to yy in insert mode

require([
  'nbextensions/vim_binding/vim_binding',
], function() {
   CodeMirror.Vim.map("Y", "yy", "normal");
});

Enable <C-c> mapping to exit insert mode

The default configuration adds a setting to ignore the chord. The following code removes that setting and provides a mapping.

// enable the 'Ctrl-C' mapping
// change the code mirror configuration
var cm_config = require("notebook/js/cell").Cell.options_default.cm_config;
delete cm_config.extraKeys['Ctrl-C'];
// change settings for existing cells
Jupyter.notebook.get_cells().map(function(cell) {
    var cm = cell.code_mirror;
    if (cm) {
        delete cm.getOption('extraKeys')['Ctrl-C'];
    }
});
// map the keys
CodeMirror.Vim.map("<C-c>", "<Esc>", "insert");

Run cell scrolls the cell to top (scroll output into view)

// Run and scroll to top
Jupyter.keyboard_manager.actions.register({
    'help': 'run selected cells',
    'handler': function(env, event) {
        env.notebook.command_mode();
        var actions = Jupyter.keyboard_manager.actions;
        actions.call('jupyter-notebook:run-cell', event, env);
        actions.call('jupyter-notebook:scroll-cell-top', event, env);
        env.notebook.edit_mode();
    }
}, 'run-and-top', 'vim-binding');

// Run and scroll to top and select next
Jupyter.keyboard_manager.actions.register({
    'help': 'run selected cells',
    'handler': function(env, event) {
        env.notebook.command_mode();
        var actions = Jupyter.keyboard_manager.actions;
        actions.call('jupyter-notebook:run-cell', event, env);
        actions.call('jupyter-notebook:scroll-cell-top', event, env);
        actions.call('jupyter-notebook:select-next-cell', event, env);
        env.notebook.edit_mode();
    }
}, 'run-and-next-and-top', 'vim-binding');

// Add two keyboard shortcuts for the new actions
require([
  'nbextensions/vim_binding/vim_binding',
  'base/js/namespace',
], function(vim_binding, ns) {
  // Add post callback
  vim_binding.on_ready_callbacks.push(function(){
    var km = ns.keyboard_manager;
    // Indicate the key combination to run the commans
    km.edit_shortcuts.add_shortcut('ctrl-enter', 'vim-binding:run-and-top', true);
    km.edit_shortcuts.add_shortcut('shift-enter', 'vim-binding:run-and-next-and-top', true);
    // Update Help
    km.edit_shortcuts.events.trigger('rebuild.QuickHelp');
  });
});

Show trailing spaces

// custom.js
require([
  'base/js/namespace',
  'notebook/js/cell',
  'codemirror/addon/edit/trailingspace'
], function(ns, cell) {
  var cm_config = cell.Cell.options_default.cm_config;
  cm_config.showTrailingSpace = true;

  ns.notebook.get_cells().map(function(cell) {
    var cm = cell.code_mirror;
    if (cm) {
      cm.setOption('showTrailingSpace', true);
    }
  });
});

/* custom.css */
.cm-trailingspace {
  border-bottom: 1px solid #ccc;
}

Adding custom actions

require(['codemirror/keymap/vim'], function() {
  // a
  CodeMirror.Vim.defineAction("hello", function(){console.log("hello")});
  // 'a' is the key you map the action to
  CodeMirror.Vim.mapCommand("a", "action", "hello", {}, {context: "normal"}); 
});

Adding custom operators

// custom operator for commenting
// (similar to commentary by Tim Pope)
// this woks with visual selection ('vipgc') and with motions ('gcip')
require(['nbextensions/vim_binding/vim_binding'], function() {
    CodeMirror.Vim.defineOperator("comment_op", function(cm) {
        cm.toggleComment();
    });
    CodeMirror.Vim.mapCommand("gc", "operator", "comment_op", {});
});

Calling a Jupyter shortcut

require(['base/js/namespace'], function(ns) {
    ns.keyboard_manager.actions.call('jupyter-notebook:run-cell-and-insert-below');
});

Powerful resources

• CodeMirror Vim API
• Available Jupyter actions
• Default Jupyter shortcuts