# 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)`
- Multiple wiki directories
- External link handlers
- Automatic template for new page
- Link navigation with custom keymaps

See `:help muwiki` for complete documentation and configuration options.

## Installation

Using [lazy.nvim](https://github.com/folke/lazy.nvim):

```lua
{
  url = "https://git.3kgcat.fi/muwiki.nvim",
  keys = {
    { "<leader>ww", function() require("muwiki").open_index("default") end, desc = "Open wiki index" },
  },
  opts = {
    -- Wiki directories (REQUIRED - configure at least one)
    dirs = {{ name = 'default', path = '~/wiki' }},
  },

  -- autogroup only loads keymaps in wiki files
  config = function(_, opts)
    local muwiki = require('muwiki')
    muwiki.setup(opts)

    local group = vim.api.nvim_create_augroup("MuWikiKeymaps", { 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 }
        vim.keymap.set('n', '<CR>', muwiki.open_link, keymap_opts)
        vim.keymap.set('n', '<Tab>', muwiki.next_link, keymap_opts)
        vim.keymap.set('n', '<S-Tab>', muwiki.prev_link, keymap_opts)
        vim.keymap.set('v', '<CR>', muwiki.create_link, keymap_opts)
        vim.keymap.set('n', '<leader>oo', muwiki.open_link_with, keymap_opts)
      end,
    })
  end,
}
```

**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
- `open_link_with()` - Open link with custom external handler

See `:help muwiki-commands` for complete API documentation.

## Link Format

```text
[Wiki page](page.md)
[Website](https://example.com)
[Relative path](file://../document.pdf)
[Absolute path](file:///tmp/image.png)
```

## External Handlers

Define custom handlers for opening external URLs and files:

```lua
external_handlers = {
  -- Open HTTP/HTTPS URLs in Firefox
  {
    name = 'Firefox',
    cmd = 'firefox',
    pattern = '^https?://',
  },
  -- Open videos with mpv (local files and YouTube)
  {
    name = 'mpv',
    cmd = 'mpv',
    pattern = {
      '%.mp4$',
      '%.mkv$',
      '%.avi$',
      '%.webm$',
      'youtube%.com',
      'youtu%.be',
    },
  },
  -- Open images with swayimg
  {
    name = 'swayimg',
    cmd = 'swayimg',
    pattern = {
      '%.png$',
      '%.jpe?g$',
      '%.gif$',
      '%.webp$',
      '%.bmp$',
    },
  },
  -- Copy URL to clipboard using wl-copy
  {
    name = 'Copy URL',
    cmd = function(url)
      vim.system({ 'wl-copy', url }, { detach = true })
      vim.notify('URL copied to clipboard', vim.log.levels.INFO)
    end,
    pattern = '.*',
  },
  -- Fallback for any URL (Linux)
  {
    name = 'xdg-open',
    cmd = 'xdg-open',
    pattern = '.*',
  },
}
```

**Handler properties:**

- `name` - Display name in the handler menu
- `cmd` - Command string or Lua function
- `pattern` - Lua pattern(s) to match URLs (string or table of strings; optional, matches all if omitted)

**Note:** Files with extensions in `text_extensions` will always open in Neovim, bypassing external handlers.

## Recommended Plugins

These plugins work well with muwiki.nvim:

- [render-markdown.nvim](https://github.com/MeanderingProgrammer/render-markdown.nvim) - Improve markdown rendering in Neovim
- [outline.nvim](https://github.com/hedyhli/outline.nvim) - Navigate document structure with symbols outline

See `:help muwiki` for full documentation.