nuwiki/known-issues.md

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_body reads 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_line scans 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 / PrevDay rebuild and sort the entry list to find one neighbor. Same reasoning — cold path, small input.

Notes

• Upstream g:vimwiki_list config (Vim). When you haven't configured nuwiki natively, the Vim client reads your upstream g:vimwiki_list + g:vimwiki_* globals and translates them into nuwiki's schema (per-wiki path/path_html/template_*/auto_export, plus globals toc_header, toc_header_level, html_header_numbering, html_header_numbering_sym, links_space_char, list_margin). g:nuwiki_* always wins. Globals nuwiki doesn't model (e.g. automatic_nested_syntaxes) are ignored — see the divergence list above. Limitation: this drop-in translation is currently Vim-only; on Neovim, configure via setup() / g:nuwiki_wikis.
• Third-party plugin compatibility. A shim at autoload/vimwiki/vars.vim exposes the subset of vimwiki#vars#get_wikilocal that 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.