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.

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 — deliberately removed in c63ec67; the weekly diary is fixed to ISO-Monday. Default matches upstream, but non-Monday users lose it. Fix: config.rs + crates/nuwiki-core/src/date.rs.

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.

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.

---

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.