nuwiki/doc/nuwiki.txt

*nuwiki.txt*    A vimwiki-compatible plugin backed by a Rust language server.

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. Commands ................ |nuwiki-commands|
  6. Keymaps ................. |nuwiki-keymaps|
  7. Text objects ............ |nuwiki-text-objects|
  8. Insert-mode bindings .... |nuwiki-insert-mode|
  9. Diary ................... |nuwiki-diary|
 10. Tables ................... |nuwiki-tables|
 11. HTML export .............. |nuwiki-html|
 12. Folding .................. |nuwiki-folding|
 13. Health check ............. |nuwiki-health|
 14. Migrating from vimwiki ... |nuwiki-migrating|

==============================================================================
1. INTRODUCTION                                         *nuwiki-introduction*

nuwiki keeps vimwiki's file format, keymaps, and `:Vimwiki*` command surface
intact, but moves the heavy lifting into a Rust language server that the
editor talks to over LSP stdio. The result feels like vimwiki — same files,
same shortcuts — with goto-definition, backlinks, completion, semantic
highlighting, broken-link diagnostics, and incremental HTML export.

Highlights:

  * Full vimwiki syntax — headings, lists, checkboxes, tables (with
    alignment / colspan / rowspan), inline math, code, tags, every link
    kind (wiki, interwiki, diary, file, local, raw URL, transclusion with
    attributes).
  * LSP intelligence — goto-definition, backlinks, hover, completion on
    `[[`, document outline, workspace symbol search, broken-link
    diagnostics, orphan-page finder.
  * Editing helpers — smart `<CR>` continues lists / tables, `<Tab>`
    cycles between table cells, five text-object pairs, list-marker
    cycling.
  * Diary at four cadences — daily, weekly, monthly, or yearly.
  * Multi-wiki with `[[wn.name:Page]]` interwiki links.
  * HTML export with templates, CSS, RSS, and on-save export.
  * Plain Vim and Neovim both supported with feature parity.

==============================================================================
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 the binary download path; 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; the build hook downloads a pre-built
`nuwiki-ls` binary into the plugin's `bin/` directory.

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.vim: >

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

<To force a build from source (skip the download path), 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 users call `setup()` (omit the block entirely to take every
default): >

  require('nuwiki').setup({
    wiki_root      = '~/vimwiki',
    file_extension = '.wiki',
    syntax         = 'vimwiki',
    log_level      = 'warn',
    map_prefix     = '<Leader>w',
  })

<For multiple wikis or per-wiki tuning, use the `wikis` list: >

  require('nuwiki').setup({
    wikis = {
      {
        name             = 'personal',
        root             = '~/vimwiki',
        index            = 'index',
        file_extension   = '.wiki',
        diary_rel_path   = 'diary',
        diary_frequency  = 'daily',  -- daily | weekly | monthly | yearly
        diary_sort       = 'desc',
        html_path        = '~/vimwiki/_html',
        template_path    = '~/vimwiki/_templates',
        template_default = 'default',
        css_name         = 'style.css',
        auto_export      = false,
      },
    },
  })

<Vim users without Lua set the equivalent globals before loading the
plugin: >

  let g:nuwiki_wiki_root           = '~/vimwiki'
  let g:nuwiki_file_extension      = '.wiki'
  let g:nuwiki_log_level           = 'warn'
  let g:nuwiki_map_prefix          = '<Leader>w'

<Top-level options ~

                                                          *g:nuwiki_wiki_root*
`wiki_root`        ~/vimwiki
    Root directory of the single-wiki shorthand. Ignored when `wikis` is
    set (the multi-wiki list takes precedence).

                                                     *g:nuwiki_file_extension*
`file_extension`   .wiki
    File extension associated with the wiki filetype.

                                                              *g:nuwiki_syntax*
`syntax`           vimwiki
    Future-proofing; currently only `vimwiki` is supported.

                                                          *g:nuwiki_log_level*
`log_level`        warn
    `error` | `warn` | `info` | `debug`. Forwarded to the language server.

                                                       *nuwiki-config-map-prefix*
`map_prefix`       '<Leader>w'
    Prefix for the wiki command family (`<prefix>w`, `<prefix>t`,
    `<prefix><Leader>w`, …). Mirrors vimwiki's `g:vimwiki_map_prefix`. Vim
    users set |g:nuwiki_map_prefix| instead.

                                                       *nuwiki-config-folding*
`folding`          'lsp'
    `lsp` uses the server's `foldingRange` provider (Neovim 0.11+ wires
    it automatically). `expr` falls back to a regex `foldexpr`. `off`
    disables folding setup entirely. See |nuwiki-folding| for details.
    Vim users see the regex fallback when |g:nuwiki_no_folding| is not
    set.

                                                               *nuwiki-mappings*
`mappings`         (all on except `mouse`)
    Per-buffer keymap groups. Each subgroup can be flipped off
    independently to suppress that group of keymaps. Subgroups:
    `enabled`, `wiki_prefix`, `links`, `lists`, `headers`,
    `table_editing`, `diary`, `html_export`, `text_objects`, `mouse`.

`diagnostic.link_severity`        `'warn'`
    Severity of broken-link diagnostics: `off`, `hint`, `warn`, `error`.

Per-wiki options ~

Every option in this list lives on a `wikis[i] = {...}` entry. Defaults
match upstream vimwiki.

`name`                   String — display name in `:VimwikiUISelect`.
`root`                   String — absolute or `~`-relative path.
`index`                  `'index'` — stem of the wiki's index page.
`file_extension`         `'.wiki'`
`diary_rel_path`         `'diary'`
`diary_index`            `'diary'` — stem of the diary index page.
`diary_frequency`        `'daily'` | `'weekly'` | `'monthly'` | `'yearly'`
`diary_weekly_style`     `'iso'` (YYYY-Www) | `'date'`/`'vimwiki'` (week-start
                         YYYY-MM-DD). Weekly diaries only.
`diary_start_week_day`   `'monday'`..`'sunday'`; week start used when
                         `diary_weekly_style = 'date'`.
`diary_caption_level`    `0`
`diary_sort`             `'desc'` | `'asc'`
`diary_header`           `'Diary'`
`html_path`              Path for `:Vimwiki2HTML` output.
`template_path`          Path holding `<name>.tpl` templates.
`template_default`       `'default'`
`template_ext`           `'.tpl'`
`template_date_format`   `'%Y-%m-%d'` — strftime format for `%date` in templates.
`css_name`               `'style.css'`
`html_filename_parameterization` `false` — encode subdir paths into the HTML
                         filename instead of nesting directories.
`color_dic`              `{}` — map of `{ name = 'color' }` for `:NuwikiColorize`.
`custom_wiki2html`       `''` — external converter command. When set, export
                         shells out to it instead of the built-in renderer,
                         called as: <cmd> <force> <syntax> <ext> <out_dir>
                         <in_file> <css> <tpl_path> <tpl_default> <tpl_ext>
                         <root_path> <args> (`-` for empty optionals), matching
                         vimwiki's `g:vimwiki_custom_wiki2html` contract.
`custom_wiki2html_args`  `''` — extra args appended to the converter call.
`base_url`               `''` — public URL prefix. When set, diary RSS item
                         links become <base_url><diary_rel_path>/<date>.html
                         instead of local `file://` paths.
`auto_export`            `false` — export to HTML on save.
`auto_toc`               `false` — refresh TOC on save.
`auto_generate_links`    `false` — regen an existing Generated Links section
                         on save.
`auto_generate_tags`     `false` — regen an existing Generated Tags index on
                         save.
`auto_diary_index`       `false` — regen the diary index when a diary entry is
                         saved.
`toc_header`             `'Contents'`  (+ `toc_header_level` `1`) — :VimwikiTOC.
`links_header`           `'Generated Links'` (+ `links_header_level` `1`).
`tags_header`            `'Generated Tags'` (+ `tags_header_level` `1`).
`exclude_files`          List of glob patterns excluded from export.
`listsyms`               `' .oOX'` — checkbox progression characters.
`listsym_rejected`       `'-'` — glyph for a cancelled checkbox `[-]`.
`listsyms_propagate`     `true`
`list_margin`            `-1` — spaces before a list bullet; `-1` follows
                         `shiftwidth`.
`links_space_char`       `' '`

Code fences tagged with a language (`{{{python …}}}`) are highlighted with
that language's syntax automatically — there is no `nested_syntaxes` key.

Vim-specific globals ~

                                                     *g:nuwiki_diary_rel_path*
`g:nuwiki_diary_rel_path`      `'diary'`
    Diary subdirectory, relative to the wiki root. The scalar form for the
    single-wiki shape; per-wiki `diary_rel_path` (or `g:nuwiki_wikis`) wins.

                                                      *g:nuwiki_link_severity*
`g:nuwiki_link_severity`       `'warn'`
    Broken-link diagnostic severity: `off` | `hint` | `warn` | `error`. The
    scalar/global form of the `diagnostic.link_severity` setup() option.

                                                  *g:nuwiki_no_default_mappings*
`g:nuwiki_no_default_mappings` 0
    When 1, the Vim path skips every buffer-local keymap. Equivalent to
    `mappings.enabled = false` in Neovim.

                                              *g:nuwiki_no_wiki_prefix_mappings*
                                                    *g:nuwiki_no_links_mappings*
                                                    *g:nuwiki_no_lists_mappings*
                                                  *g:nuwiki_no_headers_mappings*
                                            *g:nuwiki_no_table_editing_mappings*
                                                    *g:nuwiki_no_diary_mappings*
                                              *g:nuwiki_no_html_export_mappings*
                                             *g:nuwiki_no_text_objects_mappings*
`g:nuwiki_no_<group>_mappings` 0
    Per-subgroup opt-outs, each defaulting to 0. Setting one to 1 drops just
    that group's buffer-local keymaps while leaving the rest in place; the
    whole-layer |g:nuwiki_no_default_mappings| still wins over all of them.
    These mirror the Lua-side `mappings.<group>` booleans. Every binding in
    each group (the `<Leader>w` prefix follows |g:nuwiki_map_prefix|):
        `wiki_prefix`     `<Leader>ww`, `<Leader>wt`, `<Leader>ws`,
                          `<Leader>wi`, `<Leader>w<Leader>w`,
                          `<Leader>w<Leader>y`, `<Leader>w<Leader>t`,
                          `<Leader>w<Leader>m`, `<Leader>w<Leader>i`
        `links`           `<CR>`, `<S-CR>`, `<C-CR>`, `<C-S-CR>`, `<D-CR>`,
                          `<M-CR>`, `<BS>`, `<Tab>`, `<S-Tab>`, `+` (n/x),
                          `<Leader>wn`, `<Leader>wd`, `<Leader>wr`,
                          `<Leader>wc` (n/x)
        `lists`           `<C-Space>` (also `<C-@>`/`<Nul>`), `gnt`, `gln`,
                          `glp`, `glx`, `glh`, `gll`, `gLh`, `gLl`, `glr`,
                          `gLr`, `gl-`, `gl*`, `gl#`, `gl1`, `gli`, `glI`,
                          `gla`, `glA`, `gL-`, `gL*`, `gL#`, `gL1`, `gLi`,
                          `gLI`, `gLa`, `gLA`, `gl`, `gL`, `o`, `O`; insert
                          `<C-D>`, `<C-T>`, `<C-L><C-J>`, `<C-L><C-K>`,
                          `<C-L><C-M>`, `<CR>`
        `headers`         `=`, `-`, `]]`, `[[`, `]=`, `[=`, `]u`, `[u`
        `table_editing`   `gqq`, `gq1`, `gww`, `gw1`, `<A-Left>`,
                          `<A-Right>`; insert `<Tab>`, `<S-Tab>`
        `diary`           `<C-Down>`, `<C-Up>`
        `html_export`     `<Leader>wh`, `<Leader>whh`, `<Leader>wha`
        `text_objects`    `ah`, `ih`, `aH`, `iH`, `al`, `il`, `a\`, `i\`,
                          `ac`, `ic`
        `mouse`           `<2-LeftMouse>`, `<S-2-LeftMouse>`,
                          `<C-2-LeftMouse>`, `<MiddleMouse>`, `<RightMouse>`

                                                        *g:nuwiki_map_prefix*
`g:nuwiki_map_prefix`          `'<Leader>w'`
    Prefix for the wiki command family — both the global entry-point maps
    (`<prefix>w`, `<prefix>t`, `<prefix>s`, `<prefix>i`, `<prefix><Leader>{w,y,
    t,m,i}`) and the buffer-local ones (`<prefix>{n,d,r,c,h,hh,ha}`). Mirrors
    vimwiki's `g:vimwiki_map_prefix`. Set it before the plugin loads. Neovim
    users set the `map_prefix` option in `setup()` instead.

                                                          *g:nuwiki_no_folding*
`g:nuwiki_no_folding`          0
    When 1, the Vim path skips `foldexpr` / `foldmethod` setup.

                                                       *g:nuwiki_autowriteall*
`g:nuwiki_autowriteall`        1
    When 1 (default), Vim's global `'autowriteall'` is set while a wiki
    buffer is current and restored on leave, so a modified buffer is
    auto-saved on page switch / `:make`. Mirrors vimwiki's `autowriteall`
    and the Neovim `autowriteall` setup option. Set to 0 to leave
    `'autowriteall'` untouched.

                                                     *g:nuwiki_table_auto_fmt*
`g:nuwiki_table_auto_fmt`      1
    When 1 (default), the table under the cursor is re-aligned on
    |InsertLeave|. Mirrors vimwiki's `table_auto_fmt` and the Neovim
    `table_auto_fmt` setup option. Set to 0 to disable.

                                                     *g:nuwiki_mouse_mappings*
`g:nuwiki_mouse_mappings`      0
    When 1, the Vim path registers mouse keymaps (double-click follows,
    middle-click `:badd`s the link target, etc.). Mirrors
    `mappings.mouse = true` in Neovim.

                                                  *g:nuwiki_build_from_source*
`g:nuwiki_build_from_source`   0
    When 1, the install step always builds the server with `cargo` and
    skips the release-asset download.

                                                         *g:nuwiki_binary_path*
`g:nuwiki_binary_path`
    Override the auto-discovered server binary path. If set and the
    file is readable, it overrides the `{plugin}/bin/nuwiki-ls` default.

==============================================================================
==============================================================================
5. COMMANDS                                                 *nuwiki-commands*

All commands are available in both forms:
- Canonical form: :Nuwiki*
- Vimwiki-compatible form: :Vimwiki*

Every command listed below is registered buffer-logic on `.wiki` files.
Only the `:Nuwiki*` form is shown in this document for brevity.


Wiki / navigation ~

                                                              *:NuwikiIndex*
:NuwikiIndex [{count}]
    Open wiki N's index page (default: 1). Defined globally, so it works
    from any buffer (not just inside a wiki).

                                                           *:NuwikiTabIndex*
:NuwikiTabIndex [{count}]
    Same, in a new tab. Also global.

                                                           *:NuwikiUISelect*
:NuwikiUISelect
    Pick a wiki from a list (multi-wiki only). Uses |vim.ui.select| on
    Neovim, |inputlist()| on Vim.

                                                       *:NuwikiShowVersion*
:NuwikiShowVersion
    Echo the nuwiki version (`g:nuwiki_version`) and the host editor.
    Also available as `:VimwikiShowVersion`.

                                                               *:NuwikiVar*
:NuwikiVar [{key} [{value}]]
    Get/set nuwiki client config. No argument prints the config (Vim:
    every `g:nuwiki_*`; Neovim: the resolved |nuwiki-setup| options); one
    argument prints that key; two or more sets it (server-backed settings
    need a restart to take effect). Also `:VimwikiVar`.

                                                            *:NuwikiReturn*
:NuwikiReturn
    Command form of the smart `<CR>` continuation: continue the current
    list item / table row. Mostly used internally; the insert-mode `<CR>`
    mapping does the same. Also `:VimwikiReturn`.

                                                               *:NuwikiGoto*
:NuwikiGoto {page}
    Open `{page}.wiki` by name.

                                                         *:NuwikiFollowLink*
:NuwikiFollowLink
    Follow the link under the cursor.

                                                          *:NuwikiSplitLink*
:NuwikiSplitLink
                                                         *:NuwikiVSplitLink*
:NuwikiVSplitLink
                                                         *:NuwikiTabnewLink*
:NuwikiTabnewLink
    Follow the link under the cursor in a horizontal split, vertical
    split, or new tab respectively.

                                                        *:NuwikiTabDropLink*
:NuwikiTabDropLink
    Follow the link under the cursor in a tab, reusing an existing tab
    if the target file is already open (otherwise a new tab is created).

                                                         *:NuwikiGoBackLink*
:NuwikiGoBackLink
    Jump back to where you followed the link from (via the jumplist,
    |CTRL-O|).

                                                          *:NuwikiBacklinks*
:NuwikiBacklinks
    Show all references to the current page.

                                                           *:NuwikiNextLink*
:NuwikiNextLink
                                                           *:NuwikiPrevLink*
:NuwikiPrevLink
    Jump to the next / previous wikilink on the page.

                                                           *:NuwikiBaddLink*
:NuwikiBaddLink
    Add the target of the link under the cursor to the buffer list.

                                                         *:NuwikiRenameFile*
:NuwikiRenameFile
    Prompt for a new name; rename the current page and rewrite every
    inbound link.

                                                         *:NuwikiDeleteFile*
:NuwikiDeleteFile
    Delete the current page and its on-disk file.

Diary ~

                                                       *:NuwikiMakeDiaryNote*
:NuwikiMakeDiaryNote
    Open today's diary entry. With `diary_frequency = 'weekly'` (or
    `'monthly'` / `'yearly'`) this addresses this week's / this month's
    / this year's entry instead. The file stems follow:

        daily    YYYY-MM-DD     2026-05-12.wiki
        weekly   YYYY-Www       2026-W19.wiki      (ISO 8601 week)
        monthly  YYYY-MM        2026-05.wiki
        yearly   YYYY           2026.wiki

                                              *:NuwikiMakeYesterdayDiaryNote*
:NuwikiMakeYesterdayDiaryNote
                                               *:NuwikiMakeTomorrowDiaryNote*
:NuwikiMakeTomorrowDiaryNote
    Step the diary back / forward by one period at the configured
    cadence.

                                                          *:NuwikiDiaryIndex*
:NuwikiDiaryIndex
    Open the diary index page.

                                                  *:NuwikiDiaryGenerateLinks*
:NuwikiDiaryGenerateLinks
    Rebuild the diary index page from the entries currently on disk.

                                                        *:NuwikiDiaryNextDay*
:NuwikiDiaryNextDay
                                                        *:NuwikiDiaryPrevDay*
:NuwikiDiaryPrevDay
    Walk to the next / previous indexed diary entry at the same cadence
    as the current one.

Page generation ~

                                                                *:NuwikiTOC*
:NuwikiTOC
    Generate or refresh the table of contents on the current page.

                                                       *:NuwikiGenerateLinks*
:NuwikiGenerateLinks
    Insert a flat list of every page in the wiki under the cursor.

                                                          *:NuwikiCheckLinks*
:[range]NuwikiCheckLinks
    Send every broken link in the workspace to the |quickfix| list. With a
    range (e.g. `:'<,'>NuwikiCheckLinks`) the report is limited to the current
    buffer's selected lines.

                                                         *:NuwikiFindOrphans*
:NuwikiFindOrphans
    List pages with no incoming links in the |quickfix| list.

                                                       *:NuwikiNormalizeLink*
:NuwikiNormalizeLink [0|1]
    Turn the word (or, with arg `1`, the visual selection) under the cursor
    into a wikilink. Backs the `+` mapping.

Tags ~

                                                          *:NuwikiSearchTags*
:NuwikiSearchTags {tag}
    Quickfix listing every `:tag:` occurrence.

                                                    *:NuwikiGenerateTagLinks*
:NuwikiGenerateTagLinks [tag]
    Insert a section linking every page that has `<tag>`. With no
    argument, generates a section per tag found in the workspace.

                                                         *:NuwikiRebuildTags*
:NuwikiRebuildTags[!]
    Re-index the current wiki. With `!`, re-index every configured wiki.

HTML export ~

                                                               *:Nuwiki2HTML*
:Nuwiki2HTML
    Render the current page to HTML.

                                                         *:Nuwiki2HTMLBrowse*
:Nuwiki2HTMLBrowse
    Render the current page and open it in the default browser.

                                                            *:NuwikiAll2HTML*
:NuwikiAll2HTML[!]
    Export every page in the wiki. `!` forces a full rebuild; otherwise
    only out-of-date pages are re-rendered.

                                                                *:NuwikiRss*
:NuwikiRss
    Write `rss.xml` summarising recent diary entries.

Lists, tasks & tables ~

                                                             *:NuwikiNextTask*
:NuwikiNextTask
    Jump to the next unfinished task in the buffer.

                                                         *:NuwikiListToggle*
:NuwikiListToggle
    Toggle a checkbox on the current item, adding `[ ]` if it has none.

                                                      *:NuwikiToggleListItem*
:[range]NuwikiToggleListItem
    Toggle the checkbox under the cursor. With a range, every item in the
    selection.

                                                       *:NuwikiToggleRejected*
:NuwikiToggleRejected
    Toggle the rejected marker `[-]` on the current item.

                                  *:NuwikiIncrementListItem* *:NuwikiDecrementListItem*
:[range]NuwikiIncrementListItem
:[range]NuwikiDecrementListItem
    Cycle the current item's list marker to the next / previous symbol.
    With a range, every item in the selection.

                                  *:NuwikiChangeSymbol* *:NuwikiChangeSymbolInList*
:NuwikiChangeSymbol {sym}
:NuwikiChangeSymbolInList {sym}
    Set the current item's marker to `{sym}` — or every item in the list,
    for the `InList` form.

                                                         *:NuwikiListChangeLvl*
:NuwikiListChangeLvl [increase|decrease]
    Indent (`increase`) or dedent (`decrease`) the current list item.

                                                          *:NuwikiRemoveDone*
:NuwikiRemoveDone[!]
    Remove every completed item from the current list; with `!`, from the
    whole buffer.

                                  *:NuwikiRemoveCheckbox* *:NuwikiRemoveCheckboxInList*
:[range]NuwikiRemoveCheckbox
:NuwikiRemoveCheckboxInList
    Strip the checkbox from the current item (or the range), or from every
    item in the current list for the `InList` form.

                                  *:NuwikiRenumberList* *:NuwikiRenumberAllLists*
:NuwikiRenumberList
:NuwikiRenumberAllLists
    Renumber the current ordered list, or every ordered list in the buffer.

                                                               *:NuwikiTable*
:NuwikiTable {cols} [rows]
    Insert a table with `{cols}` columns (and optional `[rows]`) at the cursor.

                                                          *:NuwikiTableAlign*
:NuwikiTableAlign
    Re-align the current table's columns.

                          *:NuwikiTableMoveColumnLeft* *:NuwikiTableMoveColumnRight*
:NuwikiTableMoveColumnLeft
:NuwikiTableMoveColumnRight
    Move the table column under the cursor left / right.

Other ~

                                                            *:NuwikiColorize*
:[range]NuwikiColorize {color}
    Wrap the word (or the visual selection) under the cursor in a coloured
    `<span>`. `{color}` may be a `color_dic` name or a literal CSS colour.

                                       *:NuwikiPasteLink* *:NuwikiPasteUrl*
:NuwikiPasteLink
:NuwikiPasteUrl
    Paste the clipboard contents as a wikilink, or as a raw URL.

                                                              *:NuwikiCatUrl*
:NuwikiCatUrl
    Echo the `file://` URL of the current page's HTML export.

                                                              *:NuwikiInstall*
:NuwikiInstall
    Install (or re-install) the `nuwiki-ls` binary into the plugin's
    `bin/` directory. Equivalent to running the build hook by hand.

==============================================================================
6. KEYMAPS                                                  *nuwiki-keymaps*

Every keymap is buffer-local. Disable the whole layer via
`mappings.enabled = false` in Neovim, or `let g:nuwiki_no_default_mappings
= 1` in Vim. Drop a single group via `mappings.<group> = false` in Neovim,
or `let g:nuwiki_no_<group>_mappings = 1` in Vim (see
|g:nuwiki_no_links_mappings| for the group list).

Links (normal mode) ~

  <CR>       Smart follow — inside `[[…]]` jumps; on a bare word
             wraps as `[[word]]` (second <CR> follows the link).
  <S-CR>     Follow in a horizontal split.
  <C-CR>     Follow in a vertical split.
  <C-S-CR>   Follow in a tab, reusing an existing tab if the file is
             already open. `<D-CR>` (macOS Cmd) is an alias.
  <M-CR>     Add the link target to the buffer list (`:badd`, no jump).
  <BS>       Jump back (`<C-o>`).
  <Tab>      Next wikilink on or after the cursor.
  <S-Tab>    Previous wikilink.
  +          Wrap word (or visual selection) as `[[word]]`. No follow.

Lists (normal mode) ~

  <C-Space>  Toggle the checkbox under the cursor. Also bound to <C-@>
             and <Nul> to cover terminal byte differences.
  gln        Cycle the checkbox state forward.
  glp        Cycle the checkbox state backward.
  glx        Toggle the rejected marker `[-]`.
  gnt        Jump to the next unfinished task.
  glh        Dedent the current list item.
  gll        Indent the current list item.
  gLh        Dedent the item including its sublist.  (alias: gLH)
  gLl        Indent the item including its sublist.  (alias: gLL)
  glr        Renumber the current ordered list.
  gLr        Renumber every ordered list in the buffer.  (alias: gLR)
  gl<sym>    Set the current item's marker to <sym>, where <sym> is one
             of `-` `*` `#` `1` (1.) `i` (i)) `I` (I)) `a` (a)) `A` (A)).
             For `1)` use `:NuwikiChangeSymbol 1)` (no single-key form).
  gL<sym>    Set every item in the list to <sym> (same symbol keys).
  gl         Remove the checkbox from the current item, keeping its text.
  gL         Remove the checkbox from every item in the current list.
             Bare `gl`/`gL` share the `gl...` prefix above, so (like
             upstream vimwiki) they fire only after 'timeoutlen'; type a
             suffix such as `gln`/`gl*` quickly to reach the prefixed maps.
             Removing done items is command-only: `:NuwikiRemoveDone`
             (current list) / `:NuwikiRemoveDone!` (whole buffer).
  o          Open a new line and continue the list marker (preserves
             any checkbox).
  O          Same, opening above the current line.

Headers ~

  =          Increase the heading level under the cursor.
  -          Decrease the heading level.
  ]]         Next heading (any level).
  [[         Previous heading.
  ]=         Next sibling heading.
  [=         Previous sibling heading.
  ]u         Jump to the parent heading.
  [u         Same — alternate binding.

Tables (normal mode) ~

  gqq        Align the table under the cursor. Also `gq1`, `gww`, `gw1`.
  <A-Left>   Move the column under the cursor left.
  <A-Right>  Move the column under the cursor right.

Wiki / diary / export ~

The `<Leader>w` prefix below is the default |map_prefix| / |g:nuwiki_map_prefix|;
set that option to relocate the whole family.

  <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    Today.
  <Leader>w<Leader>y    Yesterday.
  <Leader>w<Leader>t    Today, in a new tab.
  <Leader>w<Leader>m    Tomorrow.
  <Leader>w<Leader>i    Rebuild the diary index page.
  <Leader>wn            Goto page (prompts for name).
  <Leader>wd            Delete the current page.
  <Leader>wr            Rename the current page.
  <Leader>wh            Export the current page to HTML.
  <Leader>whh           Export and open in the browser.
  <Leader>wha           Export every page.
  <Leader>wc            Wrap word / selection in a colour span.
  <C-Down>              Next diary entry.
  <C-Up>                Previous diary entry.

Mouse (opt-in via |g:nuwiki_mouse_mappings|) ~

  <2-LeftMouse>     Follow the link clicked.
  <S-2-LeftMouse>   Follow in a horizontal split.
  <C-2-LeftMouse>   Follow in a vertical split.
  <MiddleMouse>     Add the link target to the buffer list.
  <RightMouse>      Jump back (`<C-o>`).

==============================================================================
7. TEXT OBJECTS                                         *nuwiki-text-objects*

Operator-pending + visual. Disable via `mappings.text_objects = false`.

  ah         A heading section — the heading line and everything up to
             the next heading at any level.
  ih         Same, but excluding the heading line itself.
  aH         A heading section plus every subheading underneath — stops
             at the next heading of same-or-shallower level.
  iH         Same, but excluding the heading line.
  al         The list item under the cursor.
  il         Same, but excluding the marker / checkbox prefix.
  a\         The table cell under the cursor (includes the trailing `|`).
  i\         Same, content only — no surrounding `|`s or padding.
  ac         The table column under the cursor (includes the header
             separator row).
  ic         Same, content cells only.

==============================================================================
8. INSERT-MODE BINDINGS                                  *nuwiki-insert-mode*

Smart return ~

`<CR>` is bound to a smart helper that does the right thing depending
on context:

  * On a list item with content — continue the list with the same marker
    on a new line. Preserves a leading checkbox if present.
  * On an empty list item (marker only) — clear the marker and break
    out of the list with a plain newline.
  * Inside a `|…|` table row — insert a fresh empty row below with the
    same column count; cursor lands inside the first cell.
  * Otherwise — plain `<CR>`.

Table cell navigation ~

  <Tab>      Jump to the next cell. Past the last cell, insert a fresh
             row below and land in its first cell.
  <S-Tab>    Jump to the previous cell.

Outside a table row both pass through to their default insert-mode
behaviour (literal tab / shift-tab).

List editing ~

  <C-D>          Dedent the current list item.
  <C-T>          Indent the current list item.
  <C-L><C-J>     Cycle the marker forward through the canonical run:
                   `-` → `*` → `#` → `1.` → `1)` → `a)` → `A)` → `i)` → `I)`
  <C-L><C-K>     Cycle the marker backward.
  <C-L><C-M>     Toggle the checkbox on the current item, or insert
                 `[ ]` after the marker when there isn't one.

==============================================================================
9. DIARY                                                       *nuwiki-diary*

The diary holds dated entries under `<wiki_root>/<diary_rel_path>/` —
`diary/` by default.

Frequencies ~

The `diary_frequency` per-wiki option controls the cadence:

  daily     YYYY-MM-DD       e.g. `2026-05-12.wiki`  (default)
  weekly    YYYY-Www         ISO 8601 week, e.g. `2026-W19.wiki`
  monthly   YYYY-MM          e.g. `2026-05.wiki`
  yearly    YYYY             e.g. `2026.wiki`

For weekly diaries, `diary_weekly_style` chooses the file name: the default
`'iso'` uses the ISO-week label above (always Monday-based); `'date'` (a.k.a.
`'vimwiki'`) names the file after the week-start day's date — e.g. with
`diary_start_week_day = 'monday'`, the week of 2026-05-27 is `2026-05-25.wiki`
— matching upstream vimwiki. `diary_start_week_day` (`'monday'`..`'sunday'`)
only applies in `'date'` mode.

`:NuwikiMakeDiaryNote` opens the entry for the current period at the
configured cadence; the yesterday / tomorrow commands step back and
forward by one period. `<C-Down>` / `<C-Up>` walk between indexed
entries of the same flavour as the one under the cursor — so on a
weekly page, navigation stays weekly.

Index ~

`:NuwikiDiaryGenerateLinks` rebuilds the diary index page (`diary.wiki`
by default) with a chronological list of every entry on disk, grouped
by year / month. The page name is set by `diary_index`; the heading is
set by `diary_header`.

==============================================================================
10. TABLES                                                    *nuwiki-tables*

Tables use vimwiki's pipe syntax: >

  | Name  | Score |
  |-------|-------|
  | Alice |    97 |
  | Bob   |    72 |

<Alignment markers on the header separator row follow Markdown
conventions:

  `|:---|`     left-align
  `|---:|`     right-align
  `|:---:|`    centre-align

A cell containing just `>` merges with the cell to its left (colspan);
a cell containing just `\/` merges with the cell directly above
(rowspan). The HTML renderer emits proper `colspan="N"` / `rowspan="N"`
attributes plus `style="text-align: …;"` per cell when alignment is
specified.

See |nuwiki-keymaps| for the table-editing shortcuts (alignment,
column moves, cell navigation, new-row insertion).

==============================================================================
11. HTML EXPORT                                                 *nuwiki-html*

`:Nuwiki2HTML` renders the current page; `:Nuwiki2HTMLBrowse` opens
the result in the default browser; `:NuwikiAll2HTML` exports every
page (incremental by default; `!` forces a full rebuild).

Per-wiki knobs:

  `html_path`           Output directory (created if missing).
  `template_path`       Where to find `<name>.tpl` files.
  `template_default`    Default template name (without extension).
  `template_ext`        Template file extension (default `.tpl`).
  `css_name`            CSS file copied into `html_path`.
  `auto_export`         When `true`, exports on every save.
  `exclude_files`       Glob patterns excluded from export.

Templates may include `{title}`, `{rootpath}`, `{content}`, `{css}`,
`{date}` placeholders. RSS for the diary is written by `:NuwikiRss`.

==============================================================================
12. FOLDING                                                  *nuwiki-folding*

Folds follow the heading outline: each `= H1 =` opens a level-1 fold,
each `== H2 ==` opens a level-2 fold, etc. Folds close at the next
heading of same-or-shallower level.

Neovim picks between two providers based on the `folding` setup option:

  `'lsp'`   Server-driven `foldingRange` (Neovim 0.11+ wires it
            automatically; the editor falls back to the regex variant
            if the server isn't yet attached).
  `'expr'`  Regex `foldexpr` over `getline()` — no server roundtrip.
  `'off'`   No folding setup.

Vim users get the regex variant via `nuwiki#folding#expr()` unless
|g:nuwiki_no_folding| is set.

==============================================================================
13. HEALTH CHECK                                              *nuwiki-health*

                                                          *:checkhealth-nuwiki*
Neovim users can run: >

  :checkhealth nuwiki

<This reports:

  * Whether the binary exists and responds to `--version`.
  * Whether `wiki_root` exists.
  * Whether the `.wiki` filetype is registered (`vimwiki`).
  * Whether an LSP client is currently attached.
  * Which `executeCommand` handlers the server advertised.

Vim users without `:checkhealth` can run `:LspStatus` (vim-lsp) or
`:CocCommand workspace.showOutput` (coc.nvim).

==============================================================================
14. MIGRATING FROM VIMWIKI                                 *nuwiki-migrating*

The file extension, syntax, command names, and default keymaps all
match vimwiki. To migrate:

  1. Drop the original `vimwiki` plugin from your config.
  2. Install nuwiki.
  3. Point `wiki_root` (or each `wikis[i].root`) at your existing
     directory.

Existing pages, diary entries, tags, and templates work without
modification. The first workspace scan after launch may show an empty
`:NuwikiCheckLinks` result until the background index completes;
subsequent runs are instant.

 vim:tw=78:ts=8:ft=help:norl: