neowiki.nvim

Full-featured minimalist Vimwiki Successor for Instant Notes & GTD 🚀📝

---

🌟 Introduction

neowiki.nvim is a lightweight, first-class Neovim citizen with Lua finesse, offering a minimal, intuitive workflow out of the box for note-taking and Getting Things Done (GTD).

🔥 Key Features

• Flexible Wiki Access 🪟
  Open wikis your way—in the current buffer, a new tab, or a distraction-free floating window for focused note-taking.

• Effortless Linking & Navigation 🔗
  Create and follow markdown links with <CR>, split with <S-CR> or <C-CR>, and jump between links using <Tab>/<S-Tab>. Navigate page history like a browser with [[ and ]], or return to index.md with <BS>.

• Smart Task Management ✅
  Toggle tasks with <leader>wt ([ ] ↔ [x]) and track nested task progress in real-time with dynamic updates.

• Robust Wiki Organization 📂
  Manage multiple wikis (e.g., work, personal) with automatic discovery of nested index.md files. Easily insert, rename, or delete wiki pages with automatic backlink updates.

• Neovim-Powered Efficiency ⚙️
  Built for Neovim 0.10+, leveraging Lua for speed and seamless integration with other plugins: Treesitter, markdown rendering, completion, pickers, and your existing config.

📷 Quick Peek

neowiki.nvim features in action.

🛠️ Getting Started

Requires Neovim >= 0.10. For the best experience, install Treesitter’s markdown and markdown_inline parsers.

Tip: After installation, run :checkhealth neowiki to verify your environment, dependencies, and configuration paths.

Using Lazy.nvim

{
  "echaya/neowiki.nvim",
  opts = {
    wiki_dirs = {
      -- neowiki.nvim supports both absolute and tilde-expanded paths
      { name = "Work", path = "~/work/wiki" },
      { name = "Personal", path = "personal/wiki" },
    },
  },
  keys = {
    { "<leader>ww", "<cmd>lua require('neowiki').open_wiki()<cr>", desc = "Open Wiki" },
    { "<leader>wW", "<cmd>lua require('neowiki').open_wiki_floating()<cr>", desc = "Open Wiki in Floating Window" },
    { "<leader>wT", "<cmd>lua require('neowiki').open_wiki_new_tab()<cr>", desc = "Open Wiki in Tab" },
  },
}

Using Mini.deps

require("mini.deps").add("echaya/neowiki.nvim")
require("neowiki").setup()
vim.keymap.set("n", "<leader>ww", require("neowiki").open_wiki, { desc = "Open Wiki" })
vim.keymap.set("n", "<leader>wW", require("neowiki").open_wiki_floating, { desc = "Open Floating Wiki" })
vim.keymap.set("n", "<leader>wT", require("neowiki").open_wiki_new_tab, { desc = "Open Wiki in Tab" })

Using Vim-Plug

Plug 'echaya/neowiki.nvim'
lua require('neowiki').setup()
lua vim.keymap.set("n", "<leader>ww", require("neowiki").open_wiki, { desc = "Open Wiki" })
lua vim.keymap.set("n", "<leader>wW", require("neowiki").open_wiki_floating, { desc = "Open Floating Wiki" })
lua vim.keymap.set("n", "<leader>wT", require("neowiki").open_wiki_new_tab, { desc = "Open Wiki in Tab" })

🚀 Optional Dependencies

File Search

neowiki.nvim enhances file searching with modern command-line tools for optimal performance. While optional, installing them is highly recommended for efficient page listing and backlink updates. If none are found, the plugin falls back to a native Lua search.

• ripgrep (rg): The primary search tool. It is required for global backlink search when renaming or deleting pages. Without rg, backlink updates will search a limited scope.
• fd: A fast file finder, used as the second choice if rg is not available for listing pages.
• git: If rg and fd are unavailable, git ls-files is used as a fallback for finding files within a git repository.

Functional Enhancements

• nvim-treesitter: Strongly recommended. neowiki.nvim uses the markdown and markdown_inline parsers to robustly detect and parse links, ensuring that links inside code blocks or other ignored regions are handled correctly.

• vim-repeat: Enables repeating GTD actions (e.g., task creation and completion with <leader>wt) using the dot (.) command.

📝 Usage

Quick Start

1. Open Wiki: Use <leader>ww, <leader>wW, or <leader>wT to start.
2. Create Note: Select text (e.g., “My Project”), press <CR> to create [My Project](./My_Project.md) and open it.
3. Manage Tasks: Use <leader>wt on a task line to toggle its status. Progress (e.g., [ 75% ]) will be displayed for parent items.
4. Navigate: Use <Tab>/<S-Tab> to jump between links, <BS> to return to the index.md, or <leader>wr to rename a page and update its links.
5. Save: Simply :w.

Example Wiki Index

# My Epic Wiki 🎉
- [Tasks](./Tasks.md) - Where productivity meets chaos!
- [Ideas](./Ideas.md) - Brainstorming central, no judgment zone.
- Next Big Thing
    - [ ] Release neowiki setup - Halfway to glory! [ 50% ]
      - [x] Crafted README - Checkmate!
      - [x] Snap screenshots - clack-clack-clack
      - [ ] Grand release - booking concert hall, Musikverein
      - [ ] Reach 1000 stars - designing a bot to help with that

Nested Wiki Example

# Work Wiki ⚡
- [Team Notes](./team/index.md) - The squad’s brain trust.
- [Project Plan](./plan.md) - Blueprint to world domination.

⌨️ Default Keybindings

The following keymaps are buffer-local and only active in markdown files within a configured wiki directory.

| Mode | Key | Action | Description | | --- | --- | --- | --- | | Normal | <CR> | Follow link | Open link under cursor | | Visual | <CR> | Create link | Create link from selection | | Normal | <S-CR> | Follow link (vsplit) | Open link in vertical split | | Visual | <S-CR> | Create link (vsplit) | Create link, open in vertical split | | Normal | <C-CR> | Follow link (split) | Open link in horizontal split | | Visual | <C-CR> | Create link (split) | Create link, open in horizontal split | | Normal | <Tab> | Next link | Navigate to next link | | Normal | <S-Tab> | Previous link | Navigate to previous link | | Normal | [[ | Navigate back | Go back in browsing history | | Normal | ]] | Navigate forward | Go forward in browsing history | | Normal | <Backspace> | Jump to index | Open the current wiki’s index.md | | Normal | <leader>wt | Toggle task | Create or toggle task status on the line | | Visual | <leader>wt | Toggle tasks | Bulk create or toggle tasks in selection | | Normal | <leader>wd | Delete page | Delete current or linked page | | Normal | <leader>wr | Rename page | Rename current or linked page | | Normal | <leader>wi | Insert link | Find and insert a link to a wiki page | | Normal | <leader>wc | Clean broken links | Remove broken links from the current page | | Normal | q | Close float | Close the floating wiki window |

⚙️ Default Configuration

Below is the default configuration for neowiki.nvim. You don’t need to copy all settings; just override the options you want to change in your setup() call.

require("neowiki").setup({
  -- A list of tables, where each table defines a wiki.
  -- Both absolute and tilde-expanded paths are supported.
  -- If this is nil, the plugin defaults to `~/wiki`.
  -- Example:
  -- wiki_dirs = {
  --   { name = "Work", path = "~/Documents/work-wiki" },
  --   { name = "Personal", path = "personal-wiki" },
  -- }
  wiki_dirs = nil,

  -- The filename for a wiki's index page (e.g., "index.md").
  index_file = "index.md",

  -- Automatically discover and register nested wiki roots.
  discover_nested_roots = false,

  -- Defines the keymaps used by neowiki.
  -- Setting a keymap to `false` or an empty string will disable it.
  keymaps = {
    -- In Normal mode, follows the link under the cursor.
    -- In Visual mode, creates a link from the selection.
    action_link = "<CR>",
    action_link_vsplit = "<S-CR>",
    action_link_split = "<C-CR>",

    -- Jumps to the next link in the buffer.
    next_link = "<Tab>",
    -- Jumps to the previous link in the buffer.
    prev_link = "<S-Tab>",
    -- Navigate back and forth in history.
    navigate_back = "[[",
    navigate_forward = "]]",
    -- Jumps to the index page of the current wiki.
    jump_to_index = "<Backspace>",

    -- Renames the current wiki page and updates backlinks.
    rename_page = "<leader>wr",
    -- Deletes the current wiki page and updates backlinks.
    delete_page = "<leader>wd",
    -- Inserts a link to another wiki page.
    insert_link = "<leader>wi",
    -- Removes all links in the current file that point to non-existent pages.
    cleanup_links = "<leader>wc",

    -- Toggles the status of a gtd item.
    -- Works on the current line in Normal mode and on the selection in Visual mode.
    toggle_task = "<leader>wt",

    -- Closes the floating window.
    close_float = "q",
  },

  -- Configuration for the GTD functionality.
  gtd = {
    -- Set to false to disable the progress percentage virtual text.
    show_gtd_progress = true,
    -- The highlight group to