gffranco
94cb58064d
:NuwikiTOC inserted a new table of contents at the top of the file. It now inserts at the cursor line instead, so you can place the TOC where you want it (a blank line separates it from preceding text). An existing TOC is still refreshed in place, and auto_toc-on-save is unaffected. The Vim/Lua clients send the 0-based cursor line with nuwiki.toc.generate; the server threads it into toc_edit (clamped to the document) and falls back to the top of the file when absent. toc_rebuild_edit passes None. Tests: toc_edit_inserts_at_cursor_line + toc_edit_cursor_line_clamped_and_existing_replaced_in_place. 575 passed, clippy clean, keymap harnesses green. Doc updated. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
963 lines
42 KiB
Plaintext
963 lines
42 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`.
|
|
|
|
*g:nuwiki_auto_chdir*
|
|
`auto_chdir` false
|
|
`:lcd` into the owning wiki's root when a wiki buffer becomes current.
|
|
Mirrors vimwiki's `auto_chdir`. Vim users set |g:nuwiki_auto_chdir|.
|
|
|
|
*g:nuwiki_auto_header*
|
|
`auto_header` false
|
|
Insert a level-1 header derived from the filename on new (empty) wiki
|
|
pages. Honours `links_space_char` (so `My_Page.wiki` → `= My Page =`).
|
|
Mirrors vimwiki's `auto_header`. Vim users set |g:nuwiki_auto_header|.
|
|
|
|
*g:nuwiki_no_calendar*
|
|
`use_calendar` true
|
|
When true (default), wire up calendar-vim integration if it is on the
|
|
runtimepath (`g:calendar_action` / `g:calendar_sign`). Set to false, or
|
|
define |g:nuwiki_no_calendar| before setup(), to opt out.
|
|
|
|
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'`
|
|
`diary_months` English month names — month-number → display name
|
|
used in the diary index headings.
|
|
`create_link` `true` — create the target page when following a link
|
|
to a missing page; `false` makes the follow a no-op.
|
|
`dir_link` `''` — index stem opened when following a link to a
|
|
directory (e.g. `'index'`); empty opens the directory.
|
|
`bullet_types` `['-', '*', '#']` — unordered-bullet glyphs for this
|
|
wiki; drives `cycle_bullets`.
|
|
`cycle_bullets` `false` — rotate an unordered item's glyph through
|
|
`bullet_types` as it is indented/dedented.
|
|
`generated_links_caption` `false` — emit `[[page|Heading]]` (first heading as
|
|
caption) from `:VimwikiGenerateLinks`.
|
|
`toc_link_format` `0` — `0` = `[[#anchor|title]]` (with description);
|
|
`1` = `[[#anchor]]` (anchor only).
|
|
`table_reduce_last_col` `false` — don't pad the last table column to fill;
|
|
keep it at its minimum width.
|
|
`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`.
|
|
`color_tag_template` `'<span style="__STYLE__">__CONTENT__</span>'` — HTML
|
|
emitted for a `color_dic` colour span. `__STYLE__` →
|
|
`color:<css>`, `__CONTENT__` → the rendered inner HTML.
|
|
`valid_html_tags` `'b,i,s,u,sub,sup,kbd,br,hr,div,center,strong,em'` —
|
|
comma-separated inline HTML tags passed through export
|
|
unescaped (`span` is always allowed for colour spans).
|
|
`emoji_enable` `true` — substitute `:alias:` emoji shortcodes with
|
|
their glyph during HTML export.
|
|
`text_ignore_newline` `true` — a single newline inside a paragraph renders
|
|
as a space in HTML; `false` emits `<br>`.
|
|
`list_ignore_newline` `true` — a single newline inside a list item renders
|
|
as a space in HTML; `false` emits `<br>`.
|
|
`rss_name` `'rss.xml'` — filename of the generated diary RSS feed,
|
|
relative to `html_path`.
|
|
`rss_max_items` `10` — cap on the number of diary items in the RSS feed.
|
|
`user_htmls` `{}` — basenames of HTML files with no wiki source that
|
|
`:VimwikiAll2HTML` must not prune.
|
|
`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 generated list bullet (TOC /
|
|
generated links). `-1` means "no extra margin": the
|
|
server can't read the editor's `shiftwidth`, so it
|
|
clamps negative values to `0`. Set a non-negative
|
|
number to force a fixed indent.
|
|
`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. A new TOC
|
|
is inserted at the cursor line; an existing one is refreshed in place.
|
|
|
|
*: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:
|