Vim-NoteWiki

A lightweight Vim / Neovim plugin for keeping a personal wiki of Markdown notes, with one-command export to self-contained HTML via Pandoc.

Notes are plain Markdown files linked to each other like a wiki. vim-notewiki adds the navigation, link-creation and export commands on top; it also bundles vim-pandoc-syntax for Pandoc-flavored Markdown highlighting and a small Beamer syntax extension.

Features

Requirements

Installation

Use your favorite plugin manager.

vim-plug

Plug 'matteogiorgi/vim-notewiki'

Vundle

Plugin 'matteogiorgi/vim-notewiki'

packer.nvim

use 'matteogiorgi/vim-notewiki'

Native package (Vim 8+ / Neovim), no plugin manager

git clone https://github.com/matteogiorgi/vim-notewiki.git ~/.vim/pack/plugins/start/vim-notewiki

Then run the plugin manager's install command (:PlugInstall, :PluginInstall, :PackerSync, …) — not needed for the native package method.

The plugin activates automatically on filetype=markdown buffers; there is nothing else to configure to get started.

Getting started

On load, vim-notewiki makes sure ~/notewiki exists and treats it as the default root of your wiki. This is just a convenient starting point, though: the linking and navigation commands work the same in any directory, so you can keep your notes wherever you like (see Configuration to change the default). Open (or create) the default wiki's index with:

:NoteWikiIndex

From there, or any other markdown file, place the cursor on a word and press <CR>: the first press turns it into a link (word $\to$ [word](word.md)); pressing <CR> again — now on the link — creates and opens word.md right next to the current file. (If you write the full [text](file.md) syntax by hand, one <CR> on it is enough, since it is already a link.)

Every note you write lives as a plain .md file, so the whole wiki is just a directory tree you can inspect, grep, or version-control with git.

Key mappings

Mappings below are active in Markdown buffers (ftplugin/markdown/notewiki.vim) and are built on top of <Plug> mappings, so they are easy to remap.

Mapping <Plug> Action
<leader>n (NoteWiki) Open the index note of the current directory
<leader>N (NoteBrowse) Open the current note's directory in a file browser
<leader>p (NotePandoc) Export the current note to HTML
<CR> (OpenLink) Follow the link under the cursor, or create one from the word under the cursor
<BS> (Back) Go back to the note you came from
<Tab> (NextLink) Jump to the next link in the note
<S-Tab> (PrevLink) Jump to the previous link in the note
\ (EndPar) Insert an HTML-comment paragraph break
- / _ — :HeaderIncrease / :HeaderDecrease (promote/demote the heading level)
j / k — Move by display line (gj/gk), useful with wrap

Global mappings (available everywhere, not just in notes):

Mapping Command Action
<leader>n :NoteWikiIndex Open ~/notewiki/index.md
<leader>N :NoteBrowseIndex Open ~/notewiki in a file browser

Other commands:

Command Action
:ScratchBuffer Open a disposable, unsaved scratch buffer for quick notes

Exporting notes to HTML

Running :NotePandoc (or <leader>p) on a Markdown note:

  1. Copies the bundled pandoc/ assets (favicon/head snippet, link-rewriting filter, and the export script itself) next to your note the first time it is exported, so each wiki sub-directory ends up self-contained and portable.
  2. Runs Pandoc with MathJax support, the note's parent directory name as the page title, and the link2html.py filter, which rewrites .md links to .html so the exported pages keep linking to each other correctly.
  3. Writes the result as pandoc/<notename>.html next to your note.

Steps 2 and 3 are handled by the makenote script (step 1 is done by the :NotePandoc Vim function itself):

pandoc "$currfile" -s --to=html5 -o "$pandoc/$1.html" \
    --mathjax \
    --filter="$pandoc/assets/link2html.py" \
    -H "$pandoc/assets/header.html" \
    -T "$prefixtail"

makenote is a plain shell script copied into every wiki sub-directory, so it is meant to be edited: tweak the Pandoc flags, drop the MathJax/header options, or point --to at a different writer to export somewhere other than HTML (e.g. --to=pdf -o "$pandoc/$1.pdf" for a PDF, provided a PDF engine such as LaTeX is installed). Changes only affect notes in that sub-directory, since each one gets its own copy of the pandoc/ assets.

Configuration

" Where your notes live (default: ~/notewiki)
let $wikipages = fnamemodify('~/notewiki', ':p')

" File browser used to open note directories (default: xdg-open)
let g:notebrowser = 'xdg-open'

vim-pandoc-syntax (vendored under syntax/pandoc.vim) is highly configurable — see doc/pandoc-syntax.txt or :help pandoc-syntax for the full list of g:pandoc#syntax#* options (conceal characters, embedded code-block highlighting per language, emphasis styles, and more).

Project layout

vim-notewiki powered by Geoteo