nuwiki/development/ONBOARDING.md

nuwiki Developer Onboarding

Overview

nuwiki is a vimwiki-compatible Vim/Neovim plugin backed by a Rust language server. It provides full vimwiki syntax support while keeping the original file format, keymaps, and command surface intact. The substantive work happens in a Rust LSP daemon — Vim and Neovim are thin client layers that wire up keystrokes and display results.

The Rust LSP server lives in the separate nuwiki-rs repository. This plugin repo is the Vim/Neovim client layer and is distributed independently from the server binary.

Repository Structure

nuwiki/
├── plugin/                     # Universal Vim/Neovim entry point
│   └── nuwiki.vim
│
├── lua/                        # Neovim-specific Lua layer
│   └── nuwiki/
│       ├── init.lua
│       ├── config.lua
│       ├── lsp.lua
│       └── install.lua         # Binary download logic
│
├── autoload/                   # Lazy-loaded VimL (Vim compat layer)
│   └── nuwiki/
│       └── lsp.vim
│
├── ftdetect/                   # Filetype detection for .wiki files
│   └── nuwiki.vim
│
├── ftplugin/                   # Per-filetype buffer settings
│   └── nuwiki.vim
│
├── syntax/                     # Static fallback syntax highlighting (no LSP required)
│   └── nuwiki.vim
│
├── doc/                        # Vim help documentation
│   └── nuwiki.txt
│
├── scripts/                    # Plugin-runtime scripts only
│   └── download_bin.vim        # VimL binary download (used by Dein/vim-plug build hooks)
│
├── development/                # Developer-only tooling and docs (not shipped)
│   ├── ONBOARDING.md           # This file
│   ├── SPEC.md                 # Technical reference (architecture, LSP, commands)
│   ├── nuwiki-architecture.html
│   ├── start-nvim.sh           # Launch Neovim against a generated sample wiki
│   ├── start-vim.sh            # Launch Vim against a generated sample wiki
│   ├── syntax-diag.vim         # Dump highlighting state for debugging
│   └── tests/                  # Editor keymap/command harnesses (run in CI)
│       ├── test-keymaps.sh     # Neovim keymap harness
│       ├── test-keymaps.lua
│       ├── test-keymaps-vim.sh # Vim keymap harness
│       ├── test-keymaps-vim.vim
│       ├── test-calendar.sh    # Neovim calendar-vim integration harness
│       ├── test-calendar.lua
│       ├── test-calendar-vim.sh # Vim calendar-vim integration harness
│       ├── test-calendar-vim.vim
│       └── test-calendar-vim-optout.vim
│
└── .gitea/
    └── workflows/
        ├── ci.yaml             # Editor (Vim/Neovim) harnesses on every push/PR
        └── release.yaml        # Dispatch → stamp version, tag, Gitea release (no build)

(The Rust server's binary build/cross-compile workflow lives in the separate nuwiki-rs repository; this repo's release just tags the plugin.)

Server Component

The Rust LSP server (nuwiki-ls) lives in the separate nuwiki-rs repository. Pre-built binaries are downloaded automatically by the plugin's install() function. To build from source:

git clone https://code.gfran.co/gffranco/nuwiki-rs
cd nuwiki-rs
cargo build --release -p nuwiki-ls

Build & Installation

Prerequisites

• For editor integration: Vim 9+ or Neovim 0.5+ with an LSP client (vim-lsp recommended for Vim, built-in for Neovim 0.11+)
• The nuwiki-ls binary is downloaded automatically; no Rust toolchain required unless building from source

Installation via Plugin Managers

lazy.nvim

{
  'gffranco/nuwiki',
  build = ":lua require('nuwiki').install()",
  ft = { 'vimwiki' },
  opts = {
    wiki_root = '~/vimwiki',
  },
}

vim-plug

Plug 'gffranco/nuwiki', { 'do': 'vim -e -s -c \"source scripts/download_bin.vim\" -c \"q\"' }

Dein

call dein#add('gffranco/nuwiki', {
\ 'build': 'vim -e -s -c \"source scripts/download_bin.vim\" -c \"q\"'
\ })

Manual Installation (Plain Vim)

git clone https://code.gfran.co/gffranco/nuwiki ~/.vim/pack/gffranco/start/nuwiki
cd ~/.vim/pack/gffranco/start/nuwiki
vim -e -s -c "source scripts/download_bin.vim" -c "q"

Plain Vim users also need an LSP client — vim-lsp is recommended.

Development Workflow

Testing (Editor Layer)

# Run editor tests (shell + Lua harnesses in development/tests/)
./development/tests/test-keymaps.sh
./development/tests/test-calendar.sh

For Rust-level tests, see the nuwiki-rs repository:

# In the nuwiki-rs repo
cargo test --workspace
cargo clippy --workspace -- -D warnings

Running the LSP Server Manually (for debugging)

Build from nuwiki-rs and run:

cargo run -p nuwiki-ls -- --help

The LSP server communicates over stdio. You can test it with an LSP client like lspci or by connecting from Neovim.

Health Check (Neovim)

After installing the plugin, run:

:checkhealth nuwiki

This verifies:

• Binary exists at {plugin_dir}/bin/nuwiki-ls
• Binary is executable and responds to --version
• LSP client is running
• Filetype detection works for .wiki files

Editor Layers

VimL Layer (plugin/nuwiki.vim, autoload/)

• Universal entry point for all plugin managers
• Detects whether running in Neovim or Vim
• For Neovim: delegates to Lua layer
• For Vim: starts the LSP server via nuwiki#lsp#start()

Neovim Lua Layer (lua/nuwiki/)

• init.lua: Main setup function
• config.lua: Configuration schema and defaults
• lsp.lua: Starts the LSP client using vim.lsp.start()
• install.lua: Handles binary download/build and places it in the plugin's bin/ directory

Vim Compatibility Layer (autoload/nuwiki/lsp.vim)

• Provides the nuwiki#lsp#start() function for Vim
• Handles binary location and LSP client startup via vim-lsp or coc.nvim

Important Notes

• The Rust LSP server is in the separate nuwiki-rs repository.
• This plugin repo contains only the editor client layer (VimL/Lua).
• Editor layers (VimL/Lua) contain zero logic — they are pure wiring only.
• All syntax-specific code lives in the Rust LSP server's nuwiki-core crate.

Getting Started

1. Clone this plugin repository:

   git clone https://code.gfran.co/gffranco/nuwiki
   cd nuwiki
   

2. Install the plugin in your Neovim/Vim configuration using your preferred plugin manager (see above examples). The nuwiki-ls binary will be downloaded automatically.

3. Open a .wiki file and verify:

   • Syntax highlighting works
   • :VimwikiIndex opens the index page
   • LSP features (go-to-definition, hover, completions) work via :checkhealth nuwiki

To modify the LSP server itself, clone the nuwiki-rs repository and build the binary from source.

CI/CD

This repo (editor client) uses Gitea Actions:

• CI (.gitea/workflows/ci.yaml): Runs the editor harnesses on every push/PR.
• Release (.gitea/workflows/release.yaml): workflow_dispatch with a version input — stamps g:nuwiki_version, tags vX.Y.Z, and publishes a Gitea release. No binary build (the plugin ships none).

The Rust LSP server lives in nuwiki-rs which has its own release workflow — it cross-compiles nuwiki-ls for Linux targets and publishes the downloadable binaries the plugin fetches.

Releasing the plugin

Releases are cut from the Actions UI — Release workflow (.gitea/workflows/release.yaml) → Run workflow → enter the version (e.g. 0.5.1). It stamps g:nuwiki_version in plugin/nuwiki.vim, sanity-checks that the plugin still sources, commits chore(release): X.Y.Z, pushes the vX.Y.Z tag, and publishes a Gitea release entry. The plugin ships no binary, so the release carries no assets by design.

The plugin and the nuwiki-ls server version independently; the binary is fetched from nuwiki-rs's latest release at install time. To do it by hand instead: bump g:nuwiki_version, commit, then git tag vX.Y.Z && git push --tags.

License

Dual-licensed under MIT or Apache-2.0 at your option.