gffranco
724712121d
Both remaining mapping gaps (client-side, both clients):
- Visual <CR>: upstream binds it to NormalizeLinkVisualCR (== visual `+`).
Added `x <CR>` -> normalize_link(true) (wrap the selection as a wikilink)
in both clients.
- Insert <S-CR>: upstream's multiline-list-item continuation (VimwikiReturn
2 2 -> kbd_cr with no new marker). New smart_shift_return (both clients,
<expr> insert mapping): on a list item returns <CR> + spaces aligning under
the item text (marker width + 1, +4 for a `[ ] ` checkbox), no marker; off a
list item, a plain <CR>. Mirrors smart_return's auto-indent handling.
Tests: map.visual_cr_wraps_selection + map.insert_shift_cr_multiline
(test-keymaps.lua, the latter exercising the handler directly since <S-CR>
doesn't round-trip headless feedkeys), and map.visual_cr_wraps_selection +
cr.shift_cr_multiline{,_checkbox} (test-keymaps-vim.vim). Docs (README +
doc/nuwiki.txt) and the gap doc updated. Neovim 305, Vim 299/18/21 pass.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
909 lines
39 KiB
Plaintext
909 lines
39 KiB
Plaintext
*nuwiki.txt* A vimwiki-compatible plugin backed by a Rust language server.
|
|
|
|
Author: Gabriel Fróes Franco
|
|
License: Dual MIT / Apache-2.0
|
|
|
|
==============================================================================
|
|
CONTENTS *nuwiki-contents*
|
|
|
|
1. Introduction ............ |nuwiki-introduction|
|
|
2. Requirements ............ |nuwiki-requirements|
|
|
3. Installation ............ |nuwiki-installation|
|
|
4. Configuration ........... |nuwiki-config|
|
|
5. Commands ................ |nuwiki-commands|
|
|
6. Keymaps ................. |nuwiki-keymaps|
|
|
7. Text objects ............ |nuwiki-text-objects|
|
|
8. Insert-mode bindings .... |nuwiki-insert-mode|
|
|
9. Diary ................... |nuwiki-diary|
|
|
10. Tables ................... |nuwiki-tables|
|
|
11. HTML export .............. |nuwiki-html|
|
|
12. Folding .................. |nuwiki-folding|
|
|
13. Health check ............. |nuwiki-health|
|
|
14. Migrating from vimwiki ... |nuwiki-migrating|
|
|
|
|
==============================================================================
|
|
1. INTRODUCTION *nuwiki-introduction*
|
|
|
|
nuwiki keeps vimwiki's file format, keymaps, and `:Vimwiki*` command surface
|
|
intact, but moves the heavy lifting into a Rust language server that the
|
|
editor talks to over LSP stdio. The result feels like vimwiki — same files,
|
|
same shortcuts — with goto-definition, backlinks, completion, semantic
|
|
highlighting, broken-link diagnostics, and incremental HTML export.
|
|
|
|
Highlights:
|
|
|
|
* Full vimwiki syntax — headings, lists, checkboxes, tables (with
|
|
alignment / colspan / rowspan), inline math, code, tags, every link
|
|
kind (wiki, interwiki, diary, file, local, raw URL, transclusion with
|
|
attributes).
|
|
* LSP intelligence — goto-definition, backlinks, hover, completion on
|
|
`[[`, document outline, workspace symbol search, broken-link
|
|
diagnostics, orphan-page finder.
|
|
* Editing helpers — smart `<CR>` continues lists / tables, `<Tab>`
|
|
cycles between table cells, five text-object pairs, list-marker
|
|
cycling.
|
|
* Diary at four cadences — daily, weekly, monthly, or yearly.
|
|
* Multi-wiki with `[[wn.name:Page]]` interwiki links.
|
|
* HTML export with templates, CSS, RSS, and on-save export.
|
|
* Plain Vim and Neovim both supported with feature parity.
|
|
|
|
==============================================================================
|
|
2. REQUIREMENTS *nuwiki-requirements*
|
|
|
|
* Neovim 0.11+ (preferred path)
|
|
* Vim 9.1+ with one of:
|
|
- vim-lsp (prabirshrestha/vim-lsp)
|
|
- coc.nvim (neoclide/coc.nvim)
|
|
* `curl` and `tar` (only for the binary download path; not needed if
|
|
you build from source)
|
|
* `cargo` and a Rust toolchain (only if you opt into source builds)
|
|
|
|
==============================================================================
|
|
3. INSTALLATION *nuwiki-installation*
|
|
|
|
Install via your plugin manager; the build hook downloads a pre-built
|
|
`nuwiki-ls` binary into the plugin's `bin/` directory.
|
|
|
|
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"' }
|
|
|
|
<dein.vim: >
|
|
|
|
call dein#add('gffranco/nuwiki', {
|
|
\ 'build': 'vim -e -s -c "source scripts/download_bin.vim" -c "q"',
|
|
\ })
|
|
|
|
<To force a build from source (skip the download path), set: >
|
|
|
|
let g:nuwiki_build_from_source = 1
|
|
|
|
<in Vim before re-running the build hook, or in Neovim: >
|
|
|
|
vim.g.nuwiki_build_from_source = 1
|
|
require('nuwiki').install()
|
|
|
|
<==============================================================================
|
|
4. CONFIGURATION *nuwiki-config*
|
|
|
|
Neovim users call `setup()` (omit the block entirely to take every
|
|
default): >
|
|
|
|
require('nuwiki').setup({
|
|
wiki_root = '~/vimwiki',
|
|
file_extension = '.wiki',
|
|
syntax = 'vimwiki',
|
|
log_level = 'warn',
|
|
map_prefix = '<Leader>w',
|
|
})
|
|
|
|
<For multiple wikis or per-wiki tuning, use the `wikis` list: >
|
|
|
|
require('nuwiki').setup({
|
|
wikis = {
|
|
{
|
|
name = 'personal',
|
|
root = '~/vimwiki',
|
|
index = 'index',
|
|
file_extension = '.wiki',
|
|
diary_rel_path = 'diary',
|
|
diary_frequency = 'daily', -- daily | weekly | monthly | yearly
|
|
diary_sort = 'desc',
|
|
html_path = '~/vimwiki/_html',
|
|
template_path = '~/vimwiki/_templates',
|
|
template_default = 'default',
|
|
css_name = 'style.css',
|
|
auto_export = false,
|
|
},
|
|
},
|
|
})
|
|
|
|
<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_map_prefix = '<Leader>w'
|
|
|
|
<Top-level options ~
|
|
|
|
*g:nuwiki_wiki_root*
|
|
`wiki_root` ~/vimwiki
|
|
Root directory of the single-wiki shorthand. Ignored when `wikis` is
|
|
set (the multi-wiki list takes precedence).
|
|
|
|
*g:nuwiki_file_extension*
|
|
`file_extension` .wiki
|
|
File extension associated with the wiki filetype.
|
|
|
|
*g:nuwiki_syntax*
|
|
`syntax` vimwiki
|
|
Future-proofing; currently only `vimwiki` is supported.
|
|
|
|
*g:nuwiki_log_level*
|
|
`log_level` warn
|
|
`error` | `warn` | `info` | `debug`. Forwarded to the language server.
|
|
|
|
*nuwiki-config-map-prefix*
|
|
`map_prefix` '<Leader>w'
|
|
Prefix for the wiki command family (`<prefix>w`, `<prefix>t`,
|
|
`<prefix><Leader>w`, …). Mirrors vimwiki's `g:vimwiki_map_prefix`. Vim
|
|
users set |g:nuwiki_map_prefix| instead.
|
|
|
|
*nuwiki-config-folding*
|
|
`folding` 'lsp'
|
|
`lsp` uses the server's `foldingRange` provider (Neovim 0.11+ wires
|
|
it automatically). `expr` falls back to a regex `foldexpr`. `off`
|
|
disables folding setup entirely. See |nuwiki-folding| for details.
|
|
Vim users see the regex fallback when |g:nuwiki_no_folding| is not
|
|
set.
|
|
|
|
*nuwiki-mappings*
|
|
`mappings` (all on except `mouse`)
|
|
Per-buffer keymap groups. Each subgroup can be flipped off
|
|
independently to suppress that group of keymaps. Subgroups:
|
|
`enabled`, `wiki_prefix`, `links`, `lists`, `headers`,
|
|
`table_editing`, `diary`, `html_export`, `text_objects`, `mouse`.
|
|
|
|
`diagnostic.link_severity` `'warn'`
|
|
Severity of broken-link diagnostics: `off`, `hint`, `warn`, `error`.
|
|
|
|
Per-wiki options ~
|
|
|
|
Every option in this list lives on a `wikis[i] = {...}` entry. Defaults
|
|
match upstream vimwiki.
|
|
|
|
`name` String — display name in `:VimwikiUISelect`.
|
|
`root` String — absolute or `~`-relative path.
|
|
`index` `'index'` — stem of the wiki's index page.
|
|
`file_extension` `'.wiki'`
|
|
`diary_rel_path` `'diary'`
|
|
`diary_index` `'diary'` — stem of the diary index page.
|
|
`diary_frequency` `'daily'` | `'weekly'` | `'monthly'` | `'yearly'`
|
|
`diary_weekly_style` `'iso'` (YYYY-Www) | `'date'`/`'vimwiki'` (week-start
|
|
YYYY-MM-DD). Weekly diaries only.
|
|
`diary_start_week_day` `'monday'`..`'sunday'`; week start used when
|
|
`diary_weekly_style = 'date'`.
|
|
`diary_caption_level` `0`
|
|
`diary_sort` `'desc'` | `'asc'`
|
|
`diary_header` `'Diary'`
|
|
`html_path` Path for `:Vimwiki2HTML` output.
|
|
`template_path` Path holding `<name>.tpl` templates.
|
|
`template_default` `'default'`
|
|
`template_ext` `'.tpl'`
|
|
`template_date_format` `'%Y-%m-%d'` — strftime format for `%date` in templates.
|
|
`css_name` `'style.css'`
|
|
`html_filename_parameterization` `false` — encode subdir paths into the HTML
|
|
filename instead of nesting directories.
|
|
`color_dic` `{}` — map of `{ name = 'color' }` for `:NuwikiColorize`.
|
|
`custom_wiki2html` `''` — external converter command. When set, export
|
|
shells out to it instead of the built-in renderer,
|
|
called as: <cmd> <force> <syntax> <ext> <out_dir>
|
|
<in_file> <css> <tpl_path> <tpl_default> <tpl_ext>
|
|
<root_path> <args> (`-` for empty optionals), matching
|
|
vimwiki's `g:vimwiki_custom_wiki2html` contract.
|
|
`custom_wiki2html_args` `''` — extra args appended to the converter call.
|
|
`base_url` `''` — public URL prefix. When set, diary RSS item
|
|
links become <base_url><diary_rel_path>/<date>.html
|
|
instead of local `file://` paths.
|
|
`auto_export` `false` — export to HTML on save.
|
|
`auto_toc` `false` — refresh TOC on save.
|
|
`auto_generate_links` `false` — regen an existing Generated Links section
|
|
on save.
|
|
`auto_generate_tags` `false` — regen an existing Generated Tags index on
|
|
save.
|
|
`auto_diary_index` `false` — regen the diary index when a diary entry is
|
|
saved.
|
|
`toc_header` `'Contents'` (+ `toc_header_level` `1`) — :VimwikiTOC.
|
|
`links_header` `'Generated Links'` (+ `links_header_level` `1`).
|
|
`tags_header` `'Generated Tags'` (+ `tags_header_level` `1`).
|
|
`exclude_files` List of glob patterns excluded from export.
|
|
`listsyms` `' .oOX'` — checkbox progression characters.
|
|
`listsym_rejected` `'-'` — glyph for a cancelled checkbox `[-]`.
|
|
`listsyms_propagate` `true`
|
|
`list_margin` `-1` — spaces before a list bullet; `-1` follows
|
|
`shiftwidth`.
|
|
`links_space_char` `' '`
|
|
|
|
Code fences tagged with a language (`{{{python …}}}`) are highlighted with
|
|
that language's syntax automatically — there is no `nested_syntaxes` key.
|
|
|
|
Vim-specific globals ~
|
|
|
|
*g:nuwiki_diary_rel_path*
|
|
`g:nuwiki_diary_rel_path` `'diary'`
|
|
Diary subdirectory, relative to the wiki root. The scalar form for the
|
|
single-wiki shape; per-wiki `diary_rel_path` (or `g:nuwiki_wikis`) wins.
|
|
|
|
*g:nuwiki_link_severity*
|
|
`g:nuwiki_link_severity` `'warn'`
|
|
Broken-link diagnostic severity: `off` | `hint` | `warn` | `error`. The
|
|
scalar/global form of the `diagnostic.link_severity` setup() option.
|
|
|
|
*g:nuwiki_no_default_mappings*
|
|
`g:nuwiki_no_default_mappings` 0
|
|
When 1, the Vim path skips every buffer-local keymap. Equivalent to
|
|
`mappings.enabled = false` in Neovim.
|
|
|
|
*g:nuwiki_no_wiki_prefix_mappings*
|
|
*g:nuwiki_no_links_mappings*
|
|
*g:nuwiki_no_lists_mappings*
|
|
*g:nuwiki_no_headers_mappings*
|
|
*g:nuwiki_no_table_editing_mappings*
|
|
*g:nuwiki_no_diary_mappings*
|
|
*g:nuwiki_no_html_export_mappings*
|
|
*g:nuwiki_no_text_objects_mappings*
|
|
`g:nuwiki_no_<group>_mappings` 0
|
|
Per-subgroup opt-outs, each defaulting to 0. Setting one to 1 drops just
|
|
that group's buffer-local keymaps while leaving the rest in place; the
|
|
whole-layer |g:nuwiki_no_default_mappings| still wins over all of them.
|
|
These mirror the Lua-side `mappings.<group>` booleans. Every binding in
|
|
each group (the `<Leader>w` prefix follows |g:nuwiki_map_prefix|):
|
|
`wiki_prefix` `<Leader>ww`, `<Leader>wt`, `<Leader>ws`,
|
|
`<Leader>wi`, `<Leader>w<Leader>w`,
|
|
`<Leader>w<Leader>y`, `<Leader>w<Leader>t`,
|
|
`<Leader>w<Leader>m`, `<Leader>w<Leader>i`
|
|
`links` `<CR>`, `<S-CR>`, `<C-CR>`, `<C-S-CR>`, `<D-CR>`,
|
|
`<M-CR>`, `<BS>`, `<Tab>`, `<S-Tab>`, `+` (n/x),
|
|
`<CR>` (x: normalize selection),
|
|
`<Leader>wn`, `<Leader>wd`, `<Leader>wr`,
|
|
`<Leader>wc` (n/x)
|
|
`lists` `<C-Space>` (also `<C-@>`/`<Nul>`), `gnt`, `gln`,
|
|
`glp`, `glx`, `glh`, `gll`, `gLh`, `gLl`, `glr`,
|
|
`gLr`, `gl-`, `gl*`, `gl#`, `gl1`, `gli`, `glI`,
|
|
`gla`, `glA`, `gL-`, `gL*`, `gL#`, `gL1`, `gLi`,
|
|
`gLI`, `gLa`, `gLA`, `gl`, `gL`, `o`, `O`; insert
|
|
`<C-D>`, `<C-T>`, `<C-L><C-J>`, `<C-L><C-K>`,
|
|
`<C-L><C-M>`, `<CR>`, `<S-CR>`
|
|
`headers` `=`, `-`, `]]`, `[[`, `]=`, `[=`, `]u`, `[u`
|
|
`table_editing` `gqq`, `gq1`, `gww`, `gw1`, `<A-Left>`,
|
|
`<A-Right>`; insert `<Tab>`, `<S-Tab>`
|
|
`diary` `<C-Down>`, `<C-Up>`
|
|
`html_export` `<Leader>wh`, `<Leader>whh`, `<Leader>wha`
|
|
`text_objects` `ah`, `ih`, `aH`, `iH`, `al`, `il`, `a\`, `i\`,
|
|
`ac`, `ic`
|
|
`mouse` `<2-LeftMouse>`, `<S-2-LeftMouse>`,
|
|
`<C-2-LeftMouse>`, `<MiddleMouse>`, `<RightMouse>`
|
|
|
|
*g:nuwiki_map_prefix*
|
|
`g:nuwiki_map_prefix` `'<Leader>w'`
|
|
Prefix for the wiki command family — both the global entry-point maps
|
|
(`<prefix>w`, `<prefix>t`, `<prefix>s`, `<prefix>i`, `<prefix><Leader>{w,y,
|
|
t,m,i}`) and the buffer-local ones (`<prefix>{n,d,r,c,h,hh,ha}`). Mirrors
|
|
vimwiki's `g:vimwiki_map_prefix`. Set it before the plugin loads. Neovim
|
|
users set the `map_prefix` option in `setup()` instead.
|
|
|
|
*g:nuwiki_no_folding*
|
|
`g:nuwiki_no_folding` 0
|
|
When 1, the Vim path skips `foldexpr` / `foldmethod` setup.
|
|
|
|
*g:nuwiki_autowriteall*
|
|
`g:nuwiki_autowriteall` 1
|
|
When 1 (default), Vim's global `'autowriteall'` is set while a wiki
|
|
buffer is current and restored on leave, so a modified buffer is
|
|
auto-saved on page switch / `:make`. Mirrors vimwiki's `autowriteall`
|
|
and the Neovim `autowriteall` setup option. Set to 0 to leave
|
|
`'autowriteall'` untouched.
|
|
|
|
*g:nuwiki_table_auto_fmt*
|
|
`g:nuwiki_table_auto_fmt` 1
|
|
When 1 (default), the table under the cursor is re-aligned on
|
|
|InsertLeave|. Mirrors vimwiki's `table_auto_fmt` and the Neovim
|
|
`table_auto_fmt` setup option. Set to 0 to disable.
|
|
|
|
*g:nuwiki_mouse_mappings*
|
|
`g:nuwiki_mouse_mappings` 0
|
|
When 1, the Vim path registers mouse keymaps (double-click follows,
|
|
middle-click `:badd`s the link target, etc.). Mirrors
|
|
`mappings.mouse = true` in Neovim.
|
|
|
|
*g:nuwiki_build_from_source*
|
|
`g:nuwiki_build_from_source` 0
|
|
When 1, the install step always builds the server with `cargo` and
|
|
skips the release-asset download.
|
|
|
|
*g:nuwiki_binary_path*
|
|
`g:nuwiki_binary_path`
|
|
Override the auto-discovered server binary path. If set and the
|
|
file is readable, it overrides the `{plugin}/bin/nuwiki-ls` default.
|
|
|
|
==============================================================================
|
|
==============================================================================
|
|
5. COMMANDS *nuwiki-commands*
|
|
|
|
All commands are available in both forms:
|
|
- Canonical form: :Nuwiki*
|
|
- Vimwiki-compatible form: :Vimwiki*
|
|
|
|
Every command listed below is registered buffer-logic on `.wiki` files.
|
|
Only the `:Nuwiki*` form is shown in this document for brevity.
|
|
|
|
|
|
Wiki / navigation ~
|
|
|
|
*:NuwikiIndex*
|
|
:NuwikiIndex [{count}]
|
|
Open wiki N's index page (default: 1). Defined globally, so it works
|
|
from any buffer (not just inside a wiki).
|
|
|
|
*:NuwikiTabIndex*
|
|
:NuwikiTabIndex [{count}]
|
|
Same, in a new tab. Also global.
|
|
|
|
*:NuwikiUISelect*
|
|
:NuwikiUISelect
|
|
Pick a wiki from a list (multi-wiki only). Uses |vim.ui.select| on
|
|
Neovim, |inputlist()| on Vim.
|
|
|
|
*:NuwikiShowVersion*
|
|
:NuwikiShowVersion
|
|
Echo the nuwiki version (`g:nuwiki_version`) and the host editor.
|
|
Also available as `:VimwikiShowVersion`.
|
|
|
|
*:NuwikiVar*
|
|
:NuwikiVar [{key} [{value}]]
|
|
Get/set nuwiki client config. No argument prints the config (Vim:
|
|
every `g:nuwiki_*`; Neovim: the resolved |nuwiki-setup| options); one
|
|
argument prints that key; two or more sets it (server-backed settings
|
|
need a restart to take effect). Also `:VimwikiVar`.
|
|
|
|
*:NuwikiReturn*
|
|
:NuwikiReturn
|
|
Command form of the smart `<CR>` continuation: continue the current
|
|
list item / table row. Mostly used internally; the insert-mode `<CR>`
|
|
mapping does the same. Also `:VimwikiReturn`.
|
|
|
|
*:NuwikiGoto*
|
|
:NuwikiGoto {page}
|
|
Open `{page}.wiki` by name.
|
|
|
|
*:NuwikiFollowLink*
|
|
:NuwikiFollowLink
|
|
Follow the link under the cursor.
|
|
|
|
*:NuwikiSplitLink*
|
|
:NuwikiSplitLink
|
|
*:NuwikiVSplitLink*
|
|
:NuwikiVSplitLink
|
|
*:NuwikiTabnewLink*
|
|
:NuwikiTabnewLink
|
|
Follow the link under the cursor in a horizontal split, vertical
|
|
split, or new tab respectively.
|
|
|
|
*:NuwikiTabDropLink*
|
|
:NuwikiTabDropLink
|
|
Follow the link under the cursor in a tab, reusing an existing tab
|
|
if the target file is already open (otherwise a new tab is created).
|
|
|
|
*:NuwikiGoBackLink*
|
|
:NuwikiGoBackLink
|
|
Jump back to where you followed the link from (via the jumplist,
|
|
|CTRL-O|).
|
|
|
|
*:NuwikiBacklinks*
|
|
:NuwikiBacklinks
|
|
Show all references to the current page.
|
|
|
|
*:NuwikiNextLink*
|
|
:NuwikiNextLink
|
|
*:NuwikiPrevLink*
|
|
:NuwikiPrevLink
|
|
Jump to the next / previous wikilink on the page.
|
|
|
|
*:NuwikiBaddLink*
|
|
:NuwikiBaddLink
|
|
Add the target of the link under the cursor to the buffer list.
|
|
|
|
*:NuwikiRenameFile*
|
|
:NuwikiRenameFile
|
|
Prompt for a new name; rename the current page and rewrite every
|
|
inbound link.
|
|
|
|
*:NuwikiDeleteFile*
|
|
:NuwikiDeleteFile
|
|
Delete the current page and its on-disk file.
|
|
|
|
Diary ~
|
|
|
|
*:NuwikiMakeDiaryNote*
|
|
:NuwikiMakeDiaryNote
|
|
Open today's diary entry. With `diary_frequency = 'weekly'` (or
|
|
`'monthly'` / `'yearly'`) this addresses this week's / this month's
|
|
/ this year's entry instead. The file stems follow:
|
|
|
|
daily YYYY-MM-DD 2026-05-12.wiki
|
|
weekly YYYY-Www 2026-W19.wiki (ISO 8601 week)
|
|
monthly YYYY-MM 2026-05.wiki
|
|
yearly YYYY 2026.wiki
|
|
|
|
*:NuwikiMakeYesterdayDiaryNote*
|
|
:NuwikiMakeYesterdayDiaryNote
|
|
*:NuwikiMakeTomorrowDiaryNote*
|
|
:NuwikiMakeTomorrowDiaryNote
|
|
Step the diary back / forward by one period at the configured
|
|
cadence.
|
|
|
|
*:NuwikiDiaryIndex*
|
|
:NuwikiDiaryIndex
|
|
Open the diary index page.
|
|
|
|
*:NuwikiDiaryGenerateLinks*
|
|
:NuwikiDiaryGenerateLinks
|
|
Rebuild the diary index page from the entries currently on disk.
|
|
|
|
*:NuwikiDiaryNextDay*
|
|
:NuwikiDiaryNextDay
|
|
*:NuwikiDiaryPrevDay*
|
|
:NuwikiDiaryPrevDay
|
|
Walk to the next / previous indexed diary entry at the same cadence
|
|
as the current one.
|
|
|
|
Page generation ~
|
|
|
|
*:NuwikiTOC*
|
|
:NuwikiTOC
|
|
Generate or refresh the table of contents on the current page.
|
|
|
|
*:NuwikiGenerateLinks*
|
|
:NuwikiGenerateLinks
|
|
Insert a flat list of every page in the wiki under the cursor.
|
|
|
|
*:NuwikiCheckLinks*
|
|
:[range]NuwikiCheckLinks
|
|
Send every broken link in the workspace to the |quickfix| list. With a
|
|
range (e.g. `:'<,'>NuwikiCheckLinks`) the report is limited to the current
|
|
buffer's selected lines.
|
|
|
|
*:NuwikiFindOrphans*
|
|
:NuwikiFindOrphans
|
|
List pages with no incoming links in the |quickfix| list.
|
|
|
|
*:NuwikiNormalizeLink*
|
|
:NuwikiNormalizeLink [0|1]
|
|
Turn the word (or, with arg `1`, the visual selection) under the cursor
|
|
into a wikilink. Backs the `+` mapping.
|
|
|
|
Tags ~
|
|
|
|
*:NuwikiSearchTags*
|
|
:NuwikiSearchTags {tag}
|
|
Quickfix listing every `:tag:` occurrence.
|
|
|
|
*:NuwikiGenerateTagLinks*
|
|
:NuwikiGenerateTagLinks [tag]
|
|
Insert a section linking every page that has `<tag>`. With no
|
|
argument, generates a section per tag found in the workspace.
|
|
|
|
*:NuwikiRebuildTags*
|
|
:NuwikiRebuildTags[!]
|
|
Re-index the current wiki. With `!`, re-index every configured wiki.
|
|
|
|
HTML export ~
|
|
|
|
*:Nuwiki2HTML*
|
|
:Nuwiki2HTML
|
|
Render the current page to HTML.
|
|
|
|
*:Nuwiki2HTMLBrowse*
|
|
:Nuwiki2HTMLBrowse
|
|
Render the current page and open it in the default browser.
|
|
|
|
*:NuwikiAll2HTML*
|
|
:NuwikiAll2HTML[!]
|
|
Export every page in the wiki. `!` forces a full rebuild; otherwise
|
|
only out-of-date pages are re-rendered.
|
|
|
|
*:NuwikiRss*
|
|
:NuwikiRss
|
|
Write `rss.xml` summarising recent diary entries.
|
|
|
|
Lists, tasks & tables ~
|
|
|
|
*:NuwikiNextTask*
|
|
:NuwikiNextTask
|
|
Jump to the next unfinished task in the buffer.
|
|
|
|
*:NuwikiListToggle*
|
|
:NuwikiListToggle
|
|
Toggle a checkbox on the current item, adding `[ ]` if it has none.
|
|
|
|
*:NuwikiToggleListItem*
|
|
:[range]NuwikiToggleListItem
|
|
Toggle the checkbox under the cursor. With a range, every item in the
|
|
selection.
|
|
|
|
*:NuwikiToggleRejected*
|
|
:NuwikiToggleRejected
|
|
Toggle the rejected marker `[-]` on the current item.
|
|
|
|
*:NuwikiIncrementListItem* *:NuwikiDecrementListItem*
|
|
:[range]NuwikiIncrementListItem
|
|
:[range]NuwikiDecrementListItem
|
|
Cycle the current item's list marker to the next / previous symbol.
|
|
With a range, every item in the selection.
|
|
|
|
*:NuwikiChangeSymbol* *:NuwikiChangeSymbolInList*
|
|
:NuwikiChangeSymbol {sym}
|
|
:NuwikiChangeSymbolInList {sym}
|
|
Set the current item's marker to `{sym}` — or every item in the list,
|
|
for the `InList` form.
|
|
|
|
*:NuwikiListChangeLvl*
|
|
:NuwikiListChangeLvl [increase|decrease]
|
|
Indent (`increase`) or dedent (`decrease`) the current list item.
|
|
|
|
*:NuwikiRemoveDone*
|
|
:NuwikiRemoveDone[!]
|
|
Remove every completed item from the current list; with `!`, from the
|
|
whole buffer.
|
|
|
|
*:NuwikiRemoveCheckbox* *:NuwikiRemoveCheckboxInList*
|
|
:[range]NuwikiRemoveCheckbox
|
|
:NuwikiRemoveCheckboxInList
|
|
Strip the checkbox from the current item (or the range), or from every
|
|
item in the current list for the `InList` form.
|
|
|
|
*:NuwikiRenumberList* *:NuwikiRenumberAllLists*
|
|
:NuwikiRenumberList
|
|
:NuwikiRenumberAllLists
|
|
Renumber the current ordered list, or every ordered list in the buffer.
|
|
|
|
*:NuwikiTable*
|
|
:NuwikiTable {cols} [rows]
|
|
Insert a table with `{cols}` columns (and optional `[rows]`) at the cursor.
|
|
|
|
*:NuwikiTableAlign*
|
|
:NuwikiTableAlign
|
|
Re-align the current table's columns.
|
|
|
|
*:NuwikiTableMoveColumnLeft* *:NuwikiTableMoveColumnRight*
|
|
:NuwikiTableMoveColumnLeft
|
|
:NuwikiTableMoveColumnRight
|
|
Move the table column under the cursor left / right.
|
|
|
|
Other ~
|
|
|
|
*:NuwikiColorize*
|
|
:[range]NuwikiColorize {color}
|
|
Wrap the word (or the visual selection) under the cursor in a coloured
|
|
`<span>`. `{color}` may be a `color_dic` name or a literal CSS colour.
|
|
|
|
*:NuwikiPasteLink* *:NuwikiPasteUrl*
|
|
:NuwikiPasteLink
|
|
:NuwikiPasteUrl
|
|
Paste the clipboard contents as a wikilink, or as a raw URL.
|
|
|
|
*:NuwikiCatUrl*
|
|
:NuwikiCatUrl
|
|
Echo the `file://` URL of the current page's HTML export.
|
|
|
|
*:NuwikiInstall*
|
|
:NuwikiInstall
|
|
Install (or re-install) the `nuwiki-ls` binary into the plugin's
|
|
`bin/` directory. Equivalent to running the build hook by hand.
|
|
|
|
==============================================================================
|
|
6. KEYMAPS *nuwiki-keymaps*
|
|
|
|
Every keymap is buffer-local. Disable the whole layer via
|
|
`mappings.enabled = false` in Neovim, or `let g:nuwiki_no_default_mappings
|
|
= 1` in Vim. Drop a single group via `mappings.<group> = false` in Neovim,
|
|
or `let g:nuwiki_no_<group>_mappings = 1` in Vim (see
|
|
|g:nuwiki_no_links_mappings| for the group list).
|
|
|
|
Links (normal mode) ~
|
|
|
|
<CR> Smart follow — inside `[[…]]` jumps; on a bare word
|
|
wraps as `[[word]]` (second <CR> follows the link).
|
|
<S-CR> Follow in a horizontal split.
|
|
<C-CR> Follow in a vertical split.
|
|
<C-S-CR> Follow in a tab, reusing an existing tab if the file is
|
|
already open. `<D-CR>` (macOS Cmd) is an alias.
|
|
<M-CR> Add the link target to the buffer list (`:badd`, no jump).
|
|
<BS> Jump back (`<C-o>`).
|
|
<Tab> Next wikilink on or after the cursor.
|
|
<S-Tab> Previous wikilink.
|
|
+ Wrap word (or visual selection) as `[[word]]`. No follow.
|
|
|
|
Lists (normal mode) ~
|
|
|
|
<C-Space> Toggle the checkbox under the cursor. Also bound to <C-@>
|
|
and <Nul> to cover terminal byte differences.
|
|
gln Cycle the checkbox state forward.
|
|
glp Cycle the checkbox state backward.
|
|
glx Toggle the rejected marker `[-]`.
|
|
gnt Jump to the next unfinished task.
|
|
glh Dedent the current list item.
|
|
gll Indent the current list item.
|
|
gLh Dedent the item including its sublist. (alias: gLH)
|
|
gLl Indent the item including its sublist. (alias: gLL)
|
|
glr Renumber the current ordered list.
|
|
gLr Renumber every ordered list in the buffer. (alias: gLR)
|
|
gl<sym> Set the current item's marker to <sym>, where <sym> is one
|
|
of `-` `*` `#` `1` (1.) `i` (i)) `I` (I)) `a` (a)) `A` (A)).
|
|
For `1)` use `:NuwikiChangeSymbol 1)` (no single-key form).
|
|
gL<sym> Set every item in the list to <sym> (same symbol keys).
|
|
gl Remove the checkbox from the current item, keeping its text.
|
|
gL Remove the checkbox from every item in the current list.
|
|
Bare `gl`/`gL` share the `gl...` prefix above, so (like
|
|
upstream vimwiki) they fire only after 'timeoutlen'; type a
|
|
suffix such as `gln`/`gl*` quickly to reach the prefixed maps.
|
|
Removing done items is command-only: `:NuwikiRemoveDone`
|
|
(current list) / `:NuwikiRemoveDone!` (whole buffer).
|
|
o Open a new line and continue the list marker (preserves
|
|
any checkbox).
|
|
O Same, opening above the current line.
|
|
|
|
Headers ~
|
|
|
|
= Increase the heading level under the cursor.
|
|
- Decrease the heading level.
|
|
]] Next heading (any level).
|
|
[[ Previous heading.
|
|
]= Next sibling heading.
|
|
[= Previous sibling heading.
|
|
]u Jump to the parent heading.
|
|
[u Same — alternate binding.
|
|
|
|
Tables (normal mode) ~
|
|
|
|
gqq Align the table under the cursor. Also `gq1`, `gww`, `gw1`.
|
|
<A-Left> Move the column under the cursor left.
|
|
<A-Right> Move the column under the cursor right.
|
|
|
|
Wiki / diary / export ~
|
|
|
|
The `<Leader>w` prefix below is the default |map_prefix| / |g:nuwiki_map_prefix|;
|
|
set that option to relocate the whole family.
|
|
|
|
<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 Today.
|
|
<Leader>w<Leader>y Yesterday.
|
|
<Leader>w<Leader>t Today, in a new tab.
|
|
<Leader>w<Leader>m Tomorrow.
|
|
<Leader>w<Leader>i Rebuild the diary index page.
|
|
<Leader>wn Goto page (prompts for name).
|
|
<Leader>wd Delete the current page.
|
|
<Leader>wr Rename the current page.
|
|
<Leader>wh Export the current page to HTML.
|
|
<Leader>whh Export and open in the browser.
|
|
<Leader>wha Export every page.
|
|
<Leader>wc Wrap word / selection in a colour span.
|
|
<C-Down> Next diary entry.
|
|
<C-Up> Previous diary entry.
|
|
|
|
Mouse (opt-in via |g:nuwiki_mouse_mappings|) ~
|
|
|
|
<2-LeftMouse> Follow the link clicked.
|
|
<S-2-LeftMouse> Follow in a horizontal split.
|
|
<C-2-LeftMouse> Follow in a vertical split.
|
|
<MiddleMouse> Add the link target to the buffer list.
|
|
<RightMouse> Jump back (`<C-o>`).
|
|
|
|
==============================================================================
|
|
7. TEXT OBJECTS *nuwiki-text-objects*
|
|
|
|
Operator-pending + visual. Disable via `mappings.text_objects = false`.
|
|
|
|
ah A heading section — the heading line and everything up to
|
|
the next heading at any level.
|
|
ih Same, but excluding the heading line itself.
|
|
aH A heading section plus every subheading underneath — stops
|
|
at the next heading of same-or-shallower level.
|
|
iH Same, but excluding the heading line.
|
|
al The list item under the cursor.
|
|
il Same, but excluding the marker / checkbox prefix.
|
|
a\ The table cell under the cursor (includes the trailing `|`).
|
|
i\ Same, content only — no surrounding `|`s or padding.
|
|
ac The table column under the cursor (includes the header
|
|
separator row).
|
|
ic Same, content cells only.
|
|
|
|
==============================================================================
|
|
8. INSERT-MODE BINDINGS *nuwiki-insert-mode*
|
|
|
|
Smart return ~
|
|
|
|
`<CR>` is bound to a smart helper that does the right thing depending
|
|
on context:
|
|
|
|
* On a list item with content — continue the list with the same marker
|
|
on a new line. Preserves a leading checkbox if present.
|
|
* On an empty list item (marker only) — clear the marker and break
|
|
out of the list with a plain newline.
|
|
* Inside a `|…|` table row — insert a fresh empty row below with the
|
|
same column count; cursor lands inside the first cell.
|
|
* Otherwise — plain `<CR>`.
|
|
|
|
Insert `<S-CR>` continues a list item as a *multiline* item: a new line
|
|
with no marker, indented to align under the item's text (or a plain
|
|
`<CR>` when not on a list item). Mirrors vimwiki's `<S-CR>`.
|
|
|
|
Table cell navigation ~
|
|
|
|
<Tab> Jump to the next cell. Past the last cell, insert a fresh
|
|
row below and land in its first cell.
|
|
<S-Tab> Jump to the previous cell.
|
|
|
|
Outside a table row both pass through to their default insert-mode
|
|
behaviour (literal tab / shift-tab).
|
|
|
|
List editing ~
|
|
|
|
<C-D> Dedent the current list item.
|
|
<C-T> Indent the current list item.
|
|
<C-L><C-J> Cycle the marker forward through the canonical run:
|
|
`-` → `*` → `#` → `1.` → `1)` → `a)` → `A)` → `i)` → `I)`
|
|
<C-L><C-K> Cycle the marker backward.
|
|
<C-L><C-M> Toggle the checkbox on the current item, or insert
|
|
`[ ]` after the marker when there isn't one.
|
|
|
|
==============================================================================
|
|
9. DIARY *nuwiki-diary*
|
|
|
|
The diary holds dated entries under `<wiki_root>/<diary_rel_path>/` —
|
|
`diary/` by default.
|
|
|
|
Frequencies ~
|
|
|
|
The `diary_frequency` per-wiki option controls the cadence:
|
|
|
|
daily YYYY-MM-DD e.g. `2026-05-12.wiki` (default)
|
|
weekly YYYY-Www ISO 8601 week, e.g. `2026-W19.wiki`
|
|
monthly YYYY-MM e.g. `2026-05.wiki`
|
|
yearly YYYY e.g. `2026.wiki`
|
|
|
|
For weekly diaries, `diary_weekly_style` chooses the file name: the default
|
|
`'iso'` uses the ISO-week label above (always Monday-based); `'date'` (a.k.a.
|
|
`'vimwiki'`) names the file after the week-start day's date — e.g. with
|
|
`diary_start_week_day = 'monday'`, the week of 2026-05-27 is `2026-05-25.wiki`
|
|
— matching upstream vimwiki. `diary_start_week_day` (`'monday'`..`'sunday'`)
|
|
only applies in `'date'` mode.
|
|
|
|
`:NuwikiMakeDiaryNote` opens the entry for the current period at the
|
|
configured cadence; the yesterday / tomorrow commands step back and
|
|
forward by one period. `<C-Down>` / `<C-Up>` walk between indexed
|
|
entries of the same flavour as the one under the cursor — so on a
|
|
weekly page, navigation stays weekly.
|
|
|
|
Index ~
|
|
|
|
`:NuwikiDiaryGenerateLinks` rebuilds the diary index page (`diary.wiki`
|
|
by default) with a chronological list of every entry on disk, grouped
|
|
by year / month. The page name is set by `diary_index`; the heading is
|
|
set by `diary_header`.
|
|
|
|
==============================================================================
|
|
10. TABLES *nuwiki-tables*
|
|
|
|
Tables use vimwiki's pipe syntax: >
|
|
|
|
| Name | Score |
|
|
|-------|-------|
|
|
| Alice | 97 |
|
|
| Bob | 72 |
|
|
|
|
<Alignment markers on the header separator row follow Markdown
|
|
conventions:
|
|
|
|
`|:---|` left-align
|
|
`|---:|` right-align
|
|
`|:---:|` centre-align
|
|
|
|
A cell containing just `>` merges with the cell to its left (colspan);
|
|
a cell containing just `\/` merges with the cell directly above
|
|
(rowspan). The HTML renderer emits proper `colspan="N"` / `rowspan="N"`
|
|
attributes plus `style="text-align: …;"` per cell when alignment is
|
|
specified.
|
|
|
|
See |nuwiki-keymaps| for the table-editing shortcuts (alignment,
|
|
column moves, cell navigation, new-row insertion).
|
|
|
|
==============================================================================
|
|
11. HTML EXPORT *nuwiki-html*
|
|
|
|
`:Nuwiki2HTML` renders the current page; `:Nuwiki2HTMLBrowse` opens
|
|
the result in the default browser; `:NuwikiAll2HTML` exports every
|
|
page (incremental by default; `!` forces a full rebuild).
|
|
|
|
Per-wiki knobs:
|
|
|
|
`html_path` Output directory (created if missing).
|
|
`template_path` Where to find `<name>.tpl` files.
|
|
`template_default` Default template name (without extension).
|
|
`template_ext` Template file extension (default `.tpl`).
|
|
`css_name` CSS file copied into `html_path`.
|
|
`auto_export` When `true`, exports on every save.
|
|
`exclude_files` Glob patterns excluded from export.
|
|
|
|
Templates may include `{title}`, `{rootpath}`, `{content}`, `{css}`,
|
|
`{date}` placeholders. RSS for the diary is written by `:NuwikiRss`.
|
|
|
|
==============================================================================
|
|
12. FOLDING *nuwiki-folding*
|
|
|
|
Folds follow the heading outline: each `= H1 =` opens a level-1 fold,
|
|
each `== H2 ==` opens a level-2 fold, etc. Folds close at the next
|
|
heading of same-or-shallower level.
|
|
|
|
Neovim picks between two providers based on the `folding` setup option:
|
|
|
|
`'lsp'` Server-driven `foldingRange` (Neovim 0.11+ wires it
|
|
automatically; the editor falls back to the regex variant
|
|
if the server isn't yet attached).
|
|
`'expr'` Regex `foldexpr` over `getline()` — no server roundtrip.
|
|
`'off'` No folding setup.
|
|
|
|
Vim users get the regex variant via `nuwiki#folding#expr()` unless
|
|
|g:nuwiki_no_folding| is set.
|
|
|
|
==============================================================================
|
|
13. HEALTH CHECK *nuwiki-health*
|
|
|
|
*:checkhealth-nuwiki*
|
|
Neovim users can run: >
|
|
|
|
:checkhealth nuwiki
|
|
|
|
<This reports:
|
|
|
|
* Whether the binary exists and responds to `--version`.
|
|
* Whether `wiki_root` exists.
|
|
* Whether the `.wiki` filetype is registered (`vimwiki`).
|
|
* Whether an LSP client is currently attached.
|
|
* Which `executeCommand` handlers the server advertised.
|
|
|
|
Vim users without `:checkhealth` can run `:LspStatus` (vim-lsp) or
|
|
`:CocCommand workspace.showOutput` (coc.nvim).
|
|
|
|
==============================================================================
|
|
14. MIGRATING FROM VIMWIKI *nuwiki-migrating*
|
|
|
|
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
|
|
`:NuwikiCheckLinks` result until the background index completes;
|
|
subsequent runs are instant.
|
|
|
|
vim:tw=78:ts=8:ft=help:norl:
|