nuwiki/development/vimwiki-gap.md

vimwiki → nuwiki Parity Gaps

Tracking document for closing the gap between nuwiki and the original vimwiki plugin across configuration, commands, and key mappings.

Source of truth for upstream: vimwiki master — autoload/vimwiki/vars.vim (option defaults), plugin/vimwiki.vim + ftplugin/vimwiki.vim (commands/mappings), doc/vimwiki.txt (prose).

Audited 2026-05-31. Check items off as they land. Each row cites the nuwiki fix site.

---

P1 — Core workflow gaps (fix first)

• Vim client split/tab link-follow commands — VimwikiSplitLink, VimwikiVSplitLink, VimwikiGoBackLink, VimwikiTabnewLink, VimwikiTabDropLink exist only in the Neovim branch. Vim users lose split-window link following and back-navigation. Fix: ftplugin/vimwiki.vim (Vim branch) — commands added + :Nuwiki* aliases; follow_link_drop() helper in autoload/nuwiki/commands.vim; true :tab drop tab-reuse wired in both clients (lua/nuwiki/commands.lua open_uri 'tabdrop' case); <C-S-CR> repointed to tab-drop.
• gl<symbol> change-symbol mappings — upstream's one-key bullet/number symbol change (gl* gl# gl- gl1 gla gli … plus gL…) has no nuwiki keymap; only :…ChangeSymbol* commands exist. Fix: added normal-mode gl{-,*,#,1,i,I,a,A} (item) + gL… (whole list) in lua/nuwiki/keymaps.lua lists group and ftplugin/vimwiki.vim Vim-branch lists block, wired to the existing list_change_symbol. 1) stays command-only (upstream shadows it with 1.); normal-mode only (server acts on cursor item / whole list, not a visual range).
• gl<Space> / gL<Space> semantics diverge — upstream = remove checkbox from item / list siblings; nuwiki rebound to remove done items. Same keys, different effect (parity trap). Fix: bound bare gl/gL to remove-checkbox-item / -in-list for exact upstream parity (lua/nuwiki/keymaps.lua lists block, ftplugin/vimwiki.vim Vim-branch lists block); they share the gl… prefix so they fire after timeoutlen, just like upstream. Remove-done is now command-only: :NuwikiRemoveDone (current list) gained a -bang so :NuwikiRemoveDone! reaches the whole-buffer sweep that gL<Space> previously held (the only prior entry point). Normal-mode only.

Regressions (reported by users — verify, then fix)

• <CR> link-follow opens a new tab instead of reusing the current window — pressing <CR> on a link used to open the target in the same tab/window the user was browsing in (upstream behavior). It now opens a new tab and switches to it. Reported on Vim 9.x + Dein. Investigation so far: the nuwiki <CR> path is unchanged by the recent P1 #1/#2/#3 work — git blame shows the <CR> map (ftplugin/vimwiki.vim Vim branch :206, Neovim branch lua/nuwiki/keymaps.lua:161) and the follow_link_or_create → jump-definition chain were not touched; only <C-S-CR> was repointed to follow_link_drop() in f65d861. Both client jump paths open in the current window by default (vim.lsp.buf.definition() with no opts; Vim s:jump_definition() → LspDefinition, autoload/nuwiki/commands.vim:73), so the new-tab behavior is not coming from nuwiki's own placement logic as written. Rule out first (env, per memory): a stale dein copy of the plugin (bin/nuwiki-ls + copied ftplugin) and a double rtp entry where the upstream vimwiki bundle is still loaded alongside nuwiki — either can shadow the <CR> map or pull in upstream/LspDefinition --tab-style behavior. Recache dein + rebuild + restart LSP and confirm only nuwiki's ftplugin is active before treating this as a nuwiki code bug. Suspected sites if it reproduces clean: vim-lsp's definition-open default (Vim) and the vim.lsp.buf.definition() handler (Neovim) — pin which <CR> press (bare-word wrap vs. existing-link follow) triggers the tab and whether the server's definition response shape steers placement.

P2 — Moderate (real users hit these)

• <Leader>w<Leader>t collision — upstream = today-in-new-tab; nuwiki = tomorrow's diary. Fix: lua/nuwiki/keymaps.lua, ftplugin/vimwiki.vim.
• Generated-section captions hardcoded — toc_header / toc_header_level, links_header, tags_header (+levels). Fix: crates/nuwiki-lsp/src/config.rs + server TOC/generate renderers.
• On-save autoregen family — auto_diary_index, auto_generate_links, auto_generate_tags, auto_tags (only auto_toc / auto_export exist). Fix: config.rs RawWiki/WikiConfig + the didSave path.
• listsym_rejected — rejected glyph - is hardcoded. Fix: config.rs WikiConfig.
• custom_wiki2html (+_args) and base_url — external HTML converter hook + export URL prefix. Fix: config.rs HtmlConfig.
• map_prefix — <Leader>w hardcoded across the map layer. Fix: plugin/nuwiki.vim, lua/nuwiki/keymaps.lua, ftplugin/vimwiki.vim.
• <M-CR> badd-link — missing (badd is mouse-only via <MiddleMouse> / :VimwikiBaddLink). Fix: lua/nuwiki/keymaps.lua, ftplugin/vimwiki.vim.
• diary_caption_level default divergence — nuwiki 1 vs vimwiki 0. Fix: config.rs:291 (and defaults in lua/nuwiki/config.lua).
• diary_start_week_day — wrongly removed in c63ec67. The removal treated it as a server concern and hardwired the weekly diary to ISO-Monday (crates/nuwiki-core/src/date.rs monday_of_iso_week), but choosing which weekday the diary week begins on is a client-side concern and it matters for parity — non-Monday users lose the upstream option entirely. Fix: restore the config key client-side (lua/nuwiki/config.lua) and thread the week-start through to the diary date logic instead of hardcoding Monday.

P3 — Niche / low impact

Commands

• VimwikiVar — config-var get/set introspection. Fix: plugin/nuwiki.vim.
• VimwikiShowVersion — print version (trivial). Fix: plugin/nuwiki.vim.
• VimwikiReturn — no Ex-command (mapping-driven only). Fix: ftplugin/vimwiki.vim.
• VimwikiTableAlignQ vs AlignW collapsed to one table_align — gqq (align) vs gww (align w/o resize) distinction lost.
• VimwikiTable is -nargs=1 vs upstream -nargs=* (can't pass cols+rows).
• VimwikiListChangeLvl is -nargs=? vs upstream -range -nargs=+.
• VimwikiRebuildTags lacks -bang ("rebuild all" variant).
• :VimwikiSearch / VWS uses lvimgrep, not vimwiki's search engine.
• VimwikiIndex family is buffer-local in nuwiki (upstream defines globally in plugin/); only :…UISelect is a global entry point.
• VimwikiColorize / NuwikiColorize drop their argument in the Neovim branch — both are -nargs=1, but the Neovim defs call colorize() with no <q-args> (ftplugin/vimwiki.vim:445,517) while the Vim branch passes it (:106,177). The color name is silently ignored under Neovim (real bug, not just parity). Fix: ftplugin/vimwiki.vim Neovim branch.
• VimwikiTableMoveColumn{Left,Right} dispatch to different backing names per client — Vim branch → table_move_left/right; Neovim branch → table_move_column_left/right. Harmless today (each name exists in its own impl) but a divergence to converge.
• NuwikiTabIndex lacks -count in the Neovim branch (:452) while its siblings (VimwikiTabIndex, NuwikiIndex, and the Vim-branch NuwikiTabIndex) all carry it — vim.v.count is still read, so a count is honored inconsistently.
• VimwikiToggleListItem / Increment / DecrementListItem lack -range (both branches) vs upstream's -range (:350) — no visual-range checkbox toggle / symbol cycle.

Config

• auto_header — auto H1-from-filename on new page (server-side).
• create_link — toggle to suppress link-target creation.
• dir_link — index file to open when following a directory link.
• auto_chdir — :cd into wiki root on open (client-side).
• bullet_types / cycle_bullets — custom bullet glyphs + wrap-around.
• commentstring ('%%%s') — comment toggling/text-objects.
• color_tag_template — color_dic present; template regex missing.
• rss_max_items / rss_name — :Rss output hardcoded. Fix: HtmlConfig.
• emoji_enable — emoji substitution.
• html_header_numbering (+_sym) — numbered HTML headers.
• valid_html_tags — allowed inline HTML tags in export.
• generated_links_caption, toc_link_format, markdown_link_ext.
• list_ignore_newline / text_ignore_newline — export newline handling.

Mappings

• Visual <CR> normalize-link (visual + covers the same intent).
• Insert <S-CR> multiline list item.
• gLH / gLL / gLR — upstream binds these as case-variant aliases of gLh / gLl / gLr (same actions: dedent / indent whole item, renumber all lists; upstream ftplugin/vimwiki.vim:553,555,561). nuwiki has the lowercase forms but not the uppercase-suffix aliases. Cosmetic — same effect, redundant keys.

---

Intentional divergences (no action — architectural)

These upstream options have no nuwiki equivalent by design, because nuwiki is an LSP-backed reimplementation rather than a pure-VimL plugin. Listed so future audits don't re-flag them.

• nested_syntaxes / automatic_nested_syntaxes — code-fence languages are auto-detected from the fence tag (syntax/vimwiki.vim); always on, no toggle.
• maxhi — existence-based link highlighting; superseded by LSP diagnostics.
• conceal* (conceallevel, conceal_onechar_markers, …) — semantic tokens replace conceal.
• ext2syntax — syntax chosen by extension / syntax key automatically.
• folding (upstream string) — nuwiki uses folding = 'lsp' | 'expr' | 'off' backed by LSP foldingRange.
• key_mappings (dict) — replaced by Lua mappings.<group> + the g:nuwiki_no_<group>_mappings globals.
• use_calendar — no calendar.vim integration.
• CJK_length, listing_hl*, schemes_*, w32_dir_enc, menu, rx_todo / tag_format — syntax internals, menu, or Vim/Win shims.

---

Notes

• Audit confidence: upstream defaults pulled from vimwiki master; a couple of values (CJK_length, links_space_char) were summarized loosely but don't affect the gap list.
• nuwiki adds some commands with no upstream equivalent (e.g. :NuwikiFindOrphans) — additive, not divergences.