nb.nvim

A lightweight, high-performance Neovim plugin that integrates with the command-line note-taking and knowledge base application nb.

Features

• Wiki-Style Link Autocompletion: Automatically triggers only when typing inside double brackets [[ ... ]].
• New Note Creation: Prompt for a note title and immediately create and open it in Neovim (default keybinding: <localleader>nn).
• Wiki-Link Navigation: Press <CR> (Enter) on any wiki-style link to open it instantly. If the note doesn't exist, prompts to create it.
• History Navigation: Press <BS> (Backspace) in normal mode inside notebook files to jump back to the previously visited note.
• Fast, Non-Blocking Caching: Traverses notebook directories using Neovim's built-in fast libuv filesystem APIs. Spawns nb only when checking configurations, preventing keystroke lag.
• Smart Note Mapping: Resolves notes using their filenames, folders, titles, or index IDs mapping directly to nb conventions.
• Auto Cache Invalidation: Watches note file writes in your active notebook to automatically refresh cached note options.
• Supports Multiple Formats: Detects note headers dynamically for Markdown (# Heading), Org-mode (#+title:), and AsciiDoc (= Title).
• Flexible Insert Options: Configure insertion format to relative paths (e.g., [[subfolder/note-name]]), filenames, titles, or nb index IDs.

---

Installation

Install using your favorite package manager.

Lazy.nvim

{
  "mschmidty/nb.nvim",
  dependencies = {
    -- Depending on your completion engine:
    -- "hrsh7th/nvim-cmp",
    -- "Saghen/blink.cmp",
  },
  config = function()
    require("nb").setup({
      -- Optional configuration overrides
      -- link_format = "relative", -- default
    })
  end
}

---

Configuration

The default configuration options are:

require("nb").setup({
  -- The notebook name to use. If nil/empty, queries `nb notebooks current` (usually "home").
  notebook = nil,

  -- Path to the notebook. If nil/empty, dynamically queries `nb notebooks show <notebook> --path`.
  notebook_path = nil,

  -- Completion insertion format. Options:
  -- "relative"  => [[folder/note]] (relative path without extension, recommended)
  -- "filename"  => [[folder/note.md]] (relative path with extension)
  -- "title"     => [[Note Title]] (note title)
  -- "id"        => [[3]] (note index ID)
  link_format = "relative",
})

---

Setup with Completion Engines

nvim-cmp

Once nb.nvim is installed and setup is called, the nb source is registered automatically. Add it to your sources list in your cmp setup:

require("cmp").setup({
  sources = {
    { name = "nb" }, -- Add this to enable nb wiki link completions
    { name = "buffer" },
    { name = "path" },
  }
})

blink.cmp

Define the provider in your blink.cmp configurations:

require("blink.cmp").setup({
  sources = {
    default = { "lsp", "path", "snippets", "buffer", "nb" },
    providers = {
      nb = {
        name = "nb",
        module = "nb.blink",
        score_offset = 100, -- prioritize wiki links inside [[ ]]
      }
    }
  }
})

---

Usage

1. Open a Markdown or text file inside your nb note directory (or anywhere).
2. Type [[ followed by characters.
3. The autocomplete menu will trigger, showing matching notes from your notebook with titles, paths, and IDs.
4. Select a completion item to insert it.

Commands

• :NbRefresh — Forces a reload of the notebook notes list cache.

---

Running Tests

Verify the plugin's parsing and prefix detection logic by running:

nvim --headless -u NONE -c "luafile tests/test_nb.lua" -c "qa!"