From bc2944651f4dabc68d7f34c796400d80ba132016 Mon Sep 17 00:00:00 2001 From: moxie Date: Fri, 13 Mar 2026 09:58:53 +0200 Subject: chore: init --- README.md | 186 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 186 insertions(+) create mode 100644 README.md (limited to 'README.md') diff --git a/README.md b/README.md new file mode 100644 index 0000000..02f4f37 --- /dev/null +++ b/README.md @@ -0,0 +1,186 @@ +# muwiki.nvim + +A lightweight wiki plugin for Neovim using standard markdown syntax. + +## Requirements + +- Neovim v0.10+ +- Treesitter markdown parser (`:TSInstall markdown`) + +## 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' }, + }, + index_file = 'index.md', + use_template = false, + use_external_handlers = false, + create_missing_dirs = false, + }, + keys = { + { "ww", function() require("muwiki").open_index("default") end, desc = "Open wiki index" }, + { "oo", function() require("muwiki").open_link_with() end, ft = "markdown", desc = "Open link menu to choose external handler" }, + { "", function() require("muwiki").open_link() end, ft = "markdown", desc = "Open wiki link" }, + { "", function() require("muwiki").next_link() end, ft = "markdown", desc = "Next wiki link" }, + { "", function() require("muwiki").prev_link() end, ft = "markdown", desc = "Previous wiki link" }, + { "", function() require("muwiki").create_link() end, ft = "markdown", mode = "v", desc = "Create wiki link from selection" }, + }, +} +``` + +**Note:** The `ft = "markdown"` condition ensures keymaps are only active in markdown files. Actions automatically check if the buffer is within a configured wiki directory and do nothing if not. + +## Keymaps + +Configure keymaps using lazy.nvim's `keys` option or set them up manually: + +**Default keymaps (lazy.nvim):** +```lua +keys = { + { "", function() require("muwiki").open_link() end, ft = "markdown" }, + { "", function() require("muwiki").next_link() end, ft = "markdown" }, + { "", function() require("muwiki").prev_link() end, ft = "markdown" }, + { "", 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', '', require('muwiki').open_link, { buffer = true }) + vim.keymap.set('n', '', require('muwiki').next_link, { buffer = true }) + vim.keymap.set('n', '', require('muwiki').prev_link, { buffer = true }) + vim.keymap.set('v', '', 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 +- `open_link_with()` - Open link with custom external handler +- `create_link()` - Create link from visual selection + +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.fn.jobstart({ '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. -- cgit v1.2.3