chore: init

1 files changed, 444 insertions, 0 deletions

diff --git a/doc/muwiki.txt b/doc/muwiki.txt
new file mode 100644
index 0000000..7183e9e
--- /dev/null
+++ b/doc/muwiki.txt
@@ -0,0 +1,444 @@
+*muwiki.txt*    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|
+8. Templates .............................. |muwiki-templates|
+
+==============================================================================
+1. INTRODUCTION                                     *muwiki-introduction*
+
+muwiki.nvim is a lightweight wiki plugin for Neovim that uses standard
+markdown syntax for creating and navigating wiki-style documentation.
+
+Features:~
+- Standard markdown links `[text](url)` - compatible with any markdown renderer
+- Multiple wiki directories support
+- External link handlers for custom URL/file opening
+- Automatic templates for new pages
+- Link navigation with custom keymaps
+
+Requirements:~
+- Neovim v0.10+
+- Treesitter markdown parser (install with :TSInstall markdown)
+
+==============================================================================
+2. 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 = {
+        dirs = {
+          { name = 'default', path = '~/wiki' },
+        },
+        index_file = 'index.md',
+        date_fmt = '%Y-%m-%d',
+        use_template = false,
+        use_external_handlers = false,
+        external_handlers = {
+          {
+            name = 'xdg-open',
+            cmd = 'xdg-open',
+            pattern = '.*',
+          },
+        },
+        text_extensions = { 'md', 'txt' },
+      },
+      config = function(_, opts)
+        local muwiki = require('muwiki')
+        muwiki.setup(opts)
+
+        local function setup_keymaps()
+          local keymap_opts = { buffer = 0, silent = true, nowait = true }
+          vim.keymap.set('n', '<CR>', function() muwiki.open_link() end, keymap_opts)
+          vim.keymap.set('n', '<Tab>', function() muwiki.next_link() end, keymap_opts)
+          vim.keymap.set('n', '<S-Tab>', function() muwiki.prev_link() end, keymap_opts)
+        end
+
+        vim.schedule(setup_keymaps)
+        vim.api.nvim_create_autocmd('BufEnter', {
+          pattern = '*.md',
+          callback = setup_keymaps,
+        })
+      end,
+      lazy = true,
+    }
+<
+==============================================================================
+3. CONFIGURATION                                   *muwiki-configuration*
+
+                                                              *muwiki.setup()*
+>lua
+    require("muwiki").setup({
+      -- Wiki directories (REQUIRED - configure at least one)
+      dirs = {
+        { name = 'default', path = '~/wiki' },
+        { name = 'test', path = '~/wiki_test' },
+      },
+
+      index_file = 'index.md',
+      date_fmt = '%Y-%m-%d',
+      use_template = false,
+      template = [[
+---
+title: ${title}
+date: ${date}
+---
+]],
+
+      use_external_handlers = false,
+      -- External handler definitions (see |muwiki-external-handlers|)
+      external_handlers = {
+        {
+          name = 'xdg-open',
+          cmd = 'xdg-open',
+          pattern = '.*',
+        },
+      },
+
+      -- File extensions to open in Neovim (bypasses external handlers)
+      -- Tip: Add binary extensions like 'png' here to open them as hex/text for inspection
+      text_extensions = { 'md', 'txt' },
+    })
+<
+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'
+
+    date_fmt                Date format string for templates
+                            Default: '%Y-%m-%d'
+
+    use_template            Enable automatic templates for new pages
+                            Default: false
+
+    template                Template content with placeholders
+                            See |muwiki-templates|
+
+    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' }
+
+    create_missing_dirs     Automatically create missing parent directories
+                            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
+
+==============================================================================
+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)
+<
+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)
+<
+
+                                                            *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()
+<
+Jump to the next markdown link in the current buffer.
+
+                                                            *muwiki.prev_link()*
+>lua
+    require("muwiki").prev_link()
+<
+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()
+<
+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.
+
+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)
+
+Example:
+- Select: `My New Page`
+- Result: `[My New Page](my_new_page.md)`
+
+Note: Multi-line selections are not supported.
+
+==============================================================================
+5. KEYMAPS                                             *muwiki-keymaps*
+
+muwiki.nvim provides actions that automatically check if the current buffer
+is within a configured wiki directory before executing.
+
+Using lazy.nvim:~
+Configure keymaps in the `keys` table: >
+    {
+      'muwiki.nvim',
+      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' },
+        { '<leader>oo', function() require('muwiki').open_link_with() end,
+          ft = 'markdown', desc = 'Open link menu to choose external handler' },
+      },
+    }
+<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.
+
+Manual setup:~
+For other plugin managers, set up your own autocmds: >
+    vim.api.nvim_create_autocmd('BufEnter', {
+      pattern = '*.md',
+      callback = function()
+        local opts = { buffer = true }
+        vim.keymap.set('n', '<CR>', require('muwiki').open_link, opts)
+        vim.keymap.set('n', '<Tab>', require('muwiki').next_link, opts)
+        vim.keymap.set('n', '<S-Tab>', require('muwiki').prev_link, opts)
+        vim.keymap.set('v', '<CR>',
+          require('muwiki').create_link, opts)
+      end,
+    })
+<
+Note: Actions automatically check if the buffer is a wiki buffer.
+
+                                                      *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:~
+
+    open_index(name)         Open wiki index file
+
+==============================================================================
+6. LINK FORMAT                                     *muwiki-link-format*
+
+muwiki.nvim uses standard markdown link syntax.
+
+>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.
+
+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.fn.jobstart({ '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' }
+<
+
+==============================================================================
+8. TEMPLATES                                         *muwiki-templates*
+
+Automatic templates can be applied when creating new wiki pages.
+
+Enable templates:~
+>lua
+    require("muwiki").setup({
+      use_template = true,
+    })
+<
+Template Placeholders:~
+
+    ${title}    Page title (derived from filename)
+    ${date}     Current date (formatted with `date_fmt`)
+
+Default Template:~
+>lua
+    template = [[
+---
+title: ${title}
+date: ${date}
+---
+]]
+<
+Custom Template Example:~
+>lua
+    require("muwiki").setup({
+      template = [[
+---
+title: ${title}
+date: ${date}
+---
+
+# ${title}
+
+]],
+    })
+<
+==============================================================================
+HEALTH CHECKING                                        *muwiki-health*
+
+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)
+
+==============================================================================
+vim:tw=78:ts=8:ft=help:norl: