nuwiki/development/vimwiki-gap.md

# vimwiki → nuwiki Parity Gaps

Tracking document for closing the gap between nuwiki and the original
[vimwiki](https://github.com/vimwiki/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)

- [x] **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.
- [x] **`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 rebinds to *remove done items*.
  Same keys, different effect (parity trap). Remove-checkbox is command-only in
  nuwiki (`:NuwikiRemoveCheckbox` / `…InList`).
  _Fix:_ `lua/nuwiki/keymaps.lua`, `ftplugin/vimwiki.vim`.

## 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.