path: root/doc/muwiki.txt

*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|

==============================================================================
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)`
- Multiple wiki directories support
- External link handlers for custom URL/file opening
- Link navigation with custom keymaps

Requirements:~
- Neovim v0.10+
- Treesitter markdown parsers (`:TSInstall markdown markdown_inline`)

==============================================================================
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 = {
        -- 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,
    }
<
==============================================================================
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)
<
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.

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,
    })
<
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:~

    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.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*

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: