neuron.nvim

Note: If you want to use this plugin with the latest neuron version please use the unstable branch

Make neovim the best note taking application. This plugin uses neovim 0.5 to be able to take advantage of the latest cool features.

Why

Neovim combined with lua and the neuron binary allow one of the coolest note taking experiences. This plugin is like notational velocity combined with vimwiki with much more features. Do you like notational velocity? Well you can do that here. Run lua require'neuron/telescope'.find_zettels() to be able to find your notes. If you typed something that doesn't match any existing note, it will create one. Because this plugin is built on the latest features from neovim 0.5, it allows for asynchronous update. For example, if you type a valid link (not just a valid link syntax wise, this plugin also checks if the file exists), it will put virtual text on the side. No need :w neovim to update these titles, they update automatically while you type. You can run a neuron server inside neovim asynchronously and it will render all your markdown notes on the web, and auto update on save.

Features

• Great integration with telescope.nvim (currently the most extensible fuzzy finder)
• Because of that integration, can find tags, backlinks, notes
• Uses the new extmark api, sets an extmark for each valid link
• Fast because written in lua rather than vimscript

Installation

Prerequisites

Make sure you have the neuron binary installed.

MacOS installation notes

You can use Whalebrew version on MacOS, see here. If you won't be using rib server to view your notes on the web, disable port forwarding - otherwise you'll get port conflict errors for zettels with multiple links. To do that, open whalebrew's launcher with vi $(which neuron) and remove ports section.

neuron.nvim depends on the neovim plugins telescope.nvim and plenary.nvim. Why plenary.nvim? Telescope.nvim depends on plenary.nvim which contains lots of useful functions for lua because of how minimal lua is. This encourages code reuse and allows for many cool things

Plugins

using packer.nvim:

use "oberblastmeister/neuron.nvim"
use 'nvim-lua/popup.nvim'
use "nvim-lua/plenary.nvim"
use "nvim-telescope/telescope.nvim"

vim-plug:

Plug 'oberblastmeister/neuron.nvim'
Plug 'nvim-lua/popup.nvim'
Plug 'nvim-lua/plenary.nvim'
Plug 'nvim-telescope/telescope.nvim'

home-manager:

{
  programs.neovim = {
    enable = true;
    plugins = with pkgs.vimPlugins; [
      neuron-nvim
      # ...
    ];
  };
  # ...
}

Usage

You must run the setup function to be able to use this plugins. The setup function takes your config and merges it with the default config. Any key not specified will be a default. In your init.lua, run

-- these are all the default values
require'neuron'.setup {
    virtual_titles = true,
    mappings = true,
    run = nil, -- function to run when in neuron dir
    neuron_dir = "~/neuron", -- the directory of all of your notes, expanded by default (currently supports only one directory for notes, find a way to detect neuron.dhall to use any directory)
    leader = "gz", -- the leader key to for all mappings, remember with 'go zettel'
}

After running the setup function opening a note will show virtual text on the side to show the title of the note.

Default mappings

 " click enter on [[my_link]] or [[[my_link]]] to enter it
nnoremap <buffer> <CR> <cmd>lua require'neuron'.enter_link()<CR>

" create a new note
nnoremap <buffer> gzn <cmd>lua require'neuron/cmd'.new_edit(require'neuron'.config.neuron_dir)<CR>

" find your notes, click enter to create the note if there are not notes that match
nnoremap <buffer> gzz <cmd>lua require'neuron/telescope'.find_zettels()<CR>
" insert the id of the note that is found
nnoremap <buffer> gzZ <cmd>lua require'neuron/telescope'.find_zettels {insert = true}<CR>

" find the backlinks of the current note all the note that link this note
nnoremap <buffer> gzb <cmd>lua require'neuron/telescope'.find_backlinks()<CR>
" same as above but insert the found id
nnoremap <buffer> gzB <cmd>lua require'neuron/telescope'.find_backlinks {insert = true}<CR>

" find all tags and insert
nnoremap <buffer> gzt <cmd>lua require'neuron/telescope'.find_tags()<CR>

" start the neuron server and render markdown, auto reload on save
nnoremap <buffer> gzs <cmd>lua require'neuron'.rib {address = "127.0.0.1:8200", verbose = true}<CR>

" go to next [[my_link]] or [[[my_link]]]
nnoremap <buffer> gz] <cmd>lua require'neuron'.goto_next_extmark()<CR>
" go to previous
nnoremap <buffer> gz[ <cmd>lua require'neuron'.goto_prev_extmark()<CR>]]

Syntax Highlighting

neuron.nvim does not provide its own syntax highlighting out of the box because there are many better options. I recommend nvim-treesitter because it currently offers the best syntax highlighting and also to highlight code fences.

Comparisons

neuron.nvim was heavily inspired by neuron.vim. Here is table table to show the differences. I also used to use vimwiki so there is a comparison to that also.

header	neuron.nvim	neuron.vim	vimwiki
virtual text	✔️	✔️	❌
asynchronous update	✔️	❌	N.A
fuzzy finding	telescope.nvim	fzf.vim	❌
asynchronous jobs integration	✔️	❌	❌
extmarks	✔️	❌	❌
written in	lua	vimscript	vimscript
works for older neovim versions	❌	✔️	✔️
actions for notes in fuzzy finder	coming soon	❌	❌
render notes	✔️	✔️	✔️
supports vim	❌	✔️	✔️
use neuron binary	✔️	✔️	❌

License

Copyright (c) 2020 Brian Shu

neuron.nvim is distributed under the terms of the MIT license.

See the LICENSE