diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/muwiki.txt | 444 | ||||
| -rw-r--r-- | doc/tags | 18 |
2 files changed, 462 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: diff --git a/doc/tags b/doc/tags new file mode 100644 index 0000000..f52890d --- /dev/null +++ b/doc/tags @@ -0,0 +1,18 @@ +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-templates muwiki.txt /*muwiki-templates* +muwiki.next_link() muwiki.txt /*muwiki.next_link()* +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.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* |