diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/muwiki.txt | 606 | ||||
| -rw-r--r-- | doc/tags | 21 |
2 files changed, 207 insertions, 420 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: @@ -1,17 +1,24 @@ +muwiki-api muwiki.txt /*muwiki-api* +muwiki-autocmd muwiki.txt /*muwiki-autocmd* +muwiki-autocmd-mkdir muwiki.txt /*muwiki-autocmd-mkdir* +muwiki-autocmd-open-with muwiki.txt /*muwiki-autocmd-open-with* +muwiki-autocmd-template muwiki.txt /*muwiki-autocmd-template* muwiki-commands muwiki.txt /*muwiki-commands* muwiki-configuration muwiki.txt /*muwiki-configuration* muwiki-contents muwiki.txt /*muwiki-contents* -muwiki-external-handlers muwiki.txt /*muwiki-external-handlers* muwiki-health muwiki.txt /*muwiki-health* muwiki-installation muwiki.txt /*muwiki-installation* -muwiki-introduction muwiki.txt /*muwiki-introduction* -muwiki-keymaps muwiki.txt /*muwiki-keymaps* -muwiki-link-format muwiki.txt /*muwiki-link-format* +muwiki-intro muwiki.txt /*muwiki-intro* +muwiki-opt-dirs muwiki.txt /*muwiki-opt-dirs* +muwiki-opt-index_file muwiki.txt /*muwiki-opt-index_file* +muwiki-requirements muwiki.txt /*muwiki-requirements* +muwiki.create_link() muwiki.txt /*muwiki.create_link()* +muwiki.get_link() muwiki.txt /*muwiki.get_link()* muwiki.next_link() muwiki.txt /*muwiki.next_link()* +muwiki.nvim muwiki.txt /*muwiki.nvim* muwiki.open_index() muwiki.txt /*muwiki.open_index()* muwiki.open_link() muwiki.txt /*muwiki.open_link()* -muwiki.open_link_with() muwiki.txt /*muwiki.open_link_with()* +muwiki.open_with_menu() muwiki.txt /*muwiki.open_with_menu()* muwiki.prev_link() muwiki.txt /*muwiki.prev_link()* muwiki.setup() muwiki.txt /*muwiki.setup()* -muwiki.create_link() muwiki.txt /*muwiki.create_link()* -muwiki.txt muwiki.txt /*muwiki.txt* +muwiki.wiki_root() muwiki.txt /*muwiki.wiki_root()* |