1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
|
# 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.
|
