gffranco
9d89e01ed8
Two related config-ergonomics features for vimwiki migrants, sharing the
same scalar-global machinery.
1. Upstream g:vimwiki_* drop-in (Vim client). When nuwiki isn't configured
natively, the Vim client reads g:vimwiki_list + g:vimwiki_* globals and
translates them into nuwiki's schema: per-wiki path->root,
path_html->html_path, template_*, css_name, auto_export/auto_toc,
syntax, ext->file_extension, index, diary_*, name. g:nuwiki_* always
wins. Lets a vimwiki user drop in nuwiki without rewriting config.
2. Global per-wiki defaults (both clients). A display/generation setting
given once at the top level — g:nuwiki_<key> / setup({<key>=…}) /
g:vimwiki_<key> — is folded into every wiki as a default; a per-wiki
value overrides it (vimwiki's model). Covers toc_header(_level),
toc_link_format, links_header(_level), tags_header(_level),
html_header_numbering(_sym), links_space_char, list_margin, listsyms,
listsym_rejected, and the auto_* toggles. Only values the user
explicitly set fold — built-in defaults don't (added config.user
tracking on the Lua side so a default toc_header_level=1 isn't pushed
onto every wiki). User config tables are never mutated.
Both clients kept in lock-step (config-parity golden enforces identical
payloads). New harnesses test-vimwiki-compat-vim (18) and
test-global-shorthand (8), wired into CI. Server test
vimwiki_compat_payload_sets_toc_level_per_wiki. Docs in README +
known-issues.md (drop-in is currently Vim-only). Rust 573 passed, clippy
clean, all harnesses green.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
148 lines
7.4 KiB
Markdown
148 lines
7.4 KiB
Markdown
# 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 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.
|