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|
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)`
- 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 parsers (`:TSInstall markdown markdown_inline`)

==============================================================================
2. INSTALLATION                                     *muwiki-installation*

Using lazy.nvim:~
>lua
    {
      url = "https://git.3kgcat.fi/muwiki.nvim",
      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" },
      },
    }
<
==============================================================================
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'

    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.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' }
<

==============================================================================
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: