/
wiki.txt
2232 lines (1767 loc) · 86.7 KB
/
wiki.txt
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
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
*wiki.txt* A wiki plugin for Vim
*wiki.vim*
Author: Karl Yngve Lervåg <karl.yngve@gmail.com>
License: MIT license {{{
Copyright (c) 2021 Karl Yngve Lervåg
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to
deal in the Software without restriction, including without limitation the
rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
sell copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
The software is provided "as is", without warranty of any kind, express or
implied, including but not limited to the warranties of merchantability,
fitness for a particular purpose and noninfringement. In no event shall the
authors or copyright holders be liable for any claim, damages or other
liability, whether in an action of contract, tort or otherwise, arising
from, out of or in connection with the software or the use or other dealings
in the software.
}}}
==============================================================================
CONTENTS *wiki-contents*
Introduction |wiki-intro|
Requirements |wiki-intro-requirements|
Usage |wiki-intro-usage|
Features |wiki-intro-features|
Guide |wiki-intro-guide|
Other useful plugins |wiki-intro-plugins|
Alternatives |wiki-intro-alternatives|
Links |wiki-link|
URL schemes |wiki-link-schemes|
Supported link types |wiki-link-types|
Options |wiki-options|
Events |wiki-events|
Mappings and commands |wiki-mappings|
Default mappings |wiki-mappings-default|
Reference |wiki-mappings-reference|
Completion |wiki-completion|
Tags |wiki-tags|
Default tag parser |wiki-tags-default|
Orgmode tag parser |wiki-tags-orgmode|
Templates |wiki-templates|
Template function context |wiki-templates-context|
Template file format |wiki-templates-format|
Journal summaries |wiki-templates-journal-summaries|
Advanced configuration guide |wiki-advanced-configuration|
Example 1: New scheme |wiki-advanced-config-1
Example 2: Adjust the wiki scheme |wiki-advanced-config-2
==============================================================================
INTRODUCTION *wiki-intro*
This is a Vim plugin for writing and maintaining a personal wiki, also known
as a personal knowledge base. Please see |wiki-intro-usage| for a simple
quick-start guide. See also |wiki-intro-guide| for more in-depth info on what
this is and how one could use such a system efficiently.
`wiki.vim` is a "filetype agnostic" plugin that is intended to work well across
different filetypes. The core functionality is to handle links of various
kinds and to allow workflows to quickly traverse a wiki and to create new
links and new pages. The "filetype agnostic" description is only half true,
because the different link syntaxes are usually tied to a specific
filetype/file format. Also, features like |WikiTocGenerate| depends on
assumptions of an underlying file format. However, it is a core idea that
`wiki.vim` should work well for any text based wiki.
An important point: `wiki.vim` is `not` a filetype plugin! It is designed so
that it may be used along with dedicated filetype plugins, such as dedicated
Markdown plugins.
The plugin will activate by default for Markdown files (`*.md`). This may be
customized with |g:wiki_filetypes| and |g:wiki_global_load|. One may also
explicitly activate with |WikiEnable|. The wiki root is automatically detected
as long as there is a top-level index file available, e.g. `index.md`. The
index name may be changed with |g:wiki_index_name|. If no index file is found,
the root is set to the same directory as the current file. In addition, one
may specify a "main wiki" with the |g:wiki_root| option. This allows
convenient mappings and commands for opening this main wiki from anywhere.
------------------------------------------------------------------------------
REQUIREMENTS *wiki-intro-requirements*
This plugin is mainly developed on and for Linux. Some or most of the features
should still work on Windows and OSX, but currently there are no guarantees.
On Windows, it is assumed that users enable 'shellslash' to avoid issues with
backslashes versus forward slashes.
Some features require a recent version of Vim (>= 8.1) or NeoVim (>= 0.5).
The following is a list of external tools that are used for some of the
features:
Program Feature ~
======= =======
`fzf` A backend for UI selection (|g:wiki_select_method|)
`pandoc` |WikiExport|
------------------------------------------------------------------------------
USAGE *wiki-intro-usage*
This outlines the basic steps to get started:
1. Create a wiki directory where the wiki files should be stored, for instance
`~/wiki`.
2. Add the corresponding option to your `vimrc` file: >vim
let g:wiki_root = '~/wiki'
3. Now you can open the index file with `<leader>ww` and start to add your
notes as desired.
The mappings are listed in |wiki-mappings-default|. The most essential
mappings that most users will want to learn are:
- `<cr>` (normal mode): Either follow the link under the cursor, or create
a link from the text under the cursor.
- `<cr>` (visual mode): Create a link from the selected text.
- `gl`: An |operator| to create a link from the operated text.
- `<bs>`: After following a link: go back to previous location.
- `<tab>`: Move to next link.
- `<shift-tab>`: Move to previous link.
- `<leader>wd`: Delete current page.
- `<leader>wr`: Rename current page and update all incoming links.
See |wiki-mappings-default| for a full list of default options and info on how
to change them.
------------------------------------------------------------------------------
FEATURES *wiki-intro-features*
- Wiki functionality
- Global
- Commands (and mappings) to access a pre-specified wiki (|g:wiki_root|)
- |WikiIndex| to open the index
- |WikiJournal| to open the journal
- |WikiPages| to select from list of all pages
- |WikiTags| to select from list of tags
- Local commands and mappings for
- Navigation (follow links, go back, etc)
- Renaming pages (will also update links in other pages)
- Navigate through a table of contents (|WikiToc|)
- Creating a table of contents (|WikiTocGenerate|)
- Transforming links (from text to link or between link types)
- Viewing wiki link graphs
- Completion of wiki links and link anchors
- Text objects
- `iu au` Link URL
- `it at` Link text
- New page templates
- Support for journal entries
- Navigating the journal back and forth with `<Plug>(wiki-journal-next)`
and `<Plug>(wiki-journal-prev)`.
- Support for parsing journal entries in order to make weekly and monthly
summaries. The parsed result needs manual editing for good results.
- Utility functionality
- |WikiExport| command for exporting to e.g. `pdf` with `pandoc`
- Third-party support
- `ncm2`: SubscopeDetector for nested completion
------------------------------------------------------------------------------
GUIDE *wiki-intro-guide*
LAST UPDATED: 2023-03-01
The following guide is more or less an essay on how I personally use
`wiki.vim` for structuring and writing my notes. I take the liberty of writing
in the first tense, as this is clearly a subjective matter. An initial version
of this was posted as a comment in an issue thread [0] (note: the links are
listed at the bottom). I recommend anyone interested to read the entire thread
(although it is quite long!).
I've structured the following guide in two main sections. The first section
concerns how to keep a personal wiki or knowledge base. In the second,
I explain how I keep my daily journal. But first, a quote that I think
captures the most important concept in a single sentence (by @mgoral [1]):
> I think that the most important thing is to not overthink things and just
> keep writing stuff down.
Executive summary ~
- Speed is key - make sure you have a fast workflow:
- Use a keyboard shortcut in your desktop/window manager to open Vim/neovim
with the wiki index (e.g. <alt-n>).
- Use something like |:WikiPages| and `ripgrep` (with e.g.
`ctrlsf.vim` [2]) for searching.
- Write short pages and use links between related pages.
- Don't obsess about the wiki structure.
A personal wiki ~
People write things down. Take notes. Why? Because people, or at least most of
us, don't remember things for too long. From my point of view, taking notes
is a way to extend my memory. And writing the notes is itself a useful
process, because it often helps both to learn and to remember things.
I find the idea of keeping my notes linked and easily searchable in pure text
to be extremely potent. With `wiki.vim`, I can very quickly locate relevant
notes for a topic. I believe strongly that speed or efficiency is the key
aspect of a good personal-knowledge system. However, before I continue, I want
to stress that `wiki.vim` is just one such system. There are probably
countless, and I encourage everyone to find a system that works for them. Some
alternatives are listed under |wiki-intro-alternatives|.
So, some context: My personal wiki consists per 2023-03-01 of 2728 pages with
a total of 96969 lines (excluding my journal). I first started taking notes in
2007, so this is perhaps 16 years' worth of writing. I use Syncthing [3] to
keep my notes synchronized across my computers, phones, and tablets. I've
previously also used Dropbox.
Needless to say, it is important to be able to find relevant notes fast.
I have a global Vim mapping `<leader>ow` to open a page search interface.
I previously used |:WikiPages|, which works very well! Today, though, I use
Telescope [4] with a personal function to list wiki files [5]. It usually
takes no more than a couple of seconds from the moment I think of something
until I have opened the relevant note. A key here is to use simple names for
the pages. I prefer several short pages instead of one long, if possible.
I also don't worry about using spaces in my wiki file names.
Sometimes I search for things within pages. For this, I rely on `ripgrep` [6].
I use `ctrlsf.vim` [2] (which uses `ripgrep` as a backend). I map this to
`<leader>ff`. This makes it very easy and fast to search the wiki. And if my
search has too many hits, I can either narrow it down by changing the search
pattern, or I can search within the result buffer of `ctrlsf.vim`. This has
generally not failed me in finding information I'm looking for. I don't spend
a lot of time searching for things. If I know I've written about something,
I always find it with `<leader>ow` and/or `<leader>ff`, and usually in
a matter of seconds.
How do I write my notes? I make sure to write down what I feel like at the
moment. I then clean it up and rinse/repeat as something is developing. I add
links to relevant external and internal pages/resources. I often add examples,
for instance tools I discover or libraries I learn about.
With time, I've started to adopt an unstructured approach where I avoid
complicated structure and subdirectories. I try to use the proper names of
things as the name of a page. The simple structure makes it easy to convert
text to the correct links and it makes it easy to remember the relevant page
names.
I don't worry about having many pages. I don't worry about almost empty pages.
I don't worry about keeping my pages in a hierarchy. I've found it can be
useful to split information into separate pages, as it makes it easier to link
things. I sometimes find the graph features useful, e.g. |wiki-graph-in|, but
I don't use them much.
However, sometimes I write down stuff that I don't know where to put. This is
where I use my index (`index.wiki`). This file is where I put anything that
does not currently have a home. I may also use it to link to pages that need
attention. For example, if I were to notice that my wiki page about Topic X is
outdated and/or needs some work, then I add a link to it from my index. With
time, I work through the index (often slowly) and move content into more
dedicated pages. For this workflow to work well, it is crucial that my index
is extremely accessible. I therefore have a global keyboard shortcut on all my
computers to open the index in neovim in new terminal. Specifically, I map
<alt-n> to the shell command `urxvt -e nvim +WikiIndex`, where `urxvt` is
a well-known terminal. This way, it takes less than a second from the moment
I have a thought until I can start to add it to my `index.wiki` for later
processing. The speed allows me to write down a thought immediately and then
continue with the current work without being severely disrupted - this is what
makes the concept so important.
Although I do add a lot of text to my wiki, I've also realized that I should
not add all data there. For instance, I've come to use Zotero [7] for managing
my literature database. This is also why there is now some support for Zotero
within `wiki.vim` (see |wiki-link-cite|).
For some topics, I may write a wiki page about stuff where I have links to
data files in which I can append new data and to scripts I can run to
visualize the data. Thus, I don't keep everything in the wiki, instead, I may
write the "metadata" and general overview in the wiki, and then keep the real
data and relevant tools as a "third party".
Daily journal ~
I keep a daily journal. I use |:WikiJournal| to open today's page. For each
day, I tend to write a short memo on what I did that day. I've found it
convenient to format this as lists for each main topic/project/activity. This
makes it easier to write weekly and monthly summaries.
I use |WikiJournalToWeek| and |WikiJournalToMonth| commands to create the
summaries. I write them in retrospective. I use another plugin of mine,
lists.vim [8], which has a command `ListsUniq` that I use to quickly write
and combine these summaries.
I reserve my journal for work-related activities. This includes minutes of
meetings or notes from events and courses. However, I don't use my journal to
log mundane tasks or other temporal acitivities. Instead, I keep a log of such
things in a related wiki page. For instance, I have a wiki page for my house
where I keep a log of repairs and similar.
I usually plan my work week each Monday by manually writing and maintaining
TODOs for each day in the week. I also have an entry for the next Monday where
I put TODOs that are not for the present week.
This way, my journal serves as a task tracker where I write quick comments
about tasks when I work on them. I generally avoid adding "real" information
content to my journal. a journal entry. Instead, I create links to my main
wiki and put valuable content there. This way, if I work on something, then
work on it again after a long break, the content is readily available when
I get back to it. In some cases, I do link from my wiki to a specific journal
entry - for instance when I refer to meeting notes.
If I'm curious about what I did at a particular date, I use calendar.vim [9]
to find the date and open the corresponding entry (see [10, 11] for my related
Vim configuration). I'm generally never interested in any form of journal
index (|WikiJournalIndex| exists because some users find it useful, though).
The calendar.vim interface is more or less everything I need in that regard.
Similar to my personal wiki index, I use a global shortcut to open today's
journal page: <alt-j>. This is mapped to `urxvt -e nvim +WikiJournal`. I find
it very useful as it makes it very easy to quickly open my daily journal if
I want to make a note or read about something I did earlier.
Over time, the journal entries have a great value in that it is easy to go
back and see what I did at a particular point in time. The summaries make it
easy to get a larger overview. I don't use them often, but when I do, I'm glad
I have them. I also find the process of writing all of these things useful as
it makes me think about what I'm doing - both the planning part and the
retrospective part.
Closing words ~
Finally, I again stress that these are my personal experiences and opinions,
and I very much acknowledge that what works for me probably does not work for
everyone else.
References ~
[0]: https://github.com/lervag/wiki.vim/issues/101#issuecomment-709571804
[1]: https://github.com/lervag/wiki.vim/issues/101#issuecomment-718284921
[2]: https://github.com/dyng/ctrlsf.vim
[3]: https://syncthing.net/
[4]: https://github.com/nvim-telescope/telescope.nvim
[5]: https://github.com/lervag/dotnvim/blob/fddbc2def970cb4bd61894d60c0e7e266408f2f8/lua/lervag/util/ts.lua#L40-L71
[6]: https://github.com/BurntSushi/ripgrep
[7]: https://www.zotero.org/
[8]: https://github.com/lervag/lists.vim
[9]: https://github.com/itchyny/calendar.vim
[10]: https://github.com/lervag/dotnvim/blob/fddbc2def970cb4bd61894d60c0e7e266408f2f8/lua/lervag/init/packages.lua#L1335-L1347
[11]: https://github.com/lervag/dotnvim/blob/main/ftplugin/calendar.lua
------------------------------------------------------------------------------
OTHER USEFUL PLUGINS *wiki-intro-plugins*
Some users may find that `wiki.vim` does not provide all of the features they
want for taking notes. Users who are used to Vimwiki will probably miss things
like features to interact with lists and check lists. This is a natural
consequence of the idea to "do one thing and do it well"; the core feature of
`wiki.vim` is to handle links in various formats and shapes. It has additional
wiki features and some fringe features, but these are not as important.
The following is a list of plugins that one may want to use alongside
`wiki.vim` for a more "complete" experience. If a user reads this list and
things that it is lacking, they are very welcome to suggest additions!
Markdown ~
Many users prefer to use `wiki.vim` with the Markdown filetype. Vim and neovim
ship with a decent Markdown plugin by default, but there are also popular and
well maintained alternatives with more features. Here are some popular
options:
- https://github.com/tpope/vim-markdown (this is shipped with Vim and neovim)
- https://github.com/preservim/vim-markdown
- https://github.com/SidOfc/mkdx/
- https://github.com/vim-pandoc/vim-pandoc-syntax
wiki-ft.vim ~
https://github.com/lervag/wiki-ft.vim
`wiki-ft.vim` is a simple filetype plugin for `.wiki` files that provides
syntax highlighting and folding. Recommended settings if you want to use
this: >vim
let g:wiki_filetypes = ['wiki']
lists.vim ~
https://github.com/lervag/lists.vim
This is a Vim plugin to manage text based lists and check lists.
Tables ~
There are a lot of plugins to work with tables. These are both excellent:
- https://github.com/dhruvasagar/vim-table-mode
- https://github.com/junegunn/vim-easy-align
calendar.vim ~
https://github.com/itchyny/calendar.vim
A plugin that provides a neat calendar feature. It can be integrated with
`wiki.vim` with e.g. this to map `<cr>` to open the selected date in the
journal or diary in `wiki.vim`: >vim
augroup init_calendar
autocmd!
autocmd FileType calendar
\ nnoremap <silent><buffer> <cr>
\ :<c-u>call wiki#journal#open()<cr>
augroup END
------------------------------------------------------------------------------
ALTERNATIVES *wiki-intro-alternatives*
There exist a lot of alternatives to `wiki.vim`. Within the Vim ecosystem,
the main alternative is Vimwiki. But there are also a lot of other
alternatives. The following list is probably not very comprehensive. It may be
useful if only as an inspiration to read about alternative approaches. The
descriptions are mostly a copy of the initial text from the relevant home
pages.
Vimwiki ~
https://github.com/vimwiki/vimwiki
Type: Plugin; Vim
Vimwiki is a personal wiki system for Vim. It relies on its own filetype,
although recent versions also support more traditional Markdown formats.
Fun fact: `wiki.vim` was initially based on Vimwiki, but it is written from
scratch and is based on the philosophy of "do one thing and do it well".
Waikiki ~
https://github.com/fcpg/vim-waikiki
Type: Plugin; Vim
Waikiki is a "fisherman's wiki": it provides a minimal set of features to
navigate pages and create links and pages.
Foam ~
https://foambubble.github.io/foam/
Type: Plugin; Visual Studio Code
Foam is a personal knowledge management and sharing system inspired by Roam
Research, built on Visual Studio Code and GitHub.
Roam Research ~
https://roamresearch.com/
Type: Software
A note-taking tool for networked thought. As easy to use as a document. As
powerful as a graph database. Roam helps you organize your research for the
long haul.
Emacs Org Mode ~
https://orgmode.org/
Type: Plugin; Emacs
A GNU Emacs major mode for convenient plain text markup — and much more. Org
mode is for keeping notes, maintaining to-do lists, planning projects,
authoring documents, computational notebooks, literate programming and more
— in a fast and effective plain text system. Several ports to Vim exist to
varying degrees of completion.
Obsidian.md ~
https://obsidian.md/
Type: Software
"A second brain, for you, forever." Obsidian is a powerful knowledge base on
top of a local folder of plain text Markdown files.
==============================================================================
LINKS *wiki-link*
Links are the most essential concept of a wiki. As such, it is important to
understand them. Simply stated, a link is a "structure" that consists of a URL
and a possibly empty description. URL is short for Uniform Resource Locator
and is an address to a resource.
The URL concept is specified in RFC 3986 "Uniform Resource Identifier (URI):
Generic Syntax" (https://datatracker.ietf.org/doc/html/rfc3986). A typical URL
looks like this: `scheme:target-address`. Some examples of URLs:
- `http://www.example.com`
- `wiki:index`
- `journal:2013-04-05`
- `doi:10.1002%2Fandp.19053220607`
It is easy to confuse the concept of the link with that of the URL itself, but
these are two distinct concepts. A URL is by definition a link, but a link may
be "more" than just a URL. Some examples of valid links recognized by
`wiki.vim`: >
http://www.example.com link is just a URL
<wiki:a wiki link with spaces> <…> allows URLs with spaces
[[http://www.example.com]] wiki link without description
[[http://www.example.com|a wiki link]] wiki link with description
[a markdown link](http://www.example.com) markdown link with description
The mappings that act on links are listed in |wiki-mappings-default|. The most
notable default mappings are:
- A link may be followed with `<cr>`.
- `<cr>` used on normal text (not on a link) will transform the text into
a link of the type specified by |g:wiki_link_creation|. This also works in
visual mode.
- Similarly, `gl` may be used to turn operated text into a link.
- One may use `<bs>` to navigate back after following a link.
- `<leader>wf` can be used to transform a link between different types (see
|g:wiki_link_transforms|).
`wiki.vim` is very customizable with respect to how it should behave for
a given link. Consider the following example: >
[[scheme:target-address|describing text goes here]]
\______ URL ________/ \_____ description _____/
The `scheme:` part of the URL is important. It is "optional", but only in the
sense that many link types have a default "implied" scheme given by
|g:wiki_link_default_schemes|. The URL scheme is used to select the `resolver`
and `handler` functions used by `wiki.vim` to follow a link. Users can
override the default functions by use of the |g:wiki_link_schemes| option.
This also allows to easily implement custom schemes. See the section
|wiki-advanced-configuration| for examples of how one can do this.
So, in summary: When a user presses `<cr>` to follow a link, `wiki.vim` will
do these things:
- The link is first parsed to detect the URL and possibly prepend a default
scheme.
- The link URL is then passed to an optional `resolver` function that "parses"
the raw link.
- The possibly resolved URL is then passed to a `handler` that opens/follows
the link.
------------------------------------------------------------------------------
URL SCHEMES *wiki-link-schemes*
The following is a list of the schemes that are supported out of the box.
wiki ~
Links to internal wiki pages. The address can be both relative and absolute.
Absolute addresses are relative to the wiki root. Further, the addresses may
include anchors to specific sections of the wiki entry. Some examples might
be enlightening: >
wiki:index
If the address has whitespace, we need to use a full link style, for
instance:
[[wiki:index#section 1]]
With default settings, wiki link types also imply the wiki scheme, thus
the following is equivalent to the latter:
[[index#section 1]]
<
journal ~
Links to journal pages. The address should be a date format at a specified
level/frequency:
- daily: `YYYY-MM-DD` (standard ISO date)
- weekly: `YYYY-wWW`
- monthly: `YYYY-MM`
Notice that these formats will be translated to the corresponding filename
formats in the `date_format` key of |g:wiki_journal|. Some examples of
journal urls: >
journal:2014-03-02
journal:2014-w09
journal:2014-03
<
For convenience, the ISO date will also be recognized as a journal url
without the scheme.
Note: This scheme works well as long as there is only a single page per
date. If you want to use multiple entries per date you should avoid
this scheme and you should probably consider to change the
`use_journal_scheme` option (see |g:wiki_journal_index|).
file ~
Links to a local file. |g:wiki_viewer| is used by the default handler to
open a file. It can be useful to define a custom `handler` function for the
`file:` scheme to specify desired behaviour for different filetypes. As for
any scheme, users can implement a custom file handler with
|g:wiki_link_schemes|.
doi ~
Resolves `doi:ADDRESS` to `http://dx.doi.org/ADDRESS` and uses the `generic`
scheme handler to open.
zot ~
This is an early version of a Zotero scheme. It uses `fd`, `fdfind`, or
`find` (in preferred order) to search the Zotero storage for a matching pdf.
This works very well if one uses the Zotfile extension and the Better Bibtex
extension to ensure that all pdf files are named according to the format
`%b - {%T - } {%t}`, where `%b` is the citekey. Then links like
`zot:citekey` should result in unique matches. The resulting file is opened
with |g:wiki_viewer|. The Zotero storage root may be specified with
|g:wiki_zotero_root|.
The same link type can also work well for JabRef bibliographies. JabRef does
not allow to open the database on a specific key. But if your JabRef library
has PDFs that are named similarly as explained above, then it should suffice
to point |g:wiki_zotero_root| to your literature folder. Now following
`zot:citekey` (or the shorthand `@citekey`) will allow to open the PDFs in
your JabRef bibliography directly.
generic ~
If the scheme is not otherwise recognized, then the URL is opened with the
system handler. This is defined by the `_` key of |g:wiki_viewer| on Linux.
Currently, only Linux is supported here. This will work quite well on
standard Linux distributions, e.g. for following `http` and `https` URLs.
------------------------------------------------------------------------------
SUPPORTED LINK TYPES *wiki-link-types*
These are the currently supported link types:
- Wiki links |wiki-link-wiki|
- Markdown links |wiki-link-md|
- Markdown image links |wiki-link-md_fig|
- Orgmode links |wiki-link-org|
- Reference links |wiki-link-reference|
|wiki-link-ref_target|
- AsciiDoc cross references |wiki-link-adoc_xref_bracket|
|wiki-link-adoc_xref_inline|
- AsciiDoc link macro |wiki-link-adoc_link|
- Cite links |wiki-link-cite|
- ISO dates |wiki-link-date|
Wiki links ~
*wiki-link-wiki*
Wiki links are similar in style to the standard Mediawiki links [0]. A couple
of examples: >
[[URL]]
[[URL|Description]]
In `wiki.vim`, the wiki link URL is recognized as any general URL except it
has `wiki` as the default implied scheme.
[0]: https://www.mediawiki.org/wiki/Help:Links
Markdown links ~
*wiki-link-md*
Markdown links look like this: >
[Description](URL)
Markdown image links ~
*wiki-link-md_fig*
Markdown image links are similar to markdown links: >
Orgmode links ~
*wiki-link-org*
Orgmode links look identical to wiki links if they don't have a description.
If they have a description, it is added within the outer square brackets
within a second pair of square brackers. Examples: >
[[URL]]
[[URL][Description]]
Reference links ~
*wiki-link-reference*
*wiki-link-ref_target*
Reference style links consist of up to three parts: A `label`, an optional
`description`, and a `link target`. The syntax is best explained through an
example: >
The most simple form, and perhaps the most useful one, is to add a simple
reference like this [1].
One may also add a [description][label].
The target may consist of both words and numbers, e.g. [like this][Ref 3].
[1]: <URL 1>
[label]: <URL 2>
[Ref 3]: <URL 3>
Reference links are implemented as two different link types:
- `reference`: matches links used in the text, such as `[1]` and
`[text][label]`. Following this link will either open the target URL or move
the cursor to the target URL. Notice that this link type does not allow to
specify a default scheme, because it will use the reference scheme under the
hood for resolving the proper url.
- `ref_target`: matches link targets, such as `[1]: URL`. Following this will
open the URL.
Asciidoc cross references ~
*wiki-link-adoc_xref_bracket*
*wiki-link-adoc_xref_inline*
AsciiDoc cross-reference links or xrefs [0] look like this: >
Bracket style
<<anchor>>
<<anchor,Description>>
<<filename.adoc#anchor>>
<<filename.adoc#anchor,Description>>
Inline macro
xref:anchor[Description]
xref:filename.adoc#anchor[Description]
xref:[LONG URL][Description]
The `[LONG URL]` variant is supported for cases where the filename contains
spaces.
[0]: https://docs.asciidoctor.org/asciidoc/latest/macros/xref/
Asciidoc link macros ~
*wiki-link-adoc_link*
The AsciiDoc link macro [0] is a generic link syntax that looks like this: >
link:<target>[<attrlist>]
The `[<attrlist>]` will be recognized by `wiki.vim` as the link text.
[0]: https://docs.asciidoctor.org/asciidoc/latest/macros/link-macro/
Cite links ~
*wiki-link-cite*
The cite links are a convenient link type that can be used with e.g. Zotero
URLs. That is, instead of writing a link with URL `zot:citekey` one may simply
write `@citekey`.
See also |wiki-link-url| for more info on the Zotero URL scheme and handler.
Iso dates ~
*wiki-link-date*
Dates written in ISO date format, e.g. 2023-05-05, will be recognized as
a link to `journal:2023-05-05`.
==============================================================================
OPTIONS *wiki-options*
`wiki.vim` has several options to configure the behaviour. The following is
a reference of all available options.
*g:wiki_cache_root*
Specify the cache directory for `wiki.vim`.
Default value: OS dependent
`Linux and MacOS`: `'~/.cache/wiki.vim/'`
`Windows`: Standard temporary folder (based on |tempname()|)
*g:wiki_cache_persistent*
Specify whether to use persistent caching.
Default value: 1
*g:wiki_completion_enabled*
Specify whether to override 'omnifunc' when entering a wiki buffer. Set this
to 0 if you want to use another omnifunc.
Default value: 1
*g:wiki_completion_case_sensitive*
Specify whether to use case-sensitive matching for omnicompletion of links
and tags.
Default value: 1
*g:wiki_export*
A dictionary that specifies the default configuration for |WikiExport|
options. See the specifications for the options for more information.
Default: >vim
let g:wiki_export = {
\ 'args' : '',
\ 'from_format' : 'markdown',
\ 'ext' : 'pdf',
\ 'link_ext_replace': v:false,
\ 'view' : v:false,
\ 'output': fnamemodify(tempname(), ':h'),
\}
*g:wiki_filetypes*
List of filetype extensions for which `wiki.vim` should be enabled. Notice
that file extensions are not always the same as the filetype. For example,
the common extension for Markdown is `.md`, whereas the filetype is called
`markdown`. The option should list the file extensions.
The first element of the list is considered the default filetype where that
is relevant.
Default: `['md']`
*g:wiki_fzf_pages_force_create_key*
Key combination that, when pressed while searching with |WikiPages|, will
create a new page with the name of the query. The value must be a string
recognized by fzf's `--expect` argument; see fzf's manual page for a list of
available keys.
Default: `'alt-enter'`
*g:wiki_fzf_pages_opts*
A string with additional user options for |WikiPages|. This can be used
e.g. to add a previewer. Users should be aware that the page candidates are
"prettified" with the `--with-nth=1` and `-d` options for fzf, so to obtain
the page path in a previewer option one must use the field index expression `1`.
E.g.: >vim
let g:wiki_fzf_pages_opts = '--preview "cat {1}"'
<
Default: `''`
*g:wiki_fzf_tags_opts*
A string with additional user options for |WikiTags|. This can be used
e.g. to add a previewer. Users should be aware that the page candidates are
"prettified" with the `-d` option for fzf, so to obtain the page path in a
previewer option one must use the field index expression `2..`.
E.g.: >vim
let g:wiki_fzf_tags_opts = '--preview "bat --color=always {2..}"'
<
Default: `''`
*g:wiki_global_load*
`wiki.vim` is inherently agnostic in that it assumes any recognized filetype
specifies a wiki. However, some people might want to load `wiki.vim` for
ONLY files within a globally specified directory |g:wiki_root|. To allow
this behaviour, one can set this option to 0.
Default: 1
*g:wiki_select_method*
A string to represent the UI select method used for the following commands:
- |WikiPages|
- |WikiTags|
- |WikiToc|
Possible values:
- `'ui_select'` Use |vim.ui.select| (neovim only!)
- `'fzf'` Use fzf (https://github.com/junegunn/fzf.vim). This has
a few additional options for more fine tuned control:
- |g:wiki_fzf_pages_opts|
- |g:wiki_fzf_tags_opts|
- |g:wiki_fzf_pages_force_create_key|
Default (neovim): `'ui_select'`
Default (Vim): `'fzf'`
*g:wiki_index_name*
A string with the index page name for the wiki. The value should not include
the file extension.
Default: `'index'`
*g:wiki_journal*
A dictionary for configuring the journal/diary feature. Available options
are:
name ~
Name of journal. This is used to set the journal root path if the root
is not also specified explicitly.
root ~
The root path of the journal. An empty value means that the journal root
path is `{wiki root}/{journal name}`. This allows for separate wikis
with their own separate journals.
However, if the user prefers a single journal in a different location,
they may specify the journal root. In this case, all journal links will
be relative to this specific root path. This also means that the `name`
option is no longer relevant.
The root path, if specified, should be an absolute path or something
resolveable to an absolute path.
frequency ~
One of 'daily', 'weekly', or 'monthly'. Specifies the desired
journalling frequency. This is relevant for e.g. |WikiJournal|.
date_format ~
Dictionary of filename formats for the 'daily', 'weekly', and 'monthly'
frequencies. The formats may contain the following keys:
%y year (two digits)
%Y year (four digits)
%m month (01..12)
%d day of month (01..31)
%V ISO week number with Monday as first day of week
%U week number with Sunday as first day of week
/ Path delimiter
The files will be rooted at the journal root.
The following example specifies to create journal entries in a path
hierarchy: >vim
let g:wiki_journal = {
\ 'date_format': {
\ 'daily' : '%Y/%m/%d',
\ 'weekly' : '%Y/week_%V',
\ 'monthly' : '%Y/%m/summary',
\ },
\}
<
With this setting, the journal files would be structured something like
this: >
wiki/journal
├── 2021
│ ├── week_01.wiki
│ ├── week_02.wiki
│ └── 04
│ ├── summary.wiki
│ ├── 25.wiki
│ └── 26.wiki
└── 2022
└── 06
├── 25.wiki
└── 26.wiki
<
Default: >vim
let g:wiki_journal = {
\ 'name': 'journal',
\ 'root': '',
\ 'frequency': 'daily',
\ 'date_format': {
\ 'daily' : '%Y-%m-%d',
\ 'weekly' : '%Y_w%V',
\ 'monthly' : '%Y_m%m',
\ },
\}
*g:wiki_journal_index*
A dictionary for configuring the behaviour of |WikiJournalIndex|. Available
options are:
link_text_parser ~
Specify parser function for the link texts. This is a function
(|Funcref|) or a |lambda| that takes three arguments and must return the
desired link text. The arguments are:
1. The basename of the link target without extension.
2. The ISO date.
3. The absolute path to the link target.
This function gives a lot of flexibility. Here are some examples: >vim
" Use the file basename
let g:wiki_journal_index = {
\ 'link_text_parser': { b, d, p -> b }
\}
" Use the isodate. This works well as long as there is only a single
" journal entry per date.
let g:wiki_journal_index = {
\ 'link_text_parser': { b, d, p -> d }
\}
" Extract and use first header of the file
let g:wiki_journal_index = {
\ 'link_text_parser': { b, d, p -> wiki#toc#get_page_title(p) }
\}
<
link_url_parser ~
Specify parser function for the link urls. This is a function
(|Funcref|) or a |lambda| that takes three arguments and must return the
desired link url string. The arguments are the same as for
`link_text_parser`.
The default setting uses the `journal:` scheme on link urls (see
|wiki-link-url| for more info). Note that the journal scheme does not
work well if there are multiple pages per single date!
Here are some examples of alternative configurations: >vim
" Use the path from wiki root (this is usually a good alternative to
" the default journal: scheme)
let g:wiki_journal_index = {
\ 'link_url_parser': { b, d, p -> p }
\}
" Use relative path from current file (i.e. file where you are making
" the index)
let g:wiki_journal_index = {
\ 'link_url_parser': { b, d, p ->
\ wiki#paths#relative(p, expand('%:p:h'))
\ }
\}
<
Default: >vim
let g:wiki_journal_index = {
\ 'link_text_parser': { b, d, p -> d },
\ 'link_url_parser': { b, d, p -> 'journal:' . d }
\}
*g:wiki_link_creation*
A dictionary to configure how links are created from text for any given
filetype. Filetypes are specified by file extension so as to correspond with
|g:wiki_filetypes|, that is, we use `md` and not `markdown`.
The corresponding value is a dictionary of options. If there is no key for
the current filetype, then the fallback key `"_"` is used.
The valid options are:
link_type ~
A string that specifies the type of link to create. Possible values:
`md` (|wiki-link-md|)