gffranco/nuwiki
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 3 Wiki Activity

Expand README: coc setup, complete Nuwiki-first command/keymap tables
CI / cargo fmt --check (push) Successful in 19s
Details
CI / cargo clippy (push) Successful in 22s
Details
CI / cargo test (push) Successful in 47s
Details
CI / editor keymaps (push) Successful in 1m56s
Details

Browse Source 
Document third-party LSP client setup (vim-lsp auto-registration and the
coc.nvim coc-settings.json snippet), add a Requirements section and
:NuwikiInstall. Rewrite the command reference as Nuwiki-first tables with
their :Vimwiki* counterparts, list the full command and mapping surface
(including mouse maps), and fix the <Leader>ww description.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
Gabriel Fróes Franco
2026-05-30 15:54:12 -03:00
parent cd9d587aab
commit b1155dee6a
1 changed files with 144 additions and 37 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+144 -37
View File
@@ -71,6 +71,21 @@ results.
The plugin ships a `nuwiki-ls` binary that the editor talks to over LSP
stdio. The `install()` helper downloads a pre-built release for your
platform, falling back to `cargo build --release` if no asset matches.
You can run it any time with `:NuwikiInstall` (works in both Vim and
Neovim) instead of relying on a plugin-manager build hook.
### Requirements
- **Neovim 0.11+** — uses the built-in LSP client; no extra plugin.
Older releases fall back to a `vim.lsp.start` autocmd but aren't
officially supported.
- **Vim 9+** — needs a third-party LSP client:
[`vim-lsp`](https://github.com/prabirshrestha/vim-lsp) (recommended,
auto-registered) or [`coc.nvim`](https://github.com/neoclide/coc.nvim)
(one-time `coc-settings.json` entry — see [Vim LSP client
setup](#vim-lsp-client-setup)).
- **Rust toolchain (1.83+ stable)** — only needed when building the
binary from source; pre-built release downloads skip this.
### lazy.nvim
@@ -113,11 +128,42 @@ cd ~/.vim/pack/gffranco/start/nuwiki && cargo build --release -p nuwiki-ls
mkdir -p bin && ln -s ../target/release/nuwiki-ls bin/nuwiki-ls
```
Plain Vim users also need an LSP client —
[`vim-lsp`](https://github.com/prabirshrestha/vim-lsp) is the
recommended path, with [`coc.nvim`](https://github.com/neoclide/coc.nvim)
as a fallback. Neovim 0.11+ uses its built-in LSP client and needs
no extra plugin.
### Vim LSP client setup
Neovim 0.11+ registers the server through its built-in LSP client
automatically — nothing to configure. Plain Vim needs one of the
following clients on its `runtimepath`; nuwiki picks them up in this
order when the first `.wiki` buffer loads.
**vim-lsp (recommended)** — zero configuration. Once
[`vim-lsp`](https://github.com/prabirshrestha/vim-lsp) (and its
[`async.vim`](https://github.com/prabirshrestha/async.vim) dependency)
is installed, nuwiki calls `lsp#register_server()` for you and vim-lsp
auto-enables it. Your wiki settings (`g:nuwiki_wiki_root`,
`g:nuwiki_wikis`, …) are forwarded as the server's initialization
options.
**coc.nvim** — [`coc.nvim`](https://github.com/neoclide/coc.nvim) reads
its server list from `coc-settings.json`, which the plugin can't edit
on your behalf, so add the entry once yourself (open it with
`:CocConfig`):
```json
{
"languageserver": {
"nuwiki": {
"command": "~/.vim/pack/gffranco/start/nuwiki/bin/nuwiki-ls",
"filetypes": ["vimwiki"]
}
}
}
```
Point `command` at the installed binary — by default it lives in the
plugin's `bin/` directory (adjust the path for your plugin manager), or
set `g:nuwiki_binary_path` and reuse that value. With coc you can also
invoke server commands directly via `:CocCommand nuwiki.<command>`
instead of the `:Vimwiki*` / `:Nuwiki*` aliases.
### Try it without touching your config
@@ -220,37 +266,87 @@ let g:nuwiki_mouse_mappings = 0 " set to 1 to enable mouse maps
### Commands
Both `:Vimwiki*` (migration compat) and `:Nuwiki*` (canonical native)
are registered as buffer-local commands on every `.wiki` buffer.
Selected highlights — type `:Vimwiki<Tab>` for the full list.
`:Nuwiki*` is the canonical native surface; every command also has a
`:Vimwiki*` counterpart for drop-in migration. Both are registered as
buffer-local commands on every `.wiki` buffer (the wiki picker is also
global so you can switch wikis before any `.wiki` file is open). Type
`:Nuwiki<Tab>` or `:Vimwiki<Tab>` to browse them; coc.nvim users can
also call the server directly with `:CocCommand nuwiki.<command>`.
| Command | What it does |
|---|---|
| `:VimwikiIndex [N]` | Open wiki N's index page (default: 1) |
| `:VimwikiTabIndex [N]` | Same, in a new tab |
| `:VimwikiUISelect` | Pick a wiki from a list (multi-wiki only) |
| `:VimwikiGoto {page}` | Open `{page}.wiki` by name |
| `:VimwikiMakeDiaryNote` | Open today's diary entry (or this week / month / year, depending on `diary_frequency`) |
| `:VimwikiMakeYesterdayDiaryNote` / `:VimwikiMakeTomorrowDiaryNote` | Step the diary back / forward by one period |
| `:VimwikiDiaryIndex` | Open the diary index page |
| `:VimwikiDiaryGenerateLinks` | Rebuild the diary index from current entries |
| `:VimwikiDiaryNextDay` / `:VimwikiDiaryPrevDay` | Chronological diary nav (same cadence as the current entry) |
| `:VimwikiTOC` | Generate / refresh the table of contents on the current page |
| `:VimwikiGenerateLinks` | Insert a flat list of every page in the wiki |
| `:VimwikiCheckLinks` | Send broken links to the quickfix list |
| `:VimwikiSearchTags {tag}` | Quickfix listing every occurrence of `:tag:` |
| `:VimwikiGenerateTagLinks [tag]` | Insert a section linking every page that has `<tag>` |
| `:VimwikiRebuildTags` | Force a full workspace re-index |
| `:VimwikiRenameFile` | Rename the current page, rewriting incoming links |
| `:VimwikiDeleteFile` | Delete the current page |
| `:Vimwiki2HTML` | Render the current page to HTML |
| `:Vimwiki2HTMLBrowse` | Render the current page and open it in the default browser |
| `:VimwikiAll2HTML[!]` | Export the whole wiki (`!` forces; otherwise incremental) |
| `:VimwikiRss` | Write `rss.xml` for diary entries |
| `:VimwikiFollowLink` | Follow the link under the cursor |
| `:VimwikiBacklinks` | Show all references to the current page |
| `:VimwikiNextLink` / `:VimwikiPrevLink` | Jump to the next / previous wikilink on the page |
| `:VimwikiBaddLink` | Add the target of the link under the cursor to the buffer list |
Only the legacy short forms `:VWB` / `:VWS` and `:VimwikiSearch` keep a
Vimwiki-only name (shown as `—` in the Nuwiki column); every other
command is mirrored. The split / tab link-following commands exist on
the Neovim path only — plain Vim uses the `<S-CR>` / `<C-CR>` mappings
instead.
**Wiki & navigation**
| Nuwiki | Vimwiki | Action |
|---|---|---|
| `:NuwikiIndex [N]` | `:VimwikiIndex [N]` | Open wiki N's index page (default: 1) |
| `:NuwikiTabIndex [N]` | `:VimwikiTabIndex [N]` | Same, in a new tab |
| `:NuwikiUISelect` | `:VimwikiUISelect` | Pick a wiki from a list (multi-wiki) |
| `:NuwikiGoto {page}` | `:VimwikiGoto {page}` | Open `{page}.wiki` by name |
| `:NuwikiFollowLink` | `:VimwikiFollowLink` | Follow the link under the cursor |
| `:NuwikiSplitLink` / `:NuwikiVSplitLink` / `:NuwikiTabnewLink` | `:VimwikiSplitLink` / `:VimwikiVSplitLink` / `:VimwikiTabnewLink` | Follow the link in a horizontal split / vertical split / new tab (Neovim) |
| `:NuwikiGoBackLink` | `:VimwikiGoBackLink` | Jump back to where you followed the link from (Neovim) |
| `:NuwikiBacklinks` | `:VimwikiBacklinks` (`:VWB`) | Show all references to the current page |
| `:NuwikiNextLink` / `:NuwikiPrevLink` | `:VimwikiNextLink` / `:VimwikiPrevLink` | Jump to the next / previous wikilink |
| `:NuwikiBaddLink` | `:VimwikiBaddLink` | Add the link target under the cursor to the buffer list |
| — | `:VimwikiSearch {pat}` (`:VWS`) | `:lvimgrep` `{pat}` across every page |
**Diary**
| Nuwiki | Vimwiki | Action |
|---|---|---|
| `:NuwikiMakeDiaryNote` (`:NuwikiDiaryToday`) | `:VimwikiMakeDiaryNote` | Open today's entry (or this week / month / year, per `diary_frequency`) |
| `:NuwikiMakeYesterdayDiaryNote` (`:NuwikiDiaryYesterday`) | `:VimwikiMakeYesterdayDiaryNote` | Step the diary back one period |
| `:NuwikiMakeTomorrowDiaryNote` (`:NuwikiDiaryTomorrow`) | `:VimwikiMakeTomorrowDiaryNote` | Step the diary forward one period |
| `:NuwikiDiaryIndex` | `:VimwikiDiaryIndex` | Open the diary index page |
| `:NuwikiDiaryGenerateLinks` | `:VimwikiDiaryGenerateLinks` | Rebuild the diary index from current entries |
| `:NuwikiDiaryNextDay` / `:NuwikiDiaryPrevDay` (`:NuwikiDiaryNext` / `:NuwikiDiaryPrev`) | `:VimwikiDiaryNextDay` / `:VimwikiDiaryPrevDay` | Chronological diary nav (same cadence as the current entry) |
**Pages & files**
| Nuwiki | Vimwiki | Action |
|---|---|---|
| `:NuwikiRenameFile` | `:VimwikiRenameFile` | Rename the current page, rewriting incoming links |
| `:NuwikiDeleteFile` | `:VimwikiDeleteFile` | Delete the current page |
**Lists, tasks & tables**
| Nuwiki | Vimwiki | Action |
|---|---|---|
| `:NuwikiNextTask` | `:VimwikiNextTask` | Jump to the next unfinished task |
| `:NuwikiToggleListItem` | `:VimwikiToggleListItem` | Toggle the checkbox under the cursor |
| `:NuwikiToggleRejected` | `:VimwikiToggleRejectedListItem` | Toggle the rejected marker `[-]` |
| `:NuwikiRemoveDone` | `:VimwikiRemoveDone` | Remove every completed item from the current list |
| `:NuwikiListChangeLvl {increase\|decrease}` | `:VimwikiListChangeLvl {increase\|decrease}` | Indent / dedent the current list item |
| `:NuwikiTable {cols} [rows]` | `:VimwikiTable {cols} [rows]` | Insert a table at the cursor |
| `:NuwikiTableMoveColumnLeft` / `:NuwikiTableMoveColumnRight` | `:VimwikiTableMoveColumnLeft` / `:VimwikiTableMoveColumnRight` | Move the current table column left / right |
**Contents, links & tags**
| Nuwiki | Vimwiki | Action |
|---|---|---|
| `:NuwikiTOC` | `:VimwikiTOC` | Generate / refresh the table of contents on the current page |
| `:NuwikiGenerateLinks` | `:VimwikiGenerateLinks` | Insert a flat list of every page in the wiki |
| `:NuwikiCheckLinks` | `:VimwikiCheckLinks` | Send broken links to the quickfix list |
| `:NuwikiFindOrphans` | `:VimwikiFindOrphans` | List pages with no incoming links in the quickfix list |
| `:NuwikiRebuildTags` | `:VimwikiRebuildTags` | Force a full workspace re-index |
| `:NuwikiSearchTags {tag}` | `:VimwikiSearchTags {tag}` | Quickfix listing every occurrence of `:tag:` |
| `:NuwikiGenerateTagLinks [tag]` | `:VimwikiGenerateTagLinks [tag]` | Insert a section linking every page that has `<tag>` |
| `:NuwikiColorize {color}` | `:VimwikiColorize {color}` | Wrap the word / visual selection in a coloured `<span>` |
| `:NuwikiPasteLink` / `:NuwikiPasteUrl` | `:VimwikiPasteLink` / `:VimwikiPasteUrl` | Paste the clipboard contents as a wikilink / raw URL |
**HTML export**
| Nuwiki | Vimwiki | Action |
|---|---|---|
| `:Nuwiki2HTML` (`:NuwikiExport`) | `:Vimwiki2HTML` | Render the current page to HTML |
| `:Nuwiki2HTMLBrowse` (`:NuwikiExportBrowse`) | `:Vimwiki2HTMLBrowse` | Render the current page and open it in the default browser |
| `:NuwikiAll2HTML[!]` (`:NuwikiExportAll[!]`) | `:VimwikiAll2HTML[!]` | Export the whole wiki (`!` forces; otherwise incremental) |
| `:NuwikiRss` | `:VimwikiRss` | Write `rss.xml` for diary entries |
### Default keymaps
@@ -316,10 +412,12 @@ Neovim, or `let g:nuwiki_no_default_mappings = 1` in Vim.
| Key | Action |
|---|---|
| `<Leader>ww` | Open today's diary |
| `<Leader>ww` | Open the wiki index |
| `<Leader>wt` | Open the wiki index in a new tab |
| `<Leader>ws` | Pick a wiki |
| `<Leader>wi` | Open the diary index |
| `<Leader>w<Leader>w` / `<Leader>w<Leader>y` / `<Leader>w<Leader>t` | Today / yesterday / tomorrow |
| `<Leader>w<Leader>w` / `<Leader>w<Leader>y` / `<Leader>w<Leader>t` | Diary today / yesterday / tomorrow |
| `<Leader>w<Leader>m` | Diary tomorrow (vimwiki-compat alias of `<Leader>w<Leader>t`) |
| `<Leader>w<Leader>i` | Rebuild the diary index page |
| `<Leader>wn` / `<Leader>wd` / `<Leader>wr` | Goto / delete / rename page |
| `<Leader>wh` / `<Leader>whh` | Export the current page to HTML / open in browser |
@@ -327,6 +425,15 @@ Neovim, or `let g:nuwiki_no_default_mappings = 1` in Vim.
| `<Leader>wc` | Wrap word (or visual selection) in a colour span |
| `<C-Down>` / `<C-Up>` | Next / previous diary entry |
**Mouse** (normal mode, opt-in via `mappings.mouse = true` / `let g:nuwiki_mouse_mappings = 1`)
| Key | Action |
|---|---|
| `<2-LeftMouse>` | Follow the link under the pointer |
| `<S-2-LeftMouse>` / `<C-2-LeftMouse>` | Follow in a horizontal / vertical split |
| `<MiddleMouse>` | Add the link target to the buffer list |
| `<RightMouse>` | Jump back (`<C-o>`) |
**Text objects** (operator-pending + visual)
| Object | Selection |