*muwiki* *muwiki.nvim*  A lightweight wiki plugin for Neovim

==============================================================================
CONTENTS                                                     *muwiki-contents*

1. Introduction ............................................ |muwiki-intro|
2. Requirements ............................................ |muwiki-requirements|
3. Installation ............................................ |muwiki-installation|
4. Configuration ........................................... |muwiki-configuration|
5. Commands & Functions .................................... |muwiki-commands|
6. Lua API ................................................. |muwiki-api|
7. Autocommands & Recipes .................................. |muwiki-autocmd|
   7.1 Auto-create directories ............................. |muwiki-autocmd-mkdir|
   7.2 Add template for new files .......................... |muwiki-autocmd-template|
   7.3 Open with menu examples ............................. |muwiki-autocmd-open-with|
8. Health Check ............................................ |muwiki-health|

==============================================================================
1. INTRODUCTION                                                 *muwiki-intro*

MuWiki is a lightweight wiki plugin for Neovim using standard markdown syntax.
It provides:

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

==============================================================================
2. REQUIREMENTS                                           *muwiki-requirements*

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

==============================================================================
3. INSTALLATION                                           *muwiki-installation*

Using vim.pack (Neovim 0.12+)~
>
  vim.pack.add({
    { src = "https://git.3kgcat.fi/muwiki.nvim" }
  })
<

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

==============================================================================
4. CONFIGURATION                                         *muwiki-configuration*

The plugin is configured using the |muwiki.setup()| function.

Configuration Options~

                                                    *muwiki-opt-dirs*
dirs                    List of wiki directories.
                        Each entry is a table with:
                        - name: Wiki name for reference
                        - path: Absolute path to wiki directory
                        Default: nil

                                                    *muwiki-opt-index_file*
index_file              Name of the index file for each wiki.
                        Default: 'index.md'

Example Configuration~
>
  local muwiki = require('muwiki')

  muwiki.setup({
    dirs = {
      { name = 'default', path = '~/wiki' },
      { name = 'work', path = '~/work/wiki' },
    },
    index_file = 'index.md',
  })
<

==============================================================================
5. COMMANDS & FUNCTIONS                                     *muwiki-commands*

Keymaps should be configured by the user. Here are recommended keymaps:
>
  -- 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 opts = { buffer = args.buf, silent = true }
      vim.keymap.set('n', '<CR>', muwiki.open_link, opts)
      vim.keymap.set('n', '<Tab>', muwiki.next_link, opts)
      vim.keymap.set('n', '<S-Tab>', muwiki.prev_link, opts)
      vim.keymap.set('v', '<CR>', muwiki.create_link, opts)
    end,
  })
<

Link Format~
>
  [Wiki page](page.md)
  [Website](https://example.com)
  [Relative path](file://../document.pdf)
  [Absolute path](file:///tmp/image.png)
<

==============================================================================
6. LUA API                                                       *muwiki-api*

muwiki.setup({opts})                                   *muwiki.setup()*
    Configure the plugin. See |muwiki-configuration| for options.

muwiki.open_link()                                     *muwiki.open_link()*
    Open the link under cursor.
    - Wiki links: open in Neovim buffer
    - Web links: open with xdg-open
    - File links: open with xdg-open

muwiki.next_link()                                     *muwiki.next_link()*
    Jump to the next markdown link in the buffer.

muwiki.prev_link()                                     *muwiki.prev_link()*
    Jump to the previous markdown link in the buffer.

muwiki.create_link()                                   *muwiki.create_link()*
    Create a link from visual selection. In visual mode, select text and
call this function to convert it to a markdown link. The text will be
normalized to create a filename (lowercase, spaces to underscores).

muwiki.get_link()                                      *muwiki.get_link()*
    Get information about the link under cursor.
    Returns a table with:
    - text: Link display text
    - target: Link destination
    - type: Link type ('web', 'file', or 'wiki')

muwiki.open_with_menu({handlers}, {link})              *muwiki.open_with_menu()*
    Open link with a selectable handler from a menu.
    {handlers} is a list of handler tables:
>
    {
      name = "Handler Name",
      cmd = "command" or function(url),
      exts = {"pdf", "doc"}  -- optional file extensions
    }
<
    {link} is optional; if not provided, gets link under cursor.

muwiki.open_index({name})                              *muwiki.open_index()*
    Open the index file of a wiki by name.
    {name} is the wiki name from configuration.

muwiki.wiki_root({bufnr})                              *muwiki.wiki_root()*
    Get the wiki root directory for a buffer.
    Returns the path or nil if buffer is not in a wiki.

==============================================================================
7. AUTOCOMMANDS & RECIPES                                   *muwiki-autocmd*

Auto-create directories when saving~                                  *muwiki-autocmd-mkdir*
>
  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,
  })
<

Add template for new files~                                           *muwiki-autocmd-template*
>
  vim.api.nvim_create_autocmd("BufNewFile", {
    pattern = "*.md",
    callback = function(args)
      local wiki_root = muwiki.wiki_root(args.buf)
      if not wiki_root then return end

      local filename = vim.fn.fnamemodify(args.file, ":t:r")
      local template = string.format("# %%s\n\n", filename)
      vim.api.nvim_buf_set_lines(args.buf, 0, 0, false, vim.split(template, "\n"))
    end,
  })
<

Open with menu example~                                               *muwiki-autocmd-open-with*
>
  vim.api.nvim_create_autocmd("FileType", {
    pattern = "markdown",
    callback = function(args)
      if not muwiki.wiki_root(args.buf) then return end
      vim.keymap.set('n', '<leader>o', function()
        muwiki.open_with_menu({
          { name = "Zathura", cmd = "zathura", exts = {"pdf"} },
          { name = "swayimg", cmd = "swayimg", exts = {"png", "jpg", "jpeg", "gif", "webp"} },
          { name = "mpv", cmd = "mpv", exts = {"mp4", "mkv", "avi", "mov", "webm"} },
          { name = "xdg-open", cmd = "xdg-open" },
        })
      end, { buffer = args.buf, desc = "Open with..." })
    end,
  })
<

==============================================================================
8. HEALTH CHECK                                                  *muwiki-health*

Run |:checkhealth muwiki| to verify:
- Wiki directories are configured and exist
- Treesitter markdown parser is installed
- Treesitter markdown_inline parser is installed

==============================================================================
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

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