From b8a007dc84e73096b180e65c27a69b42bedec78b Mon Sep 17 00:00:00 2001
From: moxie <moxie@3kgcat.fi>
Date: Sat, 14 Mar 2026 07:15:24 +0200
Subject: chore: update readme/docs

---
 doc/muwiki.txt | 110 +++++++++++++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 100 insertions(+), 10 deletions(-)

(limited to 'doc')

diff --git a/doc/muwiki.txt b/doc/muwiki.txt
index 562ff5c..f6fd62a 100644
--- a/doc/muwiki.txt
+++ b/doc/muwiki.txt
@@ -38,18 +38,34 @@ Using 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' }},
       },
-      -- 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" },
-      },
+
+      -- 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)
+          end,
+        })
+      end,
     }
 <
 ==============================================================================
@@ -89,13 +105,87 @@ Configuration Options:~
                             when opening or creating wiki files.
                             Values:
                               false    - Don't create directories (default)
-                              true     - Same as 'notify'
-                              'silent' - Create without notification
                               'notify' - Create and show notification
                               'prompt' - Ask before creating
                             Directories are only created within wiki root.
                             Default: false
 
+Example:~
+
+    {
+      url = "https://git.3kgcat.fi/muwiki.nvim/",
+      keys = {
+        { "<leader>ww", function() require("muwiki").open_index("default") end, desc = "Open wiki index" },
+        { "<leader>we", function() require("muwiki").open_index("test") end,    desc = "Open test wiki index" },
+      },
+      opts = {
+        dirs = {
+          { name = 'default', path = '~/wiki' },
+          { name = 'test',    path = '~/wiki_test' },
+        },
+        index_file = 'index.md',
+        create_missing_dirs = 'notify',
+        date_fmt = '%Y-%m-%d',
+        use_template = true,
+        template = [[
+    ---
+    title: ${title}
+    date: ${date}
+    ---
+    ]],
+        text_extensions = { 'md', 'txt' },
+        use_external_handlers = true,
+        external_handlers = {
+          {
+            name = 'mpv',
+            cmd = 'mpv',
+            pattern = {
+              '%.mp4$',
+              '%.mkv$',
+              '%.avi$',
+              '%.webm$',
+              'youtube%.com',
+              'youtu%.be',
+            },
+          },
+          {
+            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 = '.*',
+          },
+          {
+            name = 'xdg-open',
+            cmd = 'xdg-open',
+            pattern = '.*',
+          },
+        },
+      },
+
+      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,
+    }
+
 ==============================================================================
 4. COMMANDS AND API                                   *muwiki-commands*
 
-- 
cgit v1.2.3