diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 159 |
1 files changed, 65 insertions, 94 deletions
@@ -11,14 +11,24 @@ A lightweight wiki plugin for Neovim using standard markdown syntax. - Standard markdown links `[text](url)` - Multiple wiki directories -- External link handlers -- Link navigation with custom keymaps +- Link navigation and xdg-open for web/file links +- Extensible via autocmds (mkdir, templates, custom handlers) + +See `:help muwiki-autocmd-recipes` for implementation examples. See `:help muwiki` for complete documentation and configuration options. ## Installation -Using [lazy.nvim](https://github.com/folke/lazy.nvim): +### Using vim.pack (Neovim 0.12+) + +```lua +vim.pack.add({ + { src = "https://git.3kgcat.fi/muwiki.nvim" } +}) +``` + +### Using lazy.nvim ```lua { @@ -27,62 +37,86 @@ Using [lazy.nvim](https://github.com/folke/lazy.nvim): { "<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("muwiki", { clear = true }) - -- Setup wiki keymaps for markdown files vim.api.nvim_create_autocmd("FileType", { group = group, pattern = "markdown", - callback = function(args) - if not muwiki.wiki_root(args.buf) then return end - - local keymap_opts = { buffer = args.buf, silent = true, nowait = true } + 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, - -- Auto-create parent directories when saving files in wiki - vim.api.nvim_create_autocmd("BufWritePre", { - group = group, - callback = function(args) - local wiki_root = muwiki.wiki_root(args.buf) - if not wiki_root then return end +} +``` - local file = args.file - if not vim.startswith(file, wiki_root) then return end +## Quick Start - local dir = vim.fn.fnamemodify(file, ":h") - if vim.fn.isdirectory(dir) == 0 then - vim.fn.mkdir(dir, "p") - end - end, - }) +Add this to your config for basic wiki functionality: + +```lua +local muwiki = require('muwiki') + +-- Configure wiki directories +muwiki.setup({ + dirs = {{ name = 'default', path = '~/wiki' }}, +}) + +-- 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, -} +}) + +-- Auto-create directories when saving new files +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, +}) ``` -**Available actions:** +## Available Actions -- `open_link()` - Open link under cursor +- `open_link()` - Open link under cursor (wiki→nvim, web/files→xdg-open) - `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. +- `get_link()` - Get link info at cursor +- `open_with_menu(handlers)` - Open link with selectable handler +- `open_index(name)` - Open wiki index file ## Link Format @@ -93,69 +127,6 @@ See `:help muwiki-commands` for complete API documentation. [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: |