Home

Awesome

jupyter-vim-binding

Version 2.1.0 Support Jupyter 4.1 or above MIT License Doc

See https://github.com/jupyterlab-contrib/jupyterlab-vim for an alternative of this plugin.

Do you use Vim? And you need to use Jupyter Notebook? This is a Jupyter Notebook (formerly known as IPython Notebook) extension to enable Vim like environment powered by CodeMirror's Vim. I'm sure that this plugin helps to improve your QOL.

<div align="center"> <img src="resource/screencast.gif" alt="Screencast"> </div>

This extension stands for providing a Vim like environment, so it would drastically overwrite the default mappings and introduce new behaviors. For example

Need contributors

While I changed my job, I don't use jupyter notebook, and I can't make enough time to maintain this plugin.

So if you like this plugin, please consider being a contributor.

https://github.com/lambdalisue/jupyter-vim-binding/issues/89

Installation

There are several ways to install the extension, see Installation for detail. The procedure below is the most simple one for quick use (A recommended way is different from this. See the link above if you are a beginner.)

# Create required directory in case (optional)
mkdir -p $(jupyter --data-dir)/nbextensions
# Clone the repository
cd $(jupyter --data-dir)/nbextensions
git clone https://github.com/lambdalisue/jupyter-vim-binding vim_binding
# Activate the extension
jupyter nbextension enable vim_binding/vim_binding

Usage

This extension provides Jupyter mode (For manipulating Jupyter) and Vim mode (For manipulating text). In Vim mode, there is Command mode and Insert mode like native Vim. Users can distinguish these modes by the background color of the cell.

Key mappings are designed for Vimmer so probably you don't need to know much about the mapping but remember the followings to survive:

You can find detailed information about the mappings or concept in Concept page.

Completion and Tooltip

jupyter-vim-binding supports <C-n>/<C-p> completion and <C-g> tooltip in a code cell (not in markdown / raw cell). These mappings are not listed in a help panel, due to a technical limitation.

When the user hits <C-n> or <C-p>, a completion panel like below will be shown. Once the completion panel is shown, users can select a candidate by <C-n>/<C-p> and apply by <Enter> or cancel by <Esc>.

Completion

When user hit <C-g>, a tooltip panel like below will be shown. The tooltip will disappear when users perform some actions like hitting a key.

Tooltip

Note that you can repeat <C-g> to make the tooltip larger (more information).

Plug mappings

jupyter-vim-binding provides the following <Plug> mappings for CodeMirror.

While CodeMirror's Vim does not provide noremap type of mappings. You need to use these <Plug> mappings to prevent an infinite loop (See samples in Customization section).

Customization

To customize key mappings in Vim mode, you need to understand that there are two kinds of mappings in this extension:

  1. Mappings provided by Jupyter Notebook, users can customize this type of mappings with Keyboard shortcut editor provided in IPython-notebook-extensions
  2. Mappings provided by CodeMirror's Vim, users can customize this type of mappings with custom.js as described below

To customize mappings provided by CodeMirror's Vim, create a custom.js at ~/.jupyter/custom/custom.js (at least in Linux) and use CodeMirror's Vim API to manipulate like:

// Configure CodeMirror Keymap
require([
  'nbextensions/vim_binding/vim_binding',   // depends your installation
], function() {
  // Map jj to <Esc>
  CodeMirror.Vim.map("jj", "<Esc>", "insert");
  // 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");
});

// Configure Jupyter Keymap
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;
    // Allow Ctrl-2 to change the cell mode into Markdown in Vim normal mode
    km.edit_shortcuts.add_shortcut('ctrl-2', 'vim-binding:change-cell-to-markdown', true);
    // Update Help
    km.edit_shortcuts.events.trigger('rebuild.QuickHelp');
  });
});

If you would like to customize the design, create a your custom.css at ~/.jupyter/custom/custom.css (at least in Linux) like:

/* Jupyter cell is in normal mode when code mirror */
.edit_mode .cell.selected .CodeMirror-focused.cm-fat-cursor {
  background-color: #F5F6EB !important;
}
/* Jupyter cell is in insert mode when code mirror */
.edit_mode .cell.selected .CodeMirror-focused:not(.cm-fat-cursor) {
  background-color: #F6EBF1 !important;
}

See Customization to find useful snippets. Don't be afraid to share your snippets at that page ;-)

Limitation

jupyter-vim-binding has the following technical limitation. If anybody knows about a confirmed workaround for these limitations, let me know.

Google Chrome

Google Chrome prohibits javascript from overriding several key mappings such as Ctrl-N, Ctrl-T, etc. Because of this policy, users have no chance to use default key mappings of jupyter-vim-binding, such as <C-n> completion.

Vivaldi

The chromium-based Vivaldi browser provides more flexibility in key mapping customizations and might be a viable alternative to Google Chrome for power users. In contrast to Google Chrome or Chromium, (almost) all keyboard shortcuts in Vivaldi can be changed or disabled, including (but not limited to) Ctrl-N, Ctrl-T, Ctrl-J, etc.

Furthermore, Vivaldi allows assigning a keyboard shortcut to temporarily disable all other browser keyboard shortcuts, making all key mappings available for other uses. Note that this temporary change applies globally to all tabs and windows of the browser instance (or "Profile") under consideration. To confine it to a subset of tabs, use a separate profile via the --user-data-dir=... option.

Clipboard

Most modern browsers prohibit javascript from accessing a system clipboard without user action, such as clicking a button. Because of this, there is no chance to enable copy and paste through yy, dd, or p while HTML5 clipboard object cannot be retrieved in a keydown event. So Users need to use browser default mappings such as Ctrl-C, Ctrl-V if they want to copy and paste through a system clipboard.

The followings are clipboard library for javascript, but all of them require click event or no paste support.

What we need is a clipboard object which can be used for copy and paste in a keydown event rather than click event. However, I don't know any workaround for this, so it is impossible to perform copy and paste in yy or p for now.

License

The MIT License (MIT)

Copyright (c) 2015-2016 Alisue, hashnote.net

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.