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 lists what to expect if you're coming from vimwiki. Everything here is either a deliberate design choice or a tracked future task; none of it is an accidental bug. For the detailed, per-option parity log (with code references and test names), see development/vimwiki-gap.md.

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)

---

Notes

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