1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
|
*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:
|
