phase 9: editor glue — plugin, LSP wiring, install, health, docs
P5 + P6 resolved (SPEC §11): Neovim 0.11+ and Vim 9.1+.
Universal Vim entry:
- plugin/nuwiki.vim dispatches Vim vs Neovim. Neovim path waits for
the user's `require('nuwiki').setup()` call; Vim path starts the
LSP client on `FileType vimwiki` and exposes `:NuwikiInstall`.
- ftdetect/nuwiki.vim associates `*.wiki` with the `vimwiki` filetype.
- ftplugin/nuwiki.vim sets commentstring + comments + formatoptions +
suffixesadd + iskeyword, with a clean `b:undo_ftplugin`.
- syntax/nuwiki.vim ships default `@vimwiki*` highlight links for the
semantic-token legend (with `level1..6` + `centered` modifiers),
plus a minimal regex fallback so static highlighting works before
the LSP attaches.
Lua glue (Neovim 0.11+):
- init.lua exposes setup() / install() / health() — wiring only per
SPEC §6.2.
- config.lua holds the §7.5 schema (wiki_root / file_extension /
syntax / log_level) and a tbl_deep_extend apply().
- lsp.lua registers via `vim.lsp.config{} + vim.lsp.enable` on 0.11+;
falls back to a FileType autocmd calling `vim.lsp.start` on older
builds. Root dir walks up for `.git` / `.nuwiki`, then uses
wiki_root.
- install.lua does target-triple detection (Linux gnu/musl x x86_64/
aarch64, macOS arm/x86, Windows), curl+tar download from the
release URL, cp/chmod into bin/, with a cargo fallback. Honours
`g:nuwiki_build_from_source`.
- health.lua implements `:checkhealth nuwiki` per §7.6.
VimL glue (Vim 9.1+):
- autoload/nuwiki/lsp.vim follows §7.4 preference order:
vim-lsp (calls `lsp#register_server`) → coc.nvim (prints the
coc-settings.json snippet) → error.
- scripts/download_bin.vim mirrors the Lua installer for Dein /
vim-plug build hooks — same target triples, same download →
fallback → cargo build chain.
Help: doc/nuwiki.txt with tags for install (lazy.nvim / vim-plug /
Dein), config options, health, LSP feature list, `:NuwikiInstall`.
Rust workspace unchanged this phase; 172 tests still green locally.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
+159
-1
@@ -1,5 +1,163 @@
|
||||
*nuwiki.txt* LSP-backed vimwiki support for Vim and Neovim.
|
||||
|
||||
Documentation deferred to Phase 9 (Editor Glue).
|
||||
Author: Gabriel Fróes Franco
|
||||
License: Dual MIT / Apache-2.0
|
||||
|
||||
==============================================================================
|
||||
CONTENTS *nuwiki-contents*
|
||||
|
||||
1. Introduction ............ |nuwiki-introduction|
|
||||
2. Requirements ............ |nuwiki-requirements|
|
||||
3. Installation ............ |nuwiki-installation|
|
||||
4. Configuration ........... |nuwiki-config|
|
||||
5. Health check ............ |nuwiki-health|
|
||||
6. LSP features ............ |nuwiki-features|
|
||||
7. Commands ................ |nuwiki-commands|
|
||||
|
||||
==============================================================================
|
||||
1. INTRODUCTION *nuwiki-introduction*
|
||||
|
||||
nuwiki brings full vimwiki syntax support to Vim and Neovim via a Rust-
|
||||
based language server (|nuwiki-ls|). It is architecturally distinct from
|
||||
vimwiki itself — installable through any standard plugin manager, with the
|
||||
heavy lifting done in a single binary that speaks LSP over stdio.
|
||||
|
||||
==============================================================================
|
||||
2. REQUIREMENTS *nuwiki-requirements*
|
||||
|
||||
* Neovim 0.11+ (preferred path)
|
||||
* Vim 9.1+ with one of:
|
||||
- vim-lsp (prabirshrestha/vim-lsp)
|
||||
- coc.nvim (neoclide/coc.nvim)
|
||||
* `curl` and `tar` (only for binary download; not needed if you build
|
||||
from source)
|
||||
* `cargo` and a Rust toolchain (only if you opt into source builds)
|
||||
|
||||
==============================================================================
|
||||
3. INSTALLATION *nuwiki-installation*
|
||||
|
||||
Install via your plugin manager of choice; the build hook will download
|
||||
the pre-built `nuwiki-ls` binary into the plugin's `bin/` directory.
|
||||
|
||||
lazy.nvim: >
|
||||
|
||||
{
|
||||
"gffranco/nuwiki",
|
||||
build = "lua require('nuwiki').install()",
|
||||
ft = { "vimwiki" },
|
||||
opts = {},
|
||||
}
|
||||
|
||||
<vim-plug: >
|
||||
|
||||
Plug 'gffranco/nuwiki', { 'do': 'vim -e -s -c "source scripts/download_bin.vim" -c "q"' }
|
||||
|
||||
<dein.vim: >
|
||||
|
||||
call dein#add('gffranco/nuwiki', {
|
||||
\ 'build': 'vim -e -s -c "source scripts/download_bin.vim" -c "q"',
|
||||
\ })
|
||||
|
||||
<To force a build from source (no download), set: >
|
||||
|
||||
let g:nuwiki_build_from_source = 1
|
||||
|
||||
<in Vim before re-running the build hook, or in Neovim: >
|
||||
|
||||
vim.g.nuwiki_build_from_source = 1
|
||||
require('nuwiki').install()
|
||||
|
||||
<==============================================================================
|
||||
4. CONFIGURATION *nuwiki-config*
|
||||
|
||||
Neovim (`require('nuwiki').setup{}`): >
|
||||
|
||||
require('nuwiki').setup({
|
||||
wiki_root = '~/vimwiki',
|
||||
file_extension = '.wiki',
|
||||
syntax = 'vimwiki',
|
||||
log_level = 'warn',
|
||||
})
|
||||
|
||||
<Vim sets the equivalent globals before plugin load: >
|
||||
|
||||
let g:nuwiki_wiki_root = '~/vimwiki'
|
||||
let g:nuwiki_file_extension = '.wiki'
|
||||
let g:nuwiki_syntax = 'vimwiki'
|
||||
let g:nuwiki_log_level = 'warn'
|
||||
|
||||
<Options:
|
||||
|
||||
*g:nuwiki_wiki_root*
|
||||
`wiki_root` ~/vimwiki
|
||||
Root directory of the wiki. Used as a fallback `root_dir` when no
|
||||
`.git` / `.nuwiki` marker is found near the buffer.
|
||||
|
||||
*g:nuwiki_file_extension*
|
||||
`file_extension` .wiki
|
||||
File extension associated with the wiki filetype. Note that
|
||||
`ftdetect/nuwiki.vim` hardcodes `.wiki`; users with a custom
|
||||
extension should add their own ftdetect autocmd.
|
||||
|
||||
*g:nuwiki_syntax*
|
||||
`syntax` vimwiki
|
||||
Future-proofing for additional syntaxes (e.g. `markdown`). Phase 9
|
||||
only ships the vimwiki plugin.
|
||||
|
||||
*g:nuwiki_log_level*
|
||||
`log_level` warn
|
||||
`error` | `warn` | `info` | `debug`. Forwarded to the language server.
|
||||
|
||||
*g:nuwiki_build_from_source*
|
||||
`g:nuwiki_build_from_source` 0
|
||||
When 1, the install step always builds from source (cargo) and skips
|
||||
the release-asset download path.
|
||||
|
||||
*g:nuwiki_binary_path*
|
||||
`g:nuwiki_binary_path`
|
||||
Override the auto-discovered server path. If set and the file is
|
||||
readable, `autoload/nuwiki/lsp.vim` uses it instead of the
|
||||
`{plugin}/bin/nuwiki-ls` default.
|
||||
|
||||
==============================================================================
|
||||
5. HEALTH CHECK *nuwiki-health*
|
||||
|
||||
Neovim users can run: >
|
||||
|
||||
:checkhealth nuwiki
|
||||
|
||||
<This reports whether the binary exists, responds to `--version`, whether
|
||||
`wiki_root` exists, whether `.wiki` filetype detection is wired up, and
|
||||
whether an LSP client is currently attached.
|
||||
|
||||
==============================================================================
|
||||
6. LSP FEATURES *nuwiki-features*
|
||||
|
||||
The language server provides every method listed in SPEC §6.9:
|
||||
|
||||
* Syntax highlighting via semantic tokens
|
||||
`textDocument/semanticTokens/full` + `/range`
|
||||
* Document outline
|
||||
`textDocument/documentSymbol`
|
||||
* Diagnostics (parse errors)
|
||||
`textDocument/publishDiagnostics`
|
||||
* Go-to-definition (follow wikilinks)
|
||||
`textDocument/definition`
|
||||
* Backlinks
|
||||
`textDocument/references`
|
||||
* Hover preview (page title + outline)
|
||||
`textDocument/hover`
|
||||
* Completion on `[[`
|
||||
`textDocument/completion`
|
||||
* Workspace symbol search
|
||||
`workspace/symbol`
|
||||
|
||||
==============================================================================
|
||||
7. COMMANDS *nuwiki-commands*
|
||||
|
||||
*:NuwikiInstall*
|
||||
:NuwikiInstall
|
||||
Install (or re-install) the `nuwiki-ls` binary into the plugin's
|
||||
`bin/` directory. Equivalent to running the build hook by hand.
|
||||
|
||||
vim:tw=78:ts=8:ft=help:norl:
|
||||
|
||||
Reference in New Issue
Block a user