# 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",
  opts = {
    -- Wiki directories (REQUIRED - configure at least one)
    dirs = {{ name = 'default', path = '~/wiki' }},
  },
  -- No defaults, add your own:
  keys = {
    { "<leader>ww", function() require("muwiki").open_index("default") end, desc = "Open wiki index" },
    { "<CR>", function() require("muwiki").open_link() end, ft = "markdown", desc = "Open wiki link" },
    { "<Tab>", function() require("muwiki").next_link() end, ft = "markdown", desc = "Next wiki link" },
    { "<S-Tab>", function() require("muwiki").prev_link() end, ft = "markdown", desc = "Previous wiki link" },
    { "<CR>", function() require("muwiki").create_link() end, ft = "markdown", mode = "v", desc = "Create wiki link from selection" },
  },
}
```

## Keymaps

Configure keymaps using lazy.nvim's `keys` option or set them up manually:

**Keymaps (lazy.nvim):**
```lua
keys = {
  { "<CR>", function() require("muwiki").open_link() end, ft = "markdown" },
  { "<Tab>", function() require("muwiki").next_link() end, ft = "markdown" },
  { "<S-Tab>", function() require("muwiki").prev_link() end, ft = "markdown" },
  { "<CR>", function() require("muwiki").create_link() end, ft = "markdown", mode = "v" },
}
```

**Manual setup (for other plugin managers):**
```lua
-- Set up your own autocmds
vim.api.nvim_create_autocmd('BufEnter', {
  pattern = '*.md',
  callback = function()
    vim.keymap.set('n', '<CR>', require('muwiki').open_link, { buffer = true })
    vim.keymap.set('n', '<Tab>', require('muwiki').next_link, { buffer = true })
    vim.keymap.set('n', '<S-Tab>', require('muwiki').prev_link, { buffer = true })
    vim.keymap.set('v', '<CR>', require('muwiki').create_link, { buffer = true })
  end,
})
```

Note: Actions check if the buffer is within a configured wiki directory and do nothing if not.

**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.

## Automatic Directory Creation

Automatically create missing parent directories when creating wiki files with nested paths:

```lua
-- Example: [Project notes](projects/myapp/notes.md)
-- Will create projects/myapp/ directory if it doesn't exist

create_missing_dirs = 'notify',  -- or 'silent', 'prompt', or false (default)
```

**Options:**

- `false` - Don't create directories (default)
- `true` or `'notify'` - Create directories and show notification
- `'silent'` - Create directories without notification
- `'prompt'` - Ask before creating directories

**Security:** Directories are only created within your configured wiki root directories.

## 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.