nuwiki/doc/nuwiki.txt

*nuwiki.txt*    LSP-backed vimwiki support for Vim and Neovim.

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: