refactor: simplify codebase and fix FileType autocommands

1 files changed, 193 insertions, 413 deletions

diff --git a/doc/muwiki.txt b/doc/muwiki.txt
index 878095d..c22be0f 100644
--- a/doc/muwiki.txt
+++ b/doc/muwiki.txt
@@ -1,453 +1,233 @@
-*muwiki.txt*    A lightweight wiki plugin for Neovim
+*muwiki.nvim*  A lightweight wiki plugin for Neovim
 
-Author:          muwiki.nvim contributors
-License:         TBD
-
-CONTENTS                                                *muwiki-contents*
-
-1. Introduction ........................... |muwiki-introduction|
-2. Installation ........................... |muwiki-installation|
-3. Configuration .......................... |muwiki-configuration|
-4. Commands and API ....................... |muwiki-commands|
-5. Keymaps ................................ |muwiki-keymaps|
-6. Link Format ............................ |muwiki-link-format|
-7. External Handlers ...................... |muwiki-external-handlers|
+==============================================================================
+CONTENTS                                                     *muwiki-contents*
+
+1. Introduction ............................................ |muwiki-intro|
+2. Requirements ............................................ |muwiki-requirements|
+3. Installation ............................................ |muwiki-installation|
+4. Configuration ........................................... |muwiki-configuration|
+5. Commands & Functions .................................... |muwiki-commands|
+6. Lua API ................................................. |muwiki-api|
+7. Autocommands & Recipes .................................. |muwiki-autocmd|
+   7.1 Auto-create directories ............................. |muwiki-autocmd-mkdir|
+   7.2 Add template for new files .......................... |muwiki-autocmd-template|
+   7.3 Open with menu examples ............................. |muwiki-autocmd-open-with|
+8. Health Check ............................................ |muwiki-health|
 
 ==============================================================================
-1. INTRODUCTION                                     *muwiki-introduction*
+1. INTRODUCTION                                                 *muwiki-intro*
 
-muwiki.nvim is a lightweight wiki plugin for Neovim that uses standard
-markdown syntax for creating and navigating wiki-style documentation.
+MuWiki is a lightweight wiki plugin for Neovim using standard markdown syntax.
+It provides:
 
-Features:~
 - Standard markdown links `[text](url)`
-- Multiple wiki directories support
-- External link handlers for custom URL/file opening
-- Link navigation with custom keymaps
+- Multiple wiki directories
+- Link navigation and xdg-open for web/file links
+- Extensible via autocmds (mkdir, templates, custom handlers)
+
+==============================================================================
+2. REQUIREMENTS                                           *muwiki-requirements*
 
-Requirements:~
 - Neovim v0.10+
 - Treesitter markdown parsers (`:TSInstall markdown markdown_inline`)
 
 ==============================================================================
-2. INSTALLATION                                     *muwiki-installation*
+3. INSTALLATION                                           *muwiki-installation*
 
-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' }},
-      },
-
-      -- 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 }
-            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,
-        })
-
-        -- 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
-
-            local dir = vim.fn.fnamemodify(file, ":h")
-            if vim.fn.isdirectory(dir) == 0 then
-              vim.fn.mkdir(dir, "p")
-            end
-          end,
-        })
-      end,
-    }
+Using vim.pack (Neovim 0.12+)~
+>
+  vim.pack.add({
+    { src = "https://git.3kgcat.fi/muwiki.nvim" }
+  })
 <
-==============================================================================
-3. CONFIGURATION                                   *muwiki-configuration*
-
-Configuration Options:~
-
-    dirs                    List of wiki directories (required)
-                            Each entry has `name` and `path` fields
-
-    index_file              Name of the wiki index file
-                            Default: 'index.md'
-
-    use_external_handlers   Enable external URL/file handlers
-                            Default: false
-
-    external_handlers       List of external handler definitions
-                            See |muwiki-external-handlers|
 
-    text_extensions         Extensions to open in Neovim, bypassing
-                            external handlers. Only used when
-                            use_external_handlers is enabled.
-                            Even binary files like PNG can be added
-                            to force editor opening.
-                            Default: { 'md', 'txt' }
-
-Example:~
->lua
-    {
-      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',
-        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("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 }
-            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,
-        })
-
-        -- 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
-
-            local dir = vim.fn.fnamemodify(file, ":h")
-            if vim.fn.isdirectory(dir) == 0 then
-              vim.fn.mkdir(dir, "p")
-            end
-          end,
-        })
-      end,
-    }
-<
-==============================================================================
-4. COMMANDS AND API                                   *muwiki-commands*
-
-All functions are accessed through the main module: `require("muwiki")`
-
-                                                           *muwiki.open_index()*
->lua
-    require("muwiki").open_index(name)
+Using lazy.nvim~
+>
+  {
+    url = "https://git.3kgcat.fi/muwiki.nvim",
+    keys = {
+      { "<leader>ww", function() require("muwiki").open_index("default") end, desc = "Open wiki index" },
+    },
+    opts = {
+      dirs = {{ name = 'default', path = '~/wiki' }},
+    },
+  }
 <
-Open the index file of a wiki.
-
-Parameters:~
-    {name}  Wiki directory name as configured in `dirs`
-
-Example:~
->lua
-    -- Open the default wiki index
-    require("muwiki").open_index("default")
 
-    -- Can be bound to a key
-    vim.keymap.set('n', '<leader>ww', function()
-      require("muwiki").open_index("default")
-    end)
+==============================================================================
+4. CONFIGURATION                                         *muwiki-configuration*
+
+The plugin is configured using the |muwiki.setup()| function.
+
+Configuration Options~
+
+                                                    *muwiki-opt-dirs*
+dirs                    List of wiki directories.
+                        Each entry is a table with:
+                        - name: Wiki name for reference
+                        - path: Absolute path to wiki directory
+                        Default: nil
+
+                                                    *muwiki-opt-index_file*
+index_file              Name of the index file for each wiki.
+                        Default: 'index.md'
+
+Example Configuration~
+>
+  local muwiki = require('muwiki')
+
+  muwiki.setup({
+    dirs = {
+      { name = 'default', path = '~/wiki' },
+      { name = 'work', path = '~/work/wiki' },
+    },
+    index_file = 'index.md',
+  })
 <
 
-                                                            *muwiki.open_link()*
->lua
-    require("muwiki").open_link()
-<
-Open the link under the cursor. Automatically detects link type:
-- Wiki links: Opens in Neovim (creates new page if doesn't exist)
-- Web links: Opens with xdg-open
-- File links: Opens with xdg-open or in Neovim (for text_extensions)
-
-Note: This function uses xdg-open directly and ignores custom
-external_handlers configuration. File existence is checked for file://
-links and an error is shown if the file is not found.
-Use |muwiki.open_link_with()| to utilize custom handlers.
-
-                                                            *muwiki.next_link()*
->lua
-    require("muwiki").next_link()
+==============================================================================
+5. COMMANDS & FUNCTIONS                                     *muwiki-commands*
+
+Keymaps should be configured by the user. Here are recommended keymaps:
+>
+  -- 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,
+  })
 <
-Jump to the next markdown link in the current buffer.
 
-                                                            *muwiki.prev_link()*
->lua
-    require("muwiki").prev_link()
+Link Format~
+>
+  [Wiki page](page.md)
+  [Website](https://example.com)
+  [Relative path](file://../document.pdf)
+  [Absolute path](file:///tmp/image.png)
 <
-Jump to the previous markdown link in the current buffer.
 
-                                                               *muwiki.open_link_with()*
->lua
-    require("muwiki").open_link_with()
-<
-Open the link under cursor with a custom external handler.
-Shows a menu if multiple handlers match the URL.
-Uses custom external_handlers configuration.
-Only available for web and file links.
-
-                                                 *muwiki.create_link()*
->lua
-    require("muwiki").create_link()
+==============================================================================
+6. LUA API                                                       *muwiki-api*
+
+muwiki.setup({opts})                                   *muwiki.setup()*
+    Configure the plugin. See |muwiki-configuration| for options.
+
+muwiki.open_link()                                     *muwiki.open_link()*
+    Open the link under cursor.
+    - Wiki links: open in Neovim buffer
+    - Web links: open with xdg-open
+    - File links: open with xdg-open
+
+muwiki.next_link()                                     *muwiki.next_link()*
+    Jump to the next markdown link in the buffer.
+
+muwiki.prev_link()                                     *muwiki.prev_link()*
+    Jump to the previous markdown link in the buffer.
+
+muwiki.create_link()                                   *muwiki.create_link()*
+    Create a link from visual selection. In visual mode, select text and
+call this function to convert it to a markdown link. The text will be
+normalized to create a filename (lowercase, spaces to underscores).
+
+muwiki.get_link()                                      *muwiki.get_link()*
+    Get information about the link under cursor.
+    Returns a table with:
+    - text: Link display text
+    - target: Link destination
+    - type: Link type ('web', 'file', or 'wiki')
+
+muwiki.open_with_menu({handlers}, {link})              *muwiki.open_with_menu()*
+    Open link with a selectable handler from a menu.
+    {handlers} is a list of handler tables:
+>
+    {
+      name = "Handler Name",
+      cmd = "command" or function(url),
+      exts = {"pdf", "doc"}  -- optional file extensions
+    }
 <
-Create a markdown link from the visually selected text.
-Transforms the selected text into a link format `[text](normalized_text.md)`
-and opens the target file in a new buffer.
+    {link} is optional; if not provided, gets link under cursor.
 
-Usage:
-- Select text in visual mode (v or V)
-- Call this function
-- Selected text is replaced with a markdown link
-- Target file is opened in a new buffer (unsaved)
+muwiki.open_index({name})                              *muwiki.open_index()*
+    Open the index file of a wiki by name.
+    {name} is the wiki name from configuration.
 
-Example:
-- Select: `My New Page`
-- Result: `[My New Page](my_new_page.md)`
-
-Note: Multi-line selections are not supported.
+muwiki.wiki_root({bufnr})                              *muwiki.wiki_root()*
+    Get the wiki root directory for a buffer.
+    Returns the path or nil if buffer is not in a wiki.
 
 ==============================================================================
-5. KEYMAPS                                             *muwiki-keymaps*
-
-muwiki.nvim provides actions that automatically check if the current buffer
-is within a configured wiki directory before executing.
-
-Keymap Setup:~
-Configure keymaps using an autocmd to ensure they only apply within wiki
-directories: >lua
-    local muwiki = require('muwiki')
-
-    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 opts = { buffer = args.buf, silent = true, nowait = 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)
-        vim.keymap.set('n', '<leader>oo', muwiki.open_link_with, opts)
-      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
-
-        local dir = vim.fn.fnamemodify(file, ":h")
-        if vim.fn.isdirectory(dir) == 0 then
-          vim.fn.mkdir(dir, "p")
-        end
-      end,
-    })
+7. AUTOCOMMANDS & RECIPES                                   *muwiki-autocmd*
+
+Auto-create directories when saving~                                  *muwiki-autocmd-mkdir*
+>
+  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,
+  })
 <
-Note: Actions check if the buffer is within a configured wiki directory and
-notify the user if not.
-
-                                                      *muwiki*
-Actions:~
-All user-facing actions are available directly through `require('muwiki')`:
-
-    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
 
-These functions check if the buffer is a wiki buffer before executing.
-
-Available API Functions:~
+Add template for new files~                                           *muwiki-autocmd-template*
+>
+  vim.api.nvim_create_autocmd("BufNewFile", {
+    pattern = "*.md",
+    callback = function(args)
+      local wiki_root = muwiki.wiki_root(args.buf)
+      if not wiki_root then return end
+
+      local filename = vim.fn.fnamemodify(args.file, ":t:r")
+      local template = string.format("# %%s\n\n", filename)
+      vim.api.nvim_buf_set_lines(args.buf, 0, 0, false, vim.split(template, "\n"))
+    end,
+  })
+<
 
-    open_index(name)         Open wiki index file
+Open with menu example~                                               *muwiki-autocmd-open-with*
+>
+  vim.keymap.set('n', '<leader>o', function()
+    muwiki.open_with_menu({
+      { name = "Zathura", cmd = "zathura", exts = {"pdf"} },
+      { name = "swayimg", cmd = "swayimg", exts = {"png", "jpg", "jpeg", "gif", "webp"} },
+      { name = "mpv", cmd = "mpv", exts = {"mp4", "mkv", "avi", "mov", "webm"} },
+      { name = "xdg-open", cmd = "xdg-open" },
+    })
+  end, { buffer = true, desc = "Open with..." })
+<
 
 ==============================================================================
-6. LINK FORMAT                                     *muwiki-link-format*
+8. HEALTH CHECK                                                  *muwiki-health*
 
-muwiki.nvim uses standard markdown link syntax.
+Run |:checkhealth muwiki| to verify:
+- Wiki directories are configured and exist
+- Treesitter markdown parser is installed
 
->markdown
-    [Wiki page](page.md)
-    [Website](https://example.com)
-    [Relative path](file://../document.pdf)
-    [Absolute path](file:///tmp/image.png)
-<
 ==============================================================================
-7. EXTERNAL HANDLERS                           *muwiki-external-handlers*
-
-Define custom handlers for opening external URLs and files.
+RECOMMENDED PLUGINS
 
-Note: Custom handlers are only used by |muwiki.open_link_with()|.
-The default <CR> mapping uses |muwiki.open_link()| which uses xdg-open
-directly, ignoring custom handlers.
-
-Enable external handlers:~
->lua
-    require("muwiki").setup({
-      use_external_handlers = true,
-    })
-<
-Handler Definition:~
-Each handler is a table with:
-
-    name        Display name in the handler menu (string)
-    cmd         Command string or Lua function (string|function)
-    pattern     Lua pattern(s) to match URLs (optional string or table of
-                strings; if omitted, matches all URLs)
-
-Handler Examples:~
->lua
-    external_handlers = {
-      -- Open HTTP/HTTPS URLs in Firefox
-      {
-        name = 'Firefox',
-        cmd = 'firefox',
-        pattern = '^https?://',
-      },
-      -- Open videos with mpv using multiple patterns (table)
-      {
-        name = 'mpv',
-        cmd = 'mpv',
-        pattern = {
-          '%.mp4$',
-          '%.mkv$',
-          '%.avi$',
-          '%.webm$',
-          'youtube%.com',
-          'youtu%.be',
-        },
-      },
-      -- Open images with swayimg using multiple patterns
-      {
-        name = 'swayimg',
-        cmd = 'swayimg',
-        pattern = {
-          '%.png$',
-          '%.jpe?g$',
-          '%.gif$',
-          '%.webp$',
-          '%.bmp$',
-        },
-      },
-      -- Copy URL to clipboard using Lua function
-      {
-        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
-      {
-        name = 'xdg-open',
-        cmd = 'xdg-open',
-        pattern = '.*',
-      },
-    }
-<
-Interaction with text_extensions:~
-The |muwiki-configuration| option `text_extensions` overrides external
-handlers. Files with extensions listed in `text_extensions` will always
-open in Neovim, even when `use_external_handlers` is enabled. This is
-useful for forcing certain file types into the editor (e.g., adding
-'png' to edit images as text/hex).
-
-Example: Open PNG files in Neovim (as text/hex) instead of external viewer:~
->lua
-    text_extensions = { 'md', 'txt', 'png' }
-<
-==============================================================================
-==============================================================================
-HEALTH CHECKING                                        *muwiki-health*
+These plugins work well with muwiki.nvim:
 
-Run health check with:
->:checkhealth muwiki
-<
-The health check verifies:
-- Wiki directories are configured
-- Wiki directories exist and are accessible
-- Treesitter markdown parser is installed (required for link detection)
-- External handler commands are available (if configured)
+- render-markdown.nvim - Improve markdown rendering in Neovim
+- outline.nvim - Navigate document structure with symbols outline
 
 ==============================================================================
 vim:tw=78:ts=8:ft=help:norl: