1 files changed, 186 insertions, 0 deletions
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 = {
+    { "<leader>ww", function() require("muwiki").open_index("default") end, desc = "Open wiki index" },
+    { "<leader>oo", function() require("muwiki").open_link_with() end, ft = "markdown", desc = "Open link menu to choose external handler" },
+    { "<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" },
+  },
+}
+```
+
+**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 = {
+  { "<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" },
+}
+```
+
+**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', '<CR>', require('muwiki').open_link, { buffer = true })
+    vim.keymap.set('n', '<Tab>', require('muwiki').next_link, { buffer = true })
+    vim.keymap.set('n', '<S-Tab>', require('muwiki').prev_link, { buffer = true })
+    vim.keymap.set('v', '<CR>', 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.