DOCSEARCHbyAlgolia
Submit Docs

Notebook Navigator for Neovim

repository·main·Indexed 42 days ago

https://github.com/gcballesteros/notebooknavigator.nvim

A Neovim plugin that brings Jupyter-like code cell functionality to standard text files. It enables defining, navigating, manipulating, and executing code cells within a REPL using providers such as iron.nvim, toggleterm.nvim, or molten-nvim, without requiring .ipynb files.

Tokens
1.5K
Snippets
4
Records
5
Agent score
4%

What's inside Notebook Navigator

  1. Enable cell marker highlighting with mini.hipatterns

    main

    To get high-quality highlighting for your cell markers, install mini.hipatterns and add the notebook-navigator spec to its highlighters option.

    return {
  "echasnovski/mini.hipatterns",
  event = "VeryLazy",
  dependencies = { "GCBallesteros/NotebookNavigator.nvim" },
  opts = function()
    local nn = require "notebook-navigator"

    local opts = { highlighters = { cells = nn.minihipatterns_spec } }
    return opts
  end,
}

  2. Integrate Notebook Navigator with mini.ai textobjects

    main

    You can use Notebook Navigator's cell logic as a mini.ai textobject. This allows you to perform actions like dah (delete cell), yih (yank inside cell), or vah (visual select cell) using the h textobject.

    return {
  "echasnovski/mini.ai",
  event = "VeryLazy",
  dependencies = { "GCBallesteros/NotebookNavigator.nvim" },
  opts = function()
    local nn = require "notebook-navigator"

    local opts = { custom_textobjects = { h = nn.miniai_spec } }
    return opts
  end,
}

  3. Install Notebook Navigator using lazy.nvim

    main

    To install Notebook Navigator, use the following lazy.nvim specification. It is recommended to map cell movement and execution to leader keys for quick access, while using the Hydra mode for more complex manipulations.

    Note that this setup includes iron.nvim as the REPL provider and mini.comment for cell commenting. You can swap iron.nvim for toggleterm.nvim or molten-nvim depending on your preference.

    {
  "GCBallesteros/NotebookNavigator.nvim",
  keys = {
    { "]h", function() require("notebook-navigator").move_cell "d" end },
    { "[h", function() require("notebook-navigator").move_cell "u" end },
    { "<leader>X", "<cmd>lua require('notebook-navigator').run_cell()<cr>" },
    { "<leader>x", "<cmd>lua require('notebook-navigator').run_and_move()<cr>" },
  },
  dependencies = {
    "echasnovski/mini.comment",
    "hkupty/iron.nvim", -- repl provider
    -- "akinsho/toggleterm.nvim", -- alternative repl provider
    -- "benlubas/molten-nvim", -- alternative repl provider
    "anuvyklack/hydra.nvim",
  },
  event = "VeryLazy",
  config = function()
    local nn = require "notebook-navigator"
    nn.setup({ activate_hydra_keys = "<leader>h" })
  end,
}

  4. Configure Notebook Navigator options

    main

    You can customize the behavior of Notebook Navigator via the setup function.

    Key configuration options include:

    • cell_markers: A table defining markers for different languages (e.g., { python = "# %%" }).
    • activate_hydra_keys: The keymap that triggers the Hydra mode. If nil, Hydra is disabled.
    • show_hydra_hint: Boolean to show/hide the hint panel when Hydra is active.
    • hydra_keys: A table of mappings used while the Hydra head is active. Use the string "nil" to unmap a key.
    • repl_provider: Specifies the REPL interface. Options: "iron", "toggleterm", "molten", or "auto" (detects installed providers).
    • syntax_highlight: Boolean to enable simple syntax-based highlighting for markers.
    • cell_highlight_group: The highlight group used when using mini.hipatterns.
    -- Example configuration structure
require("notebook-navigator").setup({
  cell_markers = {
    -- python = "# %%",
  },
  activate_hydra_keys = "<leader>h",
  show_hydra_hint = true,
  hydra_keys = {
    comment = "c",
    run = "X",
    run_and_move = "x",
    move_up = "k",
    move_down = "j",
    add_cell_before = "a",
    add_cell_after = "b",
  },
  repl_provider = "auto",
  syntax_highlight = false,
  cell_highlight_group = "Folded",
})

  5. Use the Notebook Navigator API

    main

    The following functions are available for manual mapping or programmatic use:

    • move_cell(dir): Move up or down a cell ("u" or "d").
    • run_cell(repl_args): Run the current cell. repl_args is an optional table passed to the REPL provider.
    • run_and_move(repl_args): Run the current cell and move to the next one.
    • swap_cell(dir): Swap the current cell with the one above ("u") or below ("d").
    • run_all_cells(repl_args): Run the entire file.
    • run_cells_below(repl_args): Run the current cell and all subsequent cells.
    • comment_cell: Comment the code inside the current cell.
    • add_cell_below: Add a cell marker below the current cell.
    • add_cell_above: Add a cell marker above the current cell.
    • split_cell: Split the current cell at the current line.
    • merge_cell(dir): Merge the current cell with the one above ("u") or below ("d").