gffranco
e6f400b370
The g:vimwiki_* drop-in was Vim-only: the Lua client read only setup() opts and g:nuwiki_wikis, so swapping the vimwiki plugin for nuwiki under lazy.nvim left the existing vim.g.vimwiki_list ignored and nuwiki pointed at the default ~/vimwiki. Mirror autoload/nuwiki/config.vim on the Lua side: config.lua now owns a single resolver (M.wikis / M.scalar_globals) that resolves setup() wikis → g:nuwiki_wikis → g:vimwiki_list (translating path->root, path_html->html_path, template_*, ext->file_extension, …) and folds the global scalar defaults (g:vimwiki_* then g:nuwiki_* then explicit setup() values; built-in defaults excluded). lsp.lua (payload) and wiki_cfg/wiki_list (buffer commands) both route through it, so the server and <Leader>ww agree on the wikis. Extends test-global-shorthand (15 checks) with the vimwiki_list drop-in + buffer-command resolution + native-wins cases. Config-parity goldens and keymap harnesses green on both clients. README + known-issues updated (drop-in is now Vim & Neovim). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
7.5 KiB
Known Issues & Divergences from vimwiki
nuwiki is an LSP-backed reimplementation of vimwiki, not a fork of the original VimL plugin. It targets behavioral parity with vimwiki, but a handful of upstream options and behaviors are implemented differently — or intentionally not at all — because of that architecture.
This page is the single source of truth for how nuwiki differs from vimwiki. Everything here is either a deliberate design choice or a tracked future task; none of it is an accidental bug.
If you hit a behavior that isn't listed here and doesn't match vimwiki, please file it — that's a real bug.
Deferred (planned, not yet implemented)
These are genuine feature gaps that we intend to close, grouped because they ship together.
Markdown generated-content
The buffer-side generators — TOC (:VimwikiTOC), generated links
(:VimwikiGenerateLinks), the tags index (:VimwikiGenerateTagLinks), and the
diary index — always emit vimwiki markup (= Heading =), regardless of the
wiki's syntax. Markdown wikis therefore get vimwiki-syntax generated sections.
Dependent on markdown-syntax generation, and deferred until it lands:
- markdown-style heading generation in those generators (
# Heading). markdown_header_style— blank lines after a generated markdown header (no markdown header exists to attach it to yet).markdown_link_ext— append the file extension in generated markdown links.
Hand-authored markdown content renders fine; only the generated sections are affected.
Behavioral divergences (by design)
These upstream options have no nuwiki equivalent, because the LSP server provides the capability a different way. They will not be re-implemented as-is.
Highlighting & display
| vimwiki option | nuwiki behavior |
|---|---|
maxhi |
Broken/existence-based link highlighting is provided by LSP diagnostics instead (severity is configurable via diagnostic.link_severity). |
conceallevel, conceal_onechar_markers, other conceal* |
Replaced by LSP semantic tokens; there is no conceal layer to configure. |
Syntax detection
| vimwiki option | nuwiki behavior |
|---|---|
nested_syntaxes / automatic_nested_syntaxes |
Code-fence languages are auto-detected from the fence tag (```python); always on, no toggle. |
ext2syntax |
Syntax is chosen by file extension / the per-wiki syntax key automatically. |
global_ext |
The configured wiki extension(s) always map to the vimwiki filetype regardless of location; there is no per-wiki "only inside the root" toggle (effectively always on). |
syntax default name |
nuwiki defaults the per-wiki syntax to vimwiki where upstream defaults to default — a naming difference only, not behavioral. |
Configuration mechanism
| vimwiki option | nuwiki behavior |
|---|---|
folding (string) |
Replaced by folding = 'lsp' | 'expr' | 'off', backed by the LSP foldingRange provider. |
key_mappings (dict) |
Replaced by the Lua mappings.<group> table and the g:nuwiki_no_<group>_mappings globals. |
Tags
| vimwiki option | nuwiki behavior |
|---|---|
auto_tags |
Upstream maintains an on-disk tag metadata file on save. nuwiki has no such file: the server re-indexes tags on every change, so tag search / jump / completion are always fresh. The configurable on-save piece (regenerating the in-buffer links section) is auto_generate_tags. |
Mappings
| vimwiki option | nuwiki behavior |
|---|---|
Mouse maps (<2-LeftMouse>, <MiddleMouse>, …) |
Upstream binds these unconditionally; nuwiki ships them opt-in via mappings.mouse / g:nuwiki_mouse_mappings. |
Value-semantics differences
| vimwiki option | nuwiki behavior |
|---|---|
list_margin (negative) |
Upstream resolves a negative value to the buffer's 'shiftwidth'. The server can't observe 'shiftwidth', so negative values collapse to zero leading indent on generated bullets. Set a non-negative number for a fixed indent. |
diary_caption_level = -1 |
Accepted (the field is deserializable), but clamps to 0. nuwiki builds the diary index tree from dates, so upstream's -1 = "no per-page captions" semantic doesn't apply. |
Vim/Win shims & syntax internals (not applicable)
CJK_length, listing_hl*, schemes_*, w32_dir_enc, menu, rx_todo,
tag_format — these are syntax internals, menu definitions, or Vim/Windows
shims with no role in an LSP-backed implementation.
Default-location differences
Where you don't set a path explicitly, nuwiki derives a different default location than upstream — by design, so each wiki is root-relative and self-contained. You can set any of these explicitly to match upstream exactly.
| Key | nuwiki default | upstream default |
|---|---|---|
html_path |
<root>/_html |
sibling <wikidir>_html/ |
template_path |
<root>/_templates |
global ~/vimwiki/templates/ |
diary_rel_path |
diary |
diary/ (trailing slash only — paths join identically, so behavior matches) |
Internal deferrals (non-parity)
These are not vimwiki differences — they're known low-priority optimizations on cold code paths, recorded so they aren't rediscovered as "bugs." All are correct as-is; the deferral is a deliberate risk/reward call.
- RSS
render_entry_bodyreads from disk. It re-reads and re-parses each diary entry from disk rather than reusing an open buffer. This is the correct source of truth for an export artifact — switching to unsaved buffer text would change semantics, not just performance. push_level_edit_for_linescans from offset 0. The list-level change (gl/gL) computes each line's start offset by scanning from the document start. It's an interactive single-keypress path over small inputs, and the offset-arithmetic rewrite carries more regression risk than the saved time is worth.- Diary next/prev neighbor scan.
:VimwikiDiaryNextDay/PrevDayrebuild and sort the entry list to find one neighbor. Same reasoning — cold path, small input.
Notes
- Upstream
g:vimwiki_listconfig (Vim & Neovim). When you haven't configured nuwiki natively, both clients read your upstreamg:vimwiki_list+g:vimwiki_*globals and translate them into nuwiki's schema (per-wikipath/path_html/template_*/auto_export, plus globalstoc_header,toc_header_level,html_header_numbering,html_header_numbering_sym,links_space_char,list_margin).g:nuwiki_*/setup()config always wins. Globals nuwiki doesn't model (e.g.automatic_nested_syntaxes) are ignored — see the divergence list above. On Neovim this means swapping thevimwikiplugin for nuwiki under lazy.nvim works with your existingvim.g.vimwiki_listuntouched (callrequire('nuwiki').setup()with no args). - Third-party plugin compatibility. A shim at
autoload/vimwiki/vars.vimexposes the subset ofvimwiki#vars#get_wikilocalthat plugins like vimwiki-sync and vim-zettel call (path,ext/extension,syntax,is_temporary_wiki), resolved from nuwiki's own config — including the correct per-wiki values in a multi-wiki setup. Add keys there if a plugin you use needs more. - Additive commands. nuwiki adds some commands with no upstream equivalent
(e.g.
:NuwikiFindOrphans). These are additions, not divergences.