From 38fed6dd9e9b092433540ee341329b0a82bfe624 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Gabriel=20Fr=C3=B3es=20Franco?= Date: Wed, 3 Jun 2026 14:23:51 +0000 Subject: [PATCH] docs: add known-issues.md gathering vimwiki divergences Consolidate the deferred features and intentional divergences from the parity log (development/vimwiki-gap.md) into a user-facing reference: - Deferred: the markdown generated-content cluster (markdown heading generation, markdown_header_style, markdown_link_ext) - By-design divergences grouped by area (highlighting/conceal -> LSP, syntax detection, config mechanism, auto_tags, mouse maps, list_margin negative + diary_caption_level -1 value semantics, Vim/Win shims) - Default-location differences (html_path/template_path/diary_rel_path) - Notes on the vars.vim compat shim and additive commands Link it from the README "Migrating from vimwiki" section so it's discoverable. Co-Authored-By: Claude Opus 4.8 --- README.md | 4 ++ known-issues.md | 120 ++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 124 insertions(+) create mode 100644 known-issues.md diff --git a/README.md b/README.md index 0b7e1b1..383e328 100644 --- a/README.md +++ b/README.md @@ -664,6 +664,10 @@ modification. The first workspace scan after launch may show an empty `:VimwikiCheckLinks` result until the background index completes; subsequent runs are instant. +A few upstream options are implemented differently or not at all — by +design, since nuwiki is LSP-backed rather than pure VimL. See +[`known-issues.md`](./known-issues.md) for the full list of divergences. + --- ## License diff --git a/known-issues.md b/known-issues.md new file mode 100644 index 0000000..76bef81 --- /dev/null +++ b/known-issues.md @@ -0,0 +1,120 @@ +# Known Issues & Divergences from vimwiki + +nuwiki is an LSP-backed reimplementation of [vimwiki](https://github.com/vimwiki/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`](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.` table and the `g:nuwiki_no__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>`, ``, …) | 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` | `/_html` | sibling `_html/` | +| `template_path` | `/_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.