github github
stars 51
issues 1
subscribers 6
forks 1



10 days ago

note.nvim 📓

A Neovim note taking plugin for daily notes, task tracking and easy deep linking across files or git commits.


The goal is to reduce the cost of interruptions and make it easy to recontextualize when you return to work in progress. Nested task items, deep links, time-based logging and being able to mark items as current makes it easy to take a fairly detailed snapshot of your 'working heap'.


use 'gsuuon/note.nvim'


With lazy.nvim:

    opts = {
      -- Spaces are note roots. These directories should contain a `./notes` directory (will be made if not).
      -- Defaults to { '~' }.
      spaces = {
        -- '~/projects/foo'

      -- Set keymap = false to disable keymapping
      -- keymap = { 
      --   prefix = '<leader>n'
      -- }
    cmd = 'Note',
    ft = 'note'


A tree-sitter grammar can be installed with :TSInstall note. The grammar includes markdown style code-fenced injections of other languages and makes it possible to use treesitter based navigation like tshjkl with note items.


The treesitter highlight groups are linked in ftplugin/note.lua and the group queries are in queries/note/highlights.scm. You can customize these by overriding the groups with your own links or highlights.


Open the daily note with :Note. This can be scoped to a workspace root with the spaces config option:

  spaces = { '~', '~/myproject' }

You can create a custom template for daily notes at [note_root]/.note/daily_template. note comes with treesitter based highlighting but falls back to a syntax file if the grammar is not installed.

Keymaps are added for note.nvim commands with a default prefix of <leader>n.


Items can be properties or tasks. The first character is a marker that indicates the type and status of the item, some examples:

- pending task
  * info property
. finished task
  [ label property
  . sub task

Items are indent scoped - a newline and 2 spaces start a child item scope. They can contain any text content. Anything below an item which doesn't start a new scope becomes part of the text content of that item.

- a pending task
const scratchFn = () => {}
- other task


> — current
- — pending
. — done
= — paused
, — cancelled


* — info
[ — label


# — section -- Not indented - the number of #'s mean depth like markdown.


Some special symbols will also highlight to help with readability:

-> — flow -- indicates one thing flowing to another
<- — select -- indicates selecting one of a list
(?) — question -- draw attention to something confusing
(!) — warn -- draw attention to something important


Links to items are created by simply writing text like [(<file>)<marker>|<body>]. Follow a link by putting the cursor over it and calling :NoteGoLink. This will search for a target item first by looking downwards from the link and then upwards. The file part can point to a specific commit.

  • <body> behaves like a case-insensitive string.match against items.
  • (<file>) if present links to that file relative to the current file - the path is joined with the current file's directory. If the file part starts with / then the path is resolved relative to the note root.
  • (<file>@<commit>) links to the file at a specific commit. The git root must be the same as the note workspace root.
  • <marker> is a specific marker (e.g. -, *) or one of these special characters:

s — section -- matches any number of #'s
p — property -- matches any property marker
t — task -- matches any task marker

For example:

[t|clean] links to a task containing 'clean'
[(chores)s|daily] links to a file in the same directory as the current file named 'chores' and finds the first section with 'daily'
[(/budget)t|groceries] links to the 'budget' file in the note root and finds the first 'groceries' task



Take out the trash is labeled as a [ chore.

- Take out the trash
  [ chore

Pick up toys is the current (>) task and is part of Cleanup house.

- Cleanup house
  - Wash dishes
  > Pick up toys

[t|monday] links to the - Monday task and [(../health)s|goal] links to the the 'health' file up one directory at a section matching goal.

# Gym
- Monday
  - Squats



Note <path> — Create or open the daily note if no arguments. Tab completes arguments with files from current note root
NoteIndex — Edit the note index of the current space

Note buffers

NoteCurrentItem — Jump to the current task (>)
NoteFindItem <marker> <body pattern> — Jump to a matching item. Tab completes if marker is s with available sections in file
NoteMarkItem <marker> — Change the marker of the item under cursor. Only for task or property markers. Dot-repeatable.
NoteMarkItemChildren <marker> — The cursor item and all children with a matching marker get marked
NoteGoLink — Follow the link under cursor
NoteTime <marker?> — Insert a timestamped item with marker (defaults to *) NoteReport — Notify with a summary of the current note
NoteLinkPinCommit — Modify the link under the cursor to pin it to the current commit (and absolute path of current file if not specified)


NoteRefCreate — Create a ref for the item under the cursor
NoteRefPaste — Paste a link to the last created ref
NoteRefYank — Yank the ref for the item under the cursor to use with NoteRefPaste

*Linked* commands add a ref link from the source item to the target and from target to the source
NoteItemLinkedYank — Yank the item under the cursor. Creates a ref if one doesn't exist
NoteItemLinkedPaste — Paste the last LinkedYank item
NoteItemLinkToday <marker> <body> — Yank the item under the cursor and add it as a child item of marker body in the daily note

Daily notes

NotePrevious — Edit the previous daily note
NoteNext — Edit the next daily note


Note buffers

<prefix>t — NoteTime
<prefix>l — NoteGoLink
<prefix>c — NoteCurrentItem
<prefix>m<marker> — NoteMarkItem
<prefix>M<marker> — NoteMarkItemChildren
<prefix>f<marker> — NoteFindItem .

Daily notes

<prefix>n — NoteNext
<prefix>p — NotePrevious