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_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).

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

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

                                                               *: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.
  gLl        Indent the item including its sublist.
  glr        Renumber the current ordered list.
  gLr        Renumber every ordered list in the buffer.
  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: