From 00a671e4866dfd0ed4bd17079fd6ac53e86c0006 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Gabriel=20Fr=C3=B3es=20Franco?= Date: Sun, 31 May 2026 07:30:22 -0300 Subject: [PATCH] docs(parity): track vimwiki config/command/mapping gaps MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add development/vimwiki-gap.md, a checkbox-tracked audit of where nuwiki diverges from upstream vimwiki across configuration options, Ex-commands, and key mappings. Items are prioritised P1–P3 with a fix site cited on each, plus an "intentional divergences" section so the LSP-rearchitected choices aren't re-flagged in future audits. Co-Authored-By: Claude Opus 4.7 --- development/vimwiki-gap.md | 120 +++++++++++++++++++++++++++++++++++++ 1 file changed, 120 insertions(+) create mode 100644 development/vimwiki-gap.md diff --git a/development/vimwiki-gap.md b/development/vimwiki-gap.md new file mode 100644 index 0000000..b01ccdc --- /dev/null +++ b/development/vimwiki-gap.md @@ -0,0 +1,120 @@ +# 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) + +- [ ] **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, ~lines 30–175). +- [ ] **`gl` 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:_ `lua/nuwiki/keymaps.lua` lists group, `ftplugin/vimwiki.vim` lists block. +- [ ] **`gl` / `gL` 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) + +- [ ] **`wt` 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`** — `w` hardcoded across the map layer. + _Fix:_ `plugin/nuwiki.vim`, `lua/nuwiki/keymaps.lua`, `ftplugin/vimwiki.vim`. +- [ ] **`` badd-link** — missing (badd is mouse-only via `` / + `: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 `` normalize-link (visual `+` covers the same intent). +- [ ] Insert `` 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.` + the + `g:nuwiki_no__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.