*link.txt* Convert inline links to reference links

                                                                 *link* *link.vim*
>
       __       __  .__   __.  __  ___     ____    ____  __  .___  ___.
      |  |     |  | |  \ |  | |  |/  /     \   \  /   / |  | |   \/   |
      |  |     |  | |   \|  | |  '  /       \   \/   /  |  | |  \  /  |
      |  |     |  | |  . `  | |    <         \      /   |  | |  |\/|  |
      |  `----.|  | |  |\   | |  .  \   __    \    /    |  | |  |  |  |
      |_______||__| |__| \__| |__|\__\ (__)    \__/     |__| |__|  |__|
<

Version: 2.0.0
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" }`

An example spec file is available in the repository for users of `lazy.nvim`.

==============================================================================
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 <C-p>          <plug>(LinkVim-Prev)
  nnoremap <C-n>          <plug>(LinkVim-Next)
  nnoremap <LocalLeader>j <plug>(LinkVim-Jump)
  nnoremap <LocalLeader>p <plug>(LinkVim-Peek)
  nnoremap <LocalLeader>o <plug>(LinkVim-Open)
  nnoremap <LocalLeader>r <plug>(LinkVim-Reformat)
  nnoremap <LocalLeader>c <Plug>(LinkVim-ConvertSingle)
  inoremap <C-g>c         <Plug>(LinkVim-ConvertSingleInsert)
  vnoremap <LocalLeader>c <plug>(LinkVim-ConvertRange)
  nnoremap <LocalLeader>a <plug>(LinkVim-ConvertAll)
  nnoremap <LocalLeader>s <plug>(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
`<buffer>` 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 <buffer> <LocalLeader>a <plug>(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.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 `<Plug>` 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:
