*link.txt* Convert inline links (Markdown or plaintext) to reference links

                                                                        *link*
              _   _           _                  _~
             | | (_)  _ __   | | __     __   __ (_)  _ __ ___~
             | | | | | '_ \  | |/ /     \ \ / / | | | '_ ` _ \~
             | | | | | | | | |   <   _   \ V /  | | | | | | | |~
             |_| |_| |_| |_| |_|\_\ (_)   \_/   |_| |_| |_| |_|~


Version: 1.0.3
Author:  qadzek
License: MIT

==============================================================================
CONTENTS                                                       *link-contents*

    1. Introduction ......... |link-introduction|
    2. Usage ................ |link-usage|
    3. Mappings ............. |link-mappings|
    4. Configuration ........ |link-configuration|
    5. Limitations .......... |link-limitations|
    6. Contributing ......... |link-contributing|
    7. Changelog ............ |link-changelog|
    8. 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 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 automatically
added if needed.

Terminology~
                               Markdown                    Plaintext
  - inline link:               `[Vim](www.vim.org)`          `Vim www.vim.org`
  - reference link:            `[Vim][0]`                    `Vim [0]`
  - link text:                 `[Vim]`                       `none`
  - label:                     `[0]`                         `same`
  - link reference definition: `[0]: https://www.vim.org`    `same`
  - 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

==============================================================================
USAGE                                                             *link-usage*

The link.vim plugin exposes the following commands:

:LinkConvertSingle                                        *:LinkConvertSingle*
    Convert one inline link on the current line of the document body to a
    reference link. Add a heading below the document body if needed. If there
    are multiple links on the current line, pick the (first) link that is
    positioned on the cursor or behind the cursor.

:LinkConvertSingleInsert                            *:LinkConvertSingleInsert*
    Same as above; intended to be used with an Insert mode mapping. Return to
    Insert mode and position the cursor just outside the reference link.

:LinkConvertRange                                          *:LinkConvertRange*
    Convert all inline links within a range to reference links. Add a
    heading below the document body if needed. Intended to be used after
    selecting lines in Visual mode `:'<,'>LinkConvertRange` or with an
    explicit range `:5,12 LinkConvertRange`

:LinkConvertAll                                              *:LinkConvertAll*
    Convert all inline links in the document body to reference links. Add a
    heading below the document body if needed.

:LinkOpen                                                          *:LinkOpen*
    For a reference link within the document body, open the URL of the
    corresponding link reference definition in the default browser.

:LinkPeek                                                          *:LinkPeek*
    For a reference link within the document body, show a preview of the
    corresponding link reference definition.

:LinkJump                                                          *: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.

:LinkReformat                                                  *: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.

        ## Links

        [0]: https://neovim.io
        [1]: https://www.vim.org
<      is turned into >
        [Vim][0] is a text editor.
        [Neovim][1] is another one.

        ## Links

        [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].

        Links:

        [0]: https://www.vim.org
        [1]: https://www.vim.org
<      is turned into >
        Vim [0] is a text editor.
        Bram Moolenaar created Vim [0].

        Links:

        [0]: https://www.vim.org
<
    - Delete link reference definitions that are no longer needed: >
        [Vim][0] is a text editor.
        Neovim is another one.

        ## Links

        [0]: https://www.vim.org
        [1]: https://neovim.io
<      is turned into >
        [Vim][0] is a text editor.
        Neovim is another one.

        ## Links

        [0]: https://www.vim.org
<
    - Mark missing links as '???': >
        Vim [0] is a text editor.
        Neovim [1] is another one.

        Links:

        [0]: https://www.vim.org
<      is turned into >
        Vim [0] is a text editor.
        Neovim [???] is another one.

        Links:

        [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`: >
  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`: >
  augroup link_key_bindings
    autocmd!
    autocmd Filetype markdown,vimwiki,mail,text :call LinkAddKeyBindings()
  augroup END

  function! LinkAddKeyBindings()
    nnoremap <buffer> <silent> <LocalLeader>c      :LinkConvertSingle<CR>
    inoremap <buffer> <silent> <C-g>c      <Esc>:LinkConvertSingleInsert<CR>
    vnoremap <buffer> <silent> <LocalLeader>c      :LinkConvertRange<CR>
    nnoremap <buffer> <silent> <LocalLeader>a      :LinkConvertAll<CR>
    nnoremap <buffer> <silent> <LocalLeader>j      :LinkJump<CR>
    nnoremap <buffer> <silent> <LocalLeader>o      :LinkOpen<CR>
    nnoremap <buffer> <silent> <LocalLeader>p      :LinkPeek<CR>
    nnoremap <buffer> <silent> <LocalLeader>r      :LinkReformat<CR>
  endfunction
<
You might want to change the filetypes mentioned in the |autocmd|. Another way
to ensure that these key bindings are only applied to certain filetypes is to
add them to e.g. `~/.vim/ftplugin/markdown.vim`. That way, you don't need to
use an |autocmd| or function.

==============================================================================
CONFIGURATION                                             *link-configuration*

By default, the plugin operates on these filetypes: `markdown`, `vimwiki`,
`email` and `text`.

                                                    *g:link_enabled_filetypes*
These filetypes can be customized: >
  let g:link_enabled_filetypes = [ 'markdown', 'gitcommit' ]
<
For examples of how users have configured this plugin for particular
filetypes, e.g. `gitcommit` buffers, visit the Wiki:
https://github.com/qadzek/link.vim/wiki

------------------------------------------------------------------------------

Some 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. To modify this heading:
  `let g:link_heading = '# My Resources'`

                                                          *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 regular
expression is matched 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 blockquotes:
  `let b:link_skip_line = '^>'`

==============================================================================
LIMITATIONS                                                 *link-limitations*

- Using a blank line as heading is currently not supported.
- When converting an inline link to a reference link, a link reference
  definition will be created, even if the same URL is already present in the
  reference section. It would be better if the same label were reused. Using
  `:LinkReformat` fixes this though.
- URLs containing the asterisk character (`*`) are not 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 **/*.vim`
To execute the tests: `./test/run_tests.sh`

==============================================================================
CHANGELOG                                                     *link-changelog*

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*

Learn Vimscript the Hard Way by Steve Losh:
https://learnvimscriptthehardway.stevelosh.com/

Contributors and their GitHub usernames:
- Enno (@Konfekt)

==============================================================================

vim:tw=78:ts=8:ft=help:norl:
