nuwiki

A vimwiki-compatible Vim/Neovim plugin backed by a Rust language server.

nuwiki replaces the original vimwiki plugin while keeping its file format, keymaps, and :Vimwiki* command surface intact. The substantive work happens in a Rust LSP daemon — Vim and Neovim are thin client layers that wire up keystrokes and display results.

Features

Syntax & rendering

• Full vimwiki syntax (.wiki) — headings, lists with checkboxes, numbered / lettered / Roman lists, tables (with |---|, |:--|--:|:--:| alignment markers and > / \/ colspan/rowspan), inline math, code fences, tags, comments, and links (wiki, interwiki, diary, file, local, raw URL, transclusion).
• Transclusions support attributes: {{image.png|alt|style="border:1px"}}.
• HTML export with templates, CSS, RSS feed, and incremental :VimwikiAll2HTML.

Editor intelligence (LSP)

• Goto-definition (follow wikilinks), backlinks, hover preview, completion on [[, document outline, workspace symbol search.
• Semantic-token highlighting (no syntax-file fallback needed).
• Broken-link diagnostics and an orphan-page finder.
• Folding: server-driven foldingRange by default, regex fallback when the server isn't ready.

Editing

• Insert-mode smart <CR>: continues list markers (-, *, 1., a), i), …) and checkboxes; breaks out of an empty bullet; inserts a fresh row when inside a |…| table.
• Insert-mode <Tab> / <S-Tab> jumps between table cells, adding a new row past the last column.
• <C-D> / <C-T> indent/dedent the current list item; <C-L><C-J> / <C-L><C-K> cycle through the marker styles; <C-L><C-M> toggles or adds a checkbox.
• Five text-object pairs in operator-pending + visual mode: ah/ih (heading section), aH/iH (heading + subtree), al/il (list item), a\/i\ (table cell), ac/ic (table column).
• Two-step <CR> on a bare word: wraps it as [[word]], second press follows the link.

Diary

• Daily diary out of the box (<Leader>ww, <C-Down> / <C-Up>).
• Configurable cadence: set diary_frequency = 'weekly' (or 'monthly' / 'yearly') per wiki and the commands address 2026-W19.wiki, 2026-05.wiki, 2026.wiki instead. Navigation stays at the same cadence as the entry under the cursor.
• Diary index page generation (:VimwikiDiaryGenerateLinks).

Other

• Multi-wiki with cross-wiki [[wn.name:Page]] interwiki links and a :VimwikiUISelect picker.
• TOC generation, tag search, tag-to-page link lists.
• :Vimwiki* command compat + canonical :Nuwiki* aliases.
• Plain Vim and Neovim both supported with feature parity (text objects, folding, smart insert-mode bindings).

---

Installation

The plugin ships a nuwiki-ls binary that the editor talks to over LSP stdio. The install() helper downloads a pre-built release for your platform, falling back to cargo build --release if no asset matches. You can run it any time with :NuwikiInstall (works in both Vim and Neovim) instead of relying on a plugin-manager build hook.

Requirements

• Neovim 0.11+ — uses the built-in LSP client; no extra plugin. Older releases fall back to a vim.lsp.start autocmd but aren't officially supported.
• Vim 9+ — needs a third-party LSP client: vim-lsp (recommended, auto-registered) or coc.nvim (one-time coc-settings.json entry — see Vim LSP client setup).
• Rust toolchain (1.83+ stable) — only needed when building the binary from source; pre-built release downloads skip this.

lazy.nvim

{
  'gffranco/nuwiki',
  build = ":lua require('nuwiki').install()",
  ft = { 'vimwiki' },
  opts = {
    wiki_root = '~/vimwiki',
  },
}

vim-plug

Plug 'gffranco/nuwiki', { 'do': 'vim -e -s -c "source scripts/download_bin.vim" -c "q"' }

In init.lua / init.vim:

require('nuwiki').setup({ wiki_root = '~/vimwiki' })

Dein

call dein#add('gffranco/nuwiki', {
  \ 'build': 'vim -e -s -c "source scripts/download_bin.vim" -c "q"'
  \ })

Plain Vim (no plugin manager)

git clone https://code.gfran.co/gffranco/nuwiki ~/.vim/pack/gffranco/start/nuwiki
cd ~/.vim/pack/gffranco/start/nuwiki && cargo build --release -p nuwiki-ls
mkdir -p bin && ln -s ../target/release/nuwiki-ls bin/nuwiki-ls

Vim LSP client setup

Neovim 0.11+ registers the server through its built-in LSP client automatically — nothing to configure. Plain Vim needs one of the following clients on its runtimepath; nuwiki picks them up in this order when the first .wiki buffer loads.

vim-lsp (recommended) — zero configuration. Once vim-lsp (and its async.vim dependency) is installed, nuwiki calls lsp#register_server() for you and vim-lsp auto-enables it. Your wiki settings (g:nuwiki_wiki_root, g:nuwiki_wikis, …) are forwarded as the server's initialization options.

coc.nvim — coc.nvim reads its server list from coc-settings.json, which the plugin can't edit on your behalf, so add the entry once yourself (open it with :CocConfig):

{
  "languageserver": {
    "nuwiki": {
      "command": "~/.vim/pack/gffranco/start/nuwiki/bin/nuwiki-ls",
      "filetypes": ["vimwiki"]
    }
  }
}

Point command at the installed binary — by default it lives in the plugin's bin/ directory (adjust the path for your plugin manager), or set g:nuwiki_binary_path and reuse that value. With coc you can also invoke server commands directly via :CocCommand nuwiki.<command> instead of the :Vimwiki* / :Nuwiki* aliases.

Try it without touching your config

./development/start-nvim.sh   # spawns Neovim against an isolated sample wiki
./development/start-vim.sh    # same, for plain Vim (clones vim-lsp on first run)

Both scripts build the LSP binary, seed a scratch wiki, and launch the editor against an isolated state dir under $XDG_CACHE_HOME/nuwiki-dev.

---

Configuration

Defaults are vimwiki-compatible. Every key has a sensible default — the example below shows the full surface for reference.

require('nuwiki').setup({
  -- Single-wiki shorthand (vimwiki-compatible).
  wiki_root      = '~/vimwiki',
  file_extension = '.wiki',
  syntax         = 'vimwiki',     -- 'vimwiki' | 'markdown' (future)
  log_level      = 'warn',

  -- Multi-wiki: each entry honours every per-wiki key vimwiki understands.
  -- Pick either this OR the single-wiki shorthand above. If both are set,
  -- `wikis` wins.
  wikis = {
    {
      name             = 'personal',
      root             = '~/vimwiki',
      index            = 'index',        -- index page stem
      file_extension   = '.wiki',
      -- Diary
      diary_rel_path   = 'diary',
      diary_index      = 'diary',
      diary_frequency  = 'daily',        -- 'daily' | 'weekly' | 'monthly' | 'yearly'
      diary_sort       = 'desc',         -- 'desc' | 'asc'
      diary_header     = 'Diary',
      -- HTML export
      html_path        = '~/vimwiki/_html',
      template_path    = '~/vimwiki/_templates',
      template_default = 'default',
      template_ext     = '.tpl',
      css_name         = 'style.css',
      auto_export      = false,          -- export on save
      auto_toc         = false,          -- auto-refresh TOC on save
      exclude_files    = {},             -- glob patterns
      -- Checkbox progression characters: " .oOX" by default.
      listsyms         = ' .oOX',
      listsyms_propagate = true,
      -- Inline highlighting: 6 heading levels by default.
      maxhi            = 1,
      -- Embed other syntaxes inside `{{{lang …}}}` fences.
      nested_syntaxes  = {},
    },
  },

  -- Keymap groups. Flip subgroups off independently. Defaults all on.
  mappings = {
    enabled       = true,
    wiki_prefix   = true,  -- <Leader>w*
    links         = true,  -- <CR>, <S-CR>, <Tab>, <BS>, +, …
    lists         = true,  -- <C-Space>, gln/glp/glx, gl<Space>, o/O, …
    headers       = true,  -- =, -, ]], [[, ]=, [=, ]u, [u
    table_editing = true,  -- gqq, <A-Left>, <A-Right>, <Tab> in insert mode
    diary         = true,  -- <C-Down>, <C-Up>
    html_export   = true,  -- <Leader>wh, <Leader>whh
    text_objects  = true,  -- ah, ih, aH, iH, al, il, a\, i\, ac, ic
    mouse         = false, -- <2-LeftMouse>, <RightMouse>, …  (opt-in)
  },

  -- 'lsp' (server-driven foldingRange, default) | 'expr' (regex) | 'off'.
  folding = 'lsp',

  -- Broken-link diagnostic severity: 'off' | 'hint' | 'warn' | 'error'.
  diagnostic = {
    link_severity = 'warn',
  },
})

Vim users without Lua set the equivalent globals before loading the plugin:

let g:nuwiki_wiki_root            = '~/vimwiki'
let g:nuwiki_file_extension       = '.wiki'
let g:nuwiki_log_level            = 'warn'
let g:nuwiki_no_default_mappings  = 0   " set to 1 to skip the keymap layer
let g:nuwiki_no_folding           = 0   " set to 1 to skip foldexpr setup
let g:nuwiki_mouse_mappings       = 0   " set to 1 to enable mouse maps

---

Usage

Commands

:Nuwiki* is the canonical native surface; every command also has a :Vimwiki* counterpart for drop-in migration. Both are registered as buffer-local commands on every .wiki buffer (the wiki picker is also global so you can switch wikis before any .wiki file is open). Type :Nuwiki<Tab> or :Vimwiki<Tab> to browse them; coc.nvim users can also call the server directly with :CocCommand nuwiki.<command>.

Only the legacy short forms :VWB / :VWS and :VimwikiSearch keep a Vimwiki-only name (shown as — in the Nuwiki column); every other command is mirrored. The split / tab link-following commands exist on the Neovim path only — plain Vim uses the <S-CR> / <C-CR> mappings instead.

Wiki & navigation

Nuwiki	Vimwiki	Action
:NuwikiIndex [N]	:VimwikiIndex [N]	Open wiki N's index page (default: 1)
:NuwikiTabIndex [N]	:VimwikiTabIndex [N]	Same, in a new tab
:NuwikiUISelect	:VimwikiUISelect	Pick a wiki from a list (multi-wiki)
:NuwikiGoto {page}	:VimwikiGoto {page}	Open {page}.wiki by name
:NuwikiFollowLink	:VimwikiFollowLink	Follow the link under the cursor
:NuwikiSplitLink / :NuwikiVSplitLink / :NuwikiTabnewLink	:VimwikiSplitLink / :VimwikiVSplitLink / :VimwikiTabnewLink	Follow the link in a horizontal split / vertical split / new tab (Neovim)
:NuwikiGoBackLink	:VimwikiGoBackLink	Jump back to where you followed the link from (Neovim)
:NuwikiBacklinks	:VimwikiBacklinks (:VWB)	Show all references to the current page
:NuwikiNextLink / :NuwikiPrevLink	:VimwikiNextLink / :VimwikiPrevLink	Jump to the next / previous wikilink
:NuwikiBaddLink	:VimwikiBaddLink	Add the link target under the cursor to the buffer list
—	:VimwikiSearch {pat} (:VWS)	:lvimgrep {pat} across every page

Diary

Nuwiki	Vimwiki	Action
:NuwikiMakeDiaryNote (:NuwikiDiaryToday)	:VimwikiMakeDiaryNote	Open today's entry (or this week / month / year, per diary_frequency)
:NuwikiMakeYesterdayDiaryNote (:NuwikiDiaryYesterday)	:VimwikiMakeYesterdayDiaryNote	Step the diary back one period
:NuwikiMakeTomorrowDiaryNote (:NuwikiDiaryTomorrow)	:VimwikiMakeTomorrowDiaryNote	Step the diary forward one period
:NuwikiDiaryIndex	:VimwikiDiaryIndex	Open the diary index page
:NuwikiDiaryGenerateLinks	:VimwikiDiaryGenerateLinks	Rebuild the diary index from current entries
:NuwikiDiaryNextDay / :NuwikiDiaryPrevDay (:NuwikiDiaryNext / :NuwikiDiaryPrev)	:VimwikiDiaryNextDay / :VimwikiDiaryPrevDay	Chronological diary nav (same cadence as the current entry)

Pages & files

Nuwiki	Vimwiki	Action
:NuwikiRenameFile	:VimwikiRenameFile	Rename the current page, rewriting incoming links
:NuwikiDeleteFile	:VimwikiDeleteFile	Delete the current page

Lists, tasks & tables

Nuwiki	Vimwiki	Action
:NuwikiNextTask	:VimwikiNextTask	Jump to the next unfinished task
:NuwikiToggleListItem	:VimwikiToggleListItem	Toggle the checkbox under the cursor
:NuwikiToggleRejected	:VimwikiToggleRejectedListItem	Toggle the rejected marker [-]
:NuwikiRemoveDone	:VimwikiRemoveDone	Remove every completed item from the current list
:NuwikiListChangeLvl {increase|decrease}	:VimwikiListChangeLvl {increase|decrease}	Indent / dedent the current list item
:NuwikiTable {cols} [rows]	:VimwikiTable {cols} [rows]	Insert a table at the cursor
:NuwikiTableMoveColumnLeft / :NuwikiTableMoveColumnRight	:VimwikiTableMoveColumnLeft / :VimwikiTableMoveColumnRight	Move the current table column left / right

Contents, links & tags

Nuwiki	Vimwiki	Action
:NuwikiTOC	:VimwikiTOC	Generate / refresh the table of contents on the current page
:NuwikiGenerateLinks	:VimwikiGenerateLinks	Insert a flat list of every page in the wiki
:NuwikiCheckLinks	:VimwikiCheckLinks	Send broken links to the quickfix list
:NuwikiFindOrphans	:VimwikiFindOrphans	List pages with no incoming links in the quickfix list
:NuwikiRebuildTags	:VimwikiRebuildTags	Force a full workspace re-index
:NuwikiSearchTags {tag}	:VimwikiSearchTags {tag}	Quickfix listing every occurrence of :tag:
:NuwikiGenerateTagLinks [tag]	:VimwikiGenerateTagLinks [tag]	Insert a section linking every page that has <tag>
:NuwikiColorize {color}	:VimwikiColorize {color}	Wrap the word / visual selection in a coloured <span>
:NuwikiPasteLink / :NuwikiPasteUrl	:VimwikiPasteLink / :VimwikiPasteUrl	Paste the clipboard contents as a wikilink / raw URL

HTML export

Nuwiki	Vimwiki	Action
:Nuwiki2HTML (:NuwikiExport)	:Vimwiki2HTML	Render the current page to HTML
:Nuwiki2HTMLBrowse (:NuwikiExportBrowse)	:Vimwiki2HTMLBrowse	Render the current page and open it in the default browser
:NuwikiAll2HTML[!] (:NuwikiExportAll[!])	:VimwikiAll2HTML[!]	Export the whole wiki (! forces; otherwise incremental)
:NuwikiRss	:VimwikiRss	Write rss.xml for diary entries

Default keymaps

All buffer-local. Disable any group via mappings.<group> = false in Neovim, or let g:nuwiki_no_default_mappings = 1 in Vim.

Links (normal mode)

Key	Action
<CR>	Smart follow — inside [[…]] jumps; on a bare word wraps as [[word]] (second <CR> follows)
<S-CR>	Follow in horizontal split
<C-CR>	Follow in vertical split
<C-S-CR>	Follow in a new tab
<BS>	Jump back (<C-o>)
<Tab> / <S-Tab>	Next / previous wikilink on or after the cursor
+	Wrap word / visual selection as a wikilink (no follow)

Lists (normal mode)

Key	Action
<C-Space> / <C-@> / <Nul>	Toggle the checkbox under the cursor (the three aliases cover terminal byte differences)
gln / glp	Cycle the checkbox state forward / backward
glx	Toggle the rejected marker [-]
gnt	Jump to the next unfinished task
glh / gll	Dedent / indent the current list item
gLh / gLl	Dedent / indent including the item's sublist
glr	Renumber the current ordered list
gLr	Renumber every ordered list in the buffer
gl<Space>	Remove every completed item from the current list
gL<Space>	Remove every completed item in the buffer
o / O	Open a new line and continue the list marker (preserves any checkbox)

Lists (insert mode)

Key	Action
<CR>	Continue the list with the same marker (preserves checkbox), or break out on an empty bullet
<C-D> / <C-T>	Dedent / indent the current item
<C-L><C-J> / <C-L><C-K>	Cycle the marker style (- → * → # → 1. → 1) → a) → A) → i) → I))
<C-L><C-M>	Toggle / add a checkbox on the current item

Headers

Key	Action
= / -	Increase / decrease the heading level
]] / [[	Next / previous heading (any level)
]= / [=	Next / previous sibling heading
]u / [u	Jump to the parent heading

Tables

Key	Action
gqq / gq1 / gww / gw1	Align the table under the cursor
<A-Left> / <A-Right>	Move the column under the cursor left / right
<Tab> / <S-Tab> (insert)	Jump to the next / previous cell; <Tab> past the last cell inserts a fresh row
<CR> (insert)	Insert a fresh empty row below the current one

Wiki / diary / export (normal mode)

Key	Action
<Leader>ww	Open the wiki index
<Leader>wt	Open the wiki index in a new tab
<Leader>ws	Pick a wiki
<Leader>wi	Open the diary index
<Leader>w<Leader>w / <Leader>w<Leader>y / <Leader>w<Leader>t	Diary today / yesterday / tomorrow
<Leader>w<Leader>m	Diary tomorrow (vimwiki-compat alias of <Leader>w<Leader>t)
<Leader>w<Leader>i	Rebuild the diary index page
<Leader>wn / <Leader>wd / <Leader>wr	Goto / delete / rename page
<Leader>wh / <Leader>whh	Export the current page to HTML / open in browser
<Leader>wha	Export every page
<Leader>wc	Wrap word (or visual selection) in a colour span
<C-Down> / <C-Up>	Next / previous diary entry

Mouse (normal mode, opt-in via mappings.mouse = true / let g:nuwiki_mouse_mappings = 1)

Key	Action
<2-LeftMouse>	Follow the link under the pointer
<S-2-LeftMouse> / <C-2-LeftMouse>	Follow in a horizontal / vertical split
<MiddleMouse>	Add the link target to the buffer list
<RightMouse>	Jump back (<C-o>)

Text objects (operator-pending + visual)

Object	Selection
ah / ih	The heading's section (ih excludes the heading line)
aH / iH	The heading's section plus every subheading underneath
al / il	The list item under the cursor (il excludes the marker / checkbox)
a\ / i\	The table cell under the cursor (i\ excludes the surrounding |)
ac / ic	The table column under the cursor (ic excludes the header separator row)

Health check (Neovim)

:checkhealth nuwiki

Reports the binary path, the LSP client status, registered executeCommand entries, whether foldingRange was negotiated, and whether the configured HTML output directory is writable.

Migrating from vimwiki

The file extension, syntax, command names, and default keymaps all match vimwiki. To migrate:

1. Drop the original vimwiki plugin from your config.
2. Install nuwiki.
3. Point wiki_root (or each wikis[i].root) at your existing directory.

Existing pages, diary entries, tags, and templates work without modification. The first workspace scan after launch may show an empty :VimwikiCheckLinks result until the background index completes; subsequent runs are instant.

---

License

Dual-licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE)
• MIT license (LICENSE-MIT)

at your option. Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this work shall be dual licensed as above, without any additional terms or conditions.