*link.txt* Convert inline links to reference links *link* *link.vim* > __ __ .__ __. __ ___ ____ ____ __ .___ ___. | | | | | \ | | | |/ / \ \ / / | | | \/ | | | | | | \| | | ' / \ \/ / | | | \ / | | | | | | . ` | | < \ / | | | |\/| | | `----.| | | |\ | | . \ __ \ / | | | | | | |_______||__| |__| \__| |__|\__\ (__) \__/ |__| |__| |__| < Version: 2.0.3 Author: qadzek License: MIT ============================================================================== CONTENTS *link-contents* 1. Introduction ......... |link-introduction| 2. Installation ......... |link-installation| 3. Usage ................ |link-usage| 4. Mappings ............. |link-mappings| 5. Configuration ........ |link-configuration| 6. Misc ................. |link-misc| 7. Limitations .......... |link-limitations| 8. Contributing ......... |link-contributing| 9. Changelog ............ |link-changelog| 10. Credits ............. |link-credits| ============================================================================== INTRODUCTION *link-introduction* Reference links allow for cleaner documents. Storing (long) URLs at the bottom of your document helps maintain the flow of the body of the text. However, managing reference links manually can be tedious. This plugin for Vim and Neovim helps converting and handling these links. Links in Markdown syntax and plaintext links (e.g. in emails, in text files etc.) are supported. The following link formats are fully supported: - Markdown external link: `[Vim](https://www.vim.org)` - plaintext external link: `https://neovim.io` The following link formats are supported in varying degrees: - Markdown internal link: `[My Recipes](recipes.md)` - Wiki internal link with description: `[[recipes.md|My Recipes]]` - Wiki internal link without description: `[[recipes.md]]` The main command will convert > # Notes [Vim](https://www.vim.org) and [Neovim](https://neovim.io) are text editors. into > # Notes [Vim][0] and [Neovim][1] are text editors. ## Links [0]: https://www.vim.org [1]: https://neovim.io < URLs are moved to a reference section. A heading is used to mark the divide between the document body and the reference section. It will be added automatically if needed and can be customized or disabled. Terminology ~ Markdown format Plaintext format - inline link: `[Vim](https://www.vim.org)` `Vim https://www.vim.org` - reference link: `[Vim][0]` `Vim [0]` - link text: `[Vim]` `none` - label: `[0]` `[0]` - link reference definition: `[0]: https://www.vim.org` `[0]: https://www.vim.org` - heading: `## Links` `Links:` - document body: part of buffer above heading, containing the main text - reference section: part of buffer below heading, containing link reference definitions For more information about the syntax Markdown uses for links, refer to the CommonMark Specification at https://spec.commonmark.org/0.31.2/#links ============================================================================== INSTALLATION *link-installation* Use your favorite plugin manager to install this plugin. vim-plug: `Plug 'qadzek/link.vim'` lazy.nvim: `{ "qadzek/link.vim" }` For `lazy.nvim` users, an example spec file is available in this project's GitHub repository. If you use a Debian-based Linux distribution, this plugin might be available in its repositories: https://repology.org/project/vim-link-vim/versions `apt install vim-link-vim` ============================================================================== USAGE *link-usage* The link.vim plugin exposes the following commands. All `:LinkConvert*` commands will add a heading below the document body if needed. *:LinkPrev* *:LinkNext* Move the cursor to the previous/next link. *:LinkConvertSingle* Convert one inline link on the current line of the document body to a reference link. If there are multiple links on the current line, pick the (first) link that is positioned on the cursor or behind the cursor. *:LinkConvertSingleInsert* Same as above; intended to be used with an Insert mode mapping. Return to Insert mode after conversion and position the cursor just outside the reference link. *:LinkConvertRange* Convert all inline links within a range of lines to reference links. Intended to be used: - with a Visual mode mapping, - after selecting lines in Visual mode `:'<,'>LinkConvertRange`, or - with an explicit range `:5,12 LinkConvertRange` *:LinkConvertAll* Convert all inline links in the document body to reference links. *:LinkOpen* Open an external link in the default browser. Open an internal link in the editor. *:LinkPeek* For a reference link within the document body, show a preview of the corresponding link reference definition. *:LinkJump* Move the cursor from a reference link within the document body to a corresponding link reference definition in the reference section, and the other way around. *:LinkShow* Show some info on link under the cursor. Useful for debugging. *:LinkReformat* Reformat reference links and reference section. This command is powerful; use it with care. It deletes the current reference section and reconstructs it. It performs the following actions: - Renumber links in document body and in reference section: > [Vim][1] is a text editor. [Neovim][0] is another one. [0]: https://neovim.io [1]: https://www.vim.org < is turned into > [Vim][0] is a text editor. [Neovim][1] is another one. [0]: https://www.vim.org [1]: https://neovim.io < - Merge links sharing the same URL: > Vim [0] is a text editor. Bram Moolenaar created Vim [1]. [0]: https://www.vim.org [1]: https://www.vim.org < is turned into > Vim [0] is a text editor. Bram Moolenaar created Vim [0]. [0]: https://www.vim.org < - Delete link reference definitions that are no longer needed: > [Vim][0] is a text editor. Neovim is another one. [0]: https://www.vim.org [1]: https://neovim.io < is turned into > [Vim][0] is a text editor. Neovim is another one. [0]: https://www.vim.org < - Mark missing links as '???': > Vim [0] is a text editor. Neovim [1] is another one. [0]: https://www.vim.org < is turned into > Vim [0] is a text editor. Neovim [???] is another one. [0]: https://www.vim.org < ============================================================================== MAPPINGS *link-mappings* No mappings are built-in to avoid conflicts with existing key bindings. *g:link_use_default_mappings* Enable the suggested key bindings (the same as mentioned below) by adding this line to your `vimrc`, before your plugin manager initializes: > let g:link_use_default_mappings = 1 < If you prefer to specify your own key bindings, ensure the variable mentioned above is not set (or set to `0`) and add the following to your `vimrc`: > nnoremap (LinkVim-Prev) nnoremap (LinkVim-Next) nnoremap j (LinkVim-Jump) nnoremap p (LinkVim-Peek) nnoremap o (LinkVim-Open) nnoremap r (LinkVim-Reformat) nnoremap c (LinkVim-ConvertSingle) inoremap c (LinkVim-ConvertSingleInsert) vnoremap c (LinkVim-ConvertRange) nnoremap a (LinkVim-ConvertAll) nnoremap s (LinkVim-Show) < To ensure that these key bindings are only applied to a particular filetype, add them to e.g. `~/.vim/ftplugin/markdown.vim` instead. Make sure to add the `` attribute. To apply these key bindings to multiple filetypes, you can add an |autocmd| to your `vimrc`: > augroup linkvim_key_bindings autocmd! autocmd Filetype markdown,vimwiki,mail,text :call LinkVimAddKeyBindings() augroup END function! LinkVimAddKeyBindings() nnoremap a (LinkVim-ConvertAll) ... endfunction < ============================================================================== CONFIGURATION *link-configuration* Most of the following configuration options exist as a local buffer variable (`b:`) or as a global variable (`g:`). The buffer-local variables enjoy a higher priority. Global variables are specified in `vimrc`. Local buffer variables can be set in their corresponding file, e.g. for mail buffers in `~/.vim/ftplugin/mail.vim` They can also be set in `vimrc`, if they are wrapped in an |autocmd|: > augroup link_mail autocmd! autocmd Filetype mail let b:link_heading = 'My Links:' augroup END < ------------------------------------------------------------------------------ *b:link_heading* *g:link_heading* By default, the heading `## Links` (Markdown) or `Links:` (other filetypes) will be used to mark the divide between the document body and the reference section. Above and below this heading, a blank line will be inserted. To modify this heading: `let g:link_heading = '# My Resources'` The heading can be disabled by setting it to an empty string. This is especially useful when link reference definitions won't be visible in the rendered output, e.g., for `README.md` files displayed on GitHub: > augroup linkvim_readme autocmd! autocmd BufRead,BufNewFile README.md let b:link_heading = '' augroup END < A multi-line heading can be configured by providing a list of strings. Note that any blank lines need to be specified explicitly. `let b:link_heading = [ '', '-----', 'My Links:', '' ]` *b:link_start_index* *g:link_start_index* By default, the first converted link gets a label of 0. To change this: `let g:link_start_index = 1` *b:link_heading_before* By default, the heading is added to the last line. You can specify a pattern to which the cursor will be moved before the heading is added. This works even if the heading is disabled. This regular expression is matched starting from the bottom of the document. This allows to position the heading, and the entire reference section, elsewhere. E.g. for a `gitcommit` buffer, the following could be useful: `let b:link_heading_before = '^# Please enter the commit message'` *b:link_skip_line* By default, links in lines matching |commentstring| are not converted. This pattern can be modified. E.g. to skip lines starting with a plus: `let b:link_skip_line = '^+'` *b:link_include_blockquotes* *g:link_include_blockquotes* By default, links in blockquotes (lines starting with `>`) are not converted. To include them: `let b:link_include_blockquotes = 1` *b:link_disable_internal_links* *g:link_disable_internal_links* Popular knowledge base plugins, such as wiki.vim, obsidian.nvim, and Vimwiki, support links to internal wiki pages. To assist their users, by default a link to an internal file, e.g. `[strawberry cake](recipes.md)` will be converted too. To disable this feature and convert only URLs: `let g:link_disable_internal_links = 1` *b:link_missing_marker* *g:link_missing_marker* The `:LinkReformat` command marks reference links with a missing link reference definition. E.g. `[foo][3]` will be converted to `[foo][???]` if there is no corresponding `[3]: ...`. To change the default `???`: `let g:link_missing_marker = 'X'` ------------------------------------------------------------------------------ *g:link_enabled_filetypes* REMOVED This plugin now operates on all filetypes by default. Configure your plugin manager to limit the plugin to certain filetypes. vim-plug: `Plug 'qadzek/link.vim', { 'for': ['markdown', 'mail'] }` lazy.nvim: `{ "qadzek/link.vim", ft = { "markdown", "mail" } }` ============================================================================== MISC *link-misc* Consider using an alternative Markdown plugin for additional link-related features. For example, https://github.com/preservim/vim-markdown supports concealing, so `[Foo][3]` is displayed as just `Foo` when not in insert mode. Other options: - https://github.com/tpope/vim-markdown (this is the default) - https://github.com/SidOfc/mkdx/ - https://github.com/vim-pandoc/vim-pandoc-syntax - https://github.com/MeanderingProgrammer/render-markdown.nvim ============================================================================== LIMITATIONS *link-limitations* - Only numeric labels are supported. ============================================================================== CONTRIBUTING *link-contributing* Pull requests are welcome. The Vint linter, the Vader test framework and the Google Style Guide are being used. https://github.com/Vimjas/vint https://github.com/junegunn/vader.vim https://google.github.io/styleguide/vimscriptguide.xml https://google.github.io/styleguide/vimscriptfull.xml To analyze the code for issues: `vint .` To run the tests, refer to `test/README.md`. ============================================================================== CHANGELOG *link-changelog* 2.0.3 2026-03-10 - Sync with upstream `wiki.vim` changes 2.0.2 2026-02-22 - Sync with upstream `wiki.vim` changes 2.0.1 2026-02-21 - Fix bug where setting wasn't honored when converting internal images (#25) 2.0.0 2025-11-20 BREAKING CHANGE - Rewrite based on `wiki.vim` - Support converting plaintext and Markdown links in the same file - Support internal links (#14) - Support multi-line headings (#21) - Avoid adding duplicate links to reference section - Support URLs containing special characters like `~` or `*` - Add commands `:LinkPrev`, `:LinkNext` and `:LinkShow` - Remove `g:link_enabled_filetypes` 1.4.0 2024-12-11 - Skip links in blockquotes (#16) 1.3.0 2024-11-28 - Support converting links to internal wiki pages (#14) 1.2.0 2024-11-07 - Support link conversion without using a heading 1.1.0 2024-11-04 - Support `` mappings 1.0.5 2024-09-11 - Fix trailing punctuation characters being seen as part of the URL (#12) 1.0.4 2024-09-10 - Fix issue with identical links on the same line - Fix unintended scrolling 1.0.3 2024-05-13 - Support special characters in URLs when opening them in browser 1.0.2 2024-05-08 - Convert filetype plugin to global plugin BREAKING CHANGE - `Links:` is default heading if filetype is not Markdown - Support `b:link_start_index` - Rename plugin BREAKING CHANGE 1.0.1 2024-05-06 - Remove :MdLinkDelete BREAKING CHANGE - Add :MdLinkReformat to renumber, merge and delete links 1.0.0 2024-05-04 - Remove pre- and post-processing commands BREAKING CHANGE - Add native support for plaintext links - Rename :MdLinkDeleteUnneededRefs BREAKING CHANGE 0.5.0 2024-04-17 - Allow positioning of reference section - Add pre- and post-processing of plaintext links - Allow lines to be skipped if pattern matches 0.4.1 2024-04-10 - Fix cursor position not getting restored (#9) 0.4.0 2024-04-08 - Allow buffer-local heading (#7) 0.3.1 2024-04-08 - Fix too lenient regex for inline links (#4) 0.3.0 2024-04-05 - Add :MdLinkConvertRange (#2) 0.2.0 2024-03-19 - Add :MdLinkOpen 0.1.0 2024-03-15 - Initial version ============================================================================== CREDITS *link-credits* Originally, `link.vim` was written from scratch. To implement more advanced features, in `v2` it has been rewritten based on the excellent `wiki.vim` plugin by Karl Yngve Lervåg (@lervag): https://github.com/lervag/wiki.vim Learn Vimscript the Hard Way by Steve Losh: https://learnvimscriptthehardway.stevelosh.com/ Contributors and their GitHub usernames: - Enno (@Konfekt) - @unclenull ============================================================================== vim:tw=78:ts=8:ft=help:norl: