notes.nvim

A dead simple Neovim plugin for your todos, notes and ideas. Supports global, project, and git branch-scoped files, with an optional floating window and basic templates.

Installation

• vim.pack

vim.pack.add({ 'https://github.com/soifou/notes.nvim' })
require('notes').setup(opts)

• lazy.nvim

{
  "soifou/notes.nvim",
  cmd = 'Notes',
  config = function()
    require("notes").setup(opts)
  end,
}

Configuration

local opts = {
  store = {
    -- Absolute path where to store all your notes
    path = '~/my_notes',
    -- Store path strategy when creating notes
    strategy = 'root',
    -- Name and extension for the generated file, e.g. "todo.md"
    filename = 'todo',
    extension = '.md',
  },
  -- Basic config for the floating window
  floating_window = {
    enabled = false,
    width = 0.8,
    height = 0.8,
    row_offset = 0,
    col_offset = 0,
    border = nil,
    title = nil, -- support template vars
    title_pos = 'center',
    backdrop = 60,
  },
  template = {
    -- Content of the default template
    lines = { '# Notes - <<project>>', '', 'Have some ideas?' },
    -- Dates that look like this format...
    date_format = '%Y-%m-%d %H:%M',
    -- ... will be updated on save
    update_on_write = false,
  },
  -- Callback when opening a note
  on_open = function(bufnr) end,
}

Commands

• :Notes Opens project notes, shorthand for :Notes project
• :Notes branch Open branch-specific notes.
• :Notes global Open global notes.
• :Notes template Open template for new notes
• :Notes delete Delete current note (prompt for confirmation)

Keymaps

No keymap defined. But you can easily create your own, for example:

vim.keymap.set('n', '<Leader>to', function() notes.toggle('project') end, { desc = 'Project notes' })
vim.keymap.set('n', '<Leader>tb', function() notes.toggle('branch') end, { desc = 'Project branch notes' })
vim.keymap.set('n', '<Leader>tO', function() notes.toggle('global') end, { desc = 'Main notes' })

Callbacks

Customize the buffer when opening your note using the on_open callback:

require('notes').setup({
  on_open = function(bufnr)
    vim.opt_local.shiftwidth = 2
    vim.opt_local.softtabstop = 2
    vim.opt_local.signcolumn = 'no'

    vim.keymap.set('i', '<C-Enter>', function()
      local col = vim.api.nvim_win_get_cursor(0)[2]
      if col == 0 then return '- [ ] ' end
      return '<CR>'
    end, { buffer = bufnr, expr = true, desc = 'Smart todo' })
  end,
})

Enable the floating window only in certain conditions:

require('notes').setup({
  floating_window = {
    enabled = function() return vim.o.columns > 150 end,
  }
})

Template

notes.nvim uses a basic inline template for new notes.

Customize it by editing the template file:

1. Run :Notes template to open ~/my_notes/template.md
2. Edit to your liking, use variables below to add dynamic value
3. Save, all future notes will use your custom template

Default (from opts.template.lines):

# Notes - <<project>>

Have some ideas?

Available variables

Variable	Description
<<date>>	Current date according to opts.template.date_format
<<project>>	Project name
<<branch>>	Branch of your project
<<kind>>	Note kind (see API)

API

kind: "project" | "branch" | "global" | "template"

• require('notes').open(kind): Open note
• require('notes').toggle(kind): Toggle note
• require('notes').delete(): Delete current note

Store

The store directory is created automatically on setup if it does not exist.

As an overview, here is an example of the file structure used for the store when creating notes for several project using the 'project' strategy:

~/my_notes/
├── todo.md         # :Notes global
├── template.md     # :Notes template
├── awesome_project
│   ├── todo.md     # :Notes project
│   ├── main.md     # :Notes branch (main branch)
│   └── feature.md  # :Notes branch (feature branch)
├── foobar_baz
│   ├── feat
│   │   └── foo.md  # :Notes branch (feat/foo branch)

You can choose a strategy that decides how to generate the folders to store your notes:

Strategy	Description	Example
'project'	Project only	~/foo/bar/baz -> ~/my_notes/baz
'parent'	Parent project	~/foo/bar/baz -> ~/my_notes/bar/baz
'root'	Relative to your home	~/foo/bar/baz -> ~/my_notes/foo/bar/baz

You may sync ~/my_notes across machines to keep your notes and ideas with you!

Warning

Keep the project path the same. If you're not using the 'project' strategy, don't change how you navigate to your project folder. For example, don't sometimes open it as /mnt/path/my_project and other times as ~/Projects/my_project, the logic treats these as different locations because it relies on the $PWD environment variable.

Similar Plugins

• vim-bujo
• nvim-workbench

Contributing

Issues and ideas are welcome.

Feel free to open a PR or discussion if you have improvements or feature requests.

License

MIT