muwiki.nvim

A lightweight wiki plugin for Neovim using standard markdown syntax.

Requirements

Neovim v0.10+
Treesitter markdown parsers (:TSInstall markdown markdown_inline)

Features

Standard markdown links [text](url)
Link navigation and xdg-open for web/file links
Multiple wiki directories
Hierarchical checkbox toggling for TODO list
Extensible via autocmds (mkdir, templates, custom handlers)

See :help muwiki for complete documentation and configuration options.

Installation

Using vim.pack (Neovim 0.12+)

vim.pack.add({
  { src = "https://git.3kgcat.fi/muwiki.nvim", name = "muwiki" },
  { src = "https://github.com/nvim-treesitter/nvim-treesitter" },
})

Using lazy.nvim

{
  url = "https://git.3kgcat.fi/muwiki.nvim",
  dependencies = { "nvim-treesitter/nvim-treesitter" },
  keys = {
    { "<leader>ww", function() require("muwiki").open_index("default") end, desc = "Open wiki index" },
  },
  opts = {
    dirs = {{ name = 'default', path = '~/wiki' }},
  },

  config = function(_, opts)
    local muwiki = require('muwiki')
    muwiki.setup(opts)

    local group = vim.api.nvim_create_augroup("muwiki", { clear = true })

    vim.api.nvim_create_autocmd("FileType", {
      group = group,
      pattern = "markdown",
      callback = function(ev)
        if not muwiki.wiki_root(ev.buf) then return end
        local keymap_opts = { buffer = ev.buf, silent = true, nowait = true }
        keymap_opts.desc = "Open link"
        vim.keymap.set('n', '<CR>', muwiki.open_link, keymap_opts)
        keymap_opts.desc = "Next link"
        vim.keymap.set('n', '<Tab>', muwiki.next_link, keymap_opts)
        keymap_opts.desc = "Previous link"
        vim.keymap.set('n', '<S-Tab>', muwiki.prev_link, keymap_opts)
        keymap_opts.desc = "Create link"
        vim.keymap.set('v', '<CR>', muwiki.create_link, keymap_opts)
        keymap_opts.desc = "Toggle checkbox"
        vim.keymap.set('n', '<S-t>', muwiki.toggle_checkbox, keymap_opts)
      end,
    })
  end,

}

Quick Start

Add this to your config for basic wiki functionality:

local muwiki = require('muwiki')

-- Configure wiki directories
muwiki.setup({
  dirs = {{ name = 'default', path = '~/wiki' }},
})

-- Quick access to wiki index
vim.keymap.set('n', '<leader>ww', function()
  muwiki.open_index("default")
end, { desc = "Open wiki index" })

-- Keymaps for wiki navigation (only active in wiki files)
vim.api.nvim_create_autocmd("FileType", {
  pattern = "markdown",
  callback = function(args)
    if not muwiki.wiki_root(args.buf) then return end

    local keymap_opts = { buffer = args.buf, silent = true }
    keymap_opts.desc = "Open link"
    vim.keymap.set('n', '<CR>', muwiki.open_link, keymap_opts)
    keymap_opts.desc = "Next link"
    vim.keymap.set('n', '<Tab>', muwiki.next_link, keymap_opts)
    keymap_opts.desc = "Previous link"
    vim.keymap.set('n', '<S-Tab>', muwiki.prev_link, keymap_opts)
    keymap_opts.desc = "Create link"
    vim.keymap.set('v', '<CR>', muwiki.create_link, keymap_opts)
    keymap_opts.desc = "Toggle checkbox"
    vim.keymap.set('n', '<S-t>', muwiki.toggle_checkbox, keymap_opts)
  end,
})

-- Auto-create directories when saving new files
vim.api.nvim_create_autocmd("BufWritePre", {
  pattern = "*.md",
  callback = function(args)
    local wiki_root = muwiki.wiki_root(args.buf)
    if not wiki_root then return end
    local dir = vim.fn.fnamemodify(args.file, ":h")
    if vim.fn.isdirectory(dir) == 0 then
      vim.fn.mkdir(dir, "p")
    end
  end,
})

See :help muwiki-autocmd for more examples.

Configuration

Example:

muwiki.setup({
  dirs = {{ name = 'default', path = '~/wiki' }},
  -- Open matching file:// links in Neovim instead of xdg-open
  text_extensions = { 'txt', 'md', 'png' },
})

This allows you to open binary files like PNG images directly in Neovim for hex editing or inspection instead of xdg-open.

Behavior:

[Link](https://example.com) → xdg-open (web)
[Link](file:///path/to/file.mp4) → xdg-open (file)
[Link](file://../relative/path/to/image.png) → neovim (file with text_extensions match)
[Link](SomePage.md) → neovim (wiki)

See :help muwiki-configuration for all options.

Available Actions

open_link() - Open link under cursor
next_link() - Jump to next markdown link
prev_link() - Jump to previous markdown link
create_link() - Create link from visual selection
get_link() - Get link info at cursor
open_index(name) - Open wiki index file
open_with_menu(handlers) - Open link with selectable handler
toggle_checkbox() - Toggle checkbox and all children (useful for todo lists)

See :help muwiki-api for detailed function documentation.

Recommended Plugins

These plugins work well with muwiki.nvim:

render-markdown.nvim - Improve markdown rendering in Neovim
outline.nvim - Navigate document structure with symbols outline
table-nvim - Edit markdown tables

See :help muwiki for full documentation.