*wiki.txt* A wiki plugin for Vim *wiki.vim* Author: Karl Yngve Lervåg 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| Example 3: Customize the select method |wiki-advanced-config-3| Example 4: Template matching |wiki-advanced-config-4| ============================================================================== 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. *wiki-filetype-specification* `wiki.vim` uses the filename extension to specify a filetype. Notice that a file extension is not always named the same as the corresponding 'filetype' option value. For example, the common extension for Markdown is `.md`, whereas the corresponding 'filetype' is `markdown`. ------------------------------------------------------------------------------ REQUIREMENTS *wiki-intro-requirements* `wiki.vim` requires Vim 9.1 or Neovim 0.9.5. 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. 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 `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: - `` (normal mode): Either follow the link under the cursor, or create a link from the text under the cursor. - `` (visual mode): Create a link from the selected text. - `gl`: An |operator| to create a link from the operated text. - ``: After following a link: go back to previous location. - ``: Move to next link. - ``: Move to previous link. - `wd`: Delete current page. - `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 - Displaying incoming links (see |WikiLinkIncomingToggle|) - 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 `(wiki-journal-next)` and `(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. ). - 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 `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 `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 `ow` and/or `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 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 activities. 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. 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: . 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 - https://github.com/MeanderingProgrammer/render-markdown.nvim 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 `` to open the selected date in the journal or diary in `wiki.vim`: >vim augroup init_calendar autocmd! autocmd FileType calendar \ nnoremap \ :call wiki#journal#open() augroup END link.vim ~ https://github.com/qadzek/link.vim A plugin for managing long URLs. It converts inline Markdown links to reference-style links, to keep them out of your way. ------------------------------------------------------------------------------ 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 <…> 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 ``. - `` 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 `` to navigate back after following a link. - `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 `` 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]] md ~ This is basically the same as the `wiki` scheme, except it will apply URL decoding while resolving the URLs. < 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 links will use the `md` scheme by default. Markdown image links ~ *wiki-link-md_fig* Markdown image links are similar to markdown links: > ![Caption text](URL) 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]: [label]: [Ref 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 <> <> <> <> 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:[] The `[]` 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-schemes| 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 filetypes for which `wiki.vim` should be enabled. As explained in |wiki-filetype-spec|, the filetypes are specified by the file extension. The first element of the list is considered the default filetype where that is relevant. Default: `['md']` *g:wiki_fzf_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|. Similar to |g:wiki_fzf_pages_opts|, except one should use the field index expression `2..` to obtain the page path. E.g.: >vim let g:wiki_fzf_tags_opts = '--preview "bat --color=always {2..}"' < Default: `''` *g:wiki_fzf_links_opts* A string with additional user options for |WikiLinkAdd|. Similar to |g:wiki_fzf_pages_opts|. < 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 dictionary of functions that allows the user to choose the preferred behaviour for |WikiPage|, |WikiTags|, |WikiToc| and |WikiLinkAdd|. This gives the user a lot of flexibility to specify how these commands will work. See |wiki-advanced-config-3| for more info on customizing it. The following table shows the option keys and the related commands: key command --- ------- `pages` |WikiPages| `tags` |WikiTags| `toc` |WikiToc| `links` |WikiLinkAdd| The dictionary values can be one of two types: - |String|: The name of a function to be executed; - |Funcref|: A function that will be executed. The following builtin alternatives can be used: - fzf (https://github.com/junegunn/fzf.vim): - `wiki#fzf#pages` |g:wiki_fzf_pages_opts| |g:wiki_fzf_force_create_key| - `wiki#fzf#tags` |g:wiki_fzf_tags_opts| - `wiki#fzf#toc` - `wiki#fzf#links` |g:wiki_fzf_links_opts| |g:wiki_fzf_force_create_key| - Lua backend that uses |vim.ui.select| (neovim only!) - `require("wiki.ui_select").pages` - `require("wiki.ui_select").tags` - `require("wiki.ui_select").toc` - `require("wiki.ui_select").links` - Telescope (https://github.com/nvim-telescope/telescope.nvim) - `require("wiki.telescope").pages` - `require("wiki.telescope").tags` - `require("wiki.telescope").toc` - `require("wiki.telescope").links` - fzf-lua (https://github.com/ibhagwan/fzf-lua) - `require("wiki.fzf_lua").pages` - `require("wiki.fzf_lua").tags` - `require("wiki.fzf_lua").toc` - `require("wiki.fzf_lua").links` Default (neovim): >lua vim.g.wiki_select_method = { pages = require("wiki.ui_select").pages, tags = require("wiki.ui_select").tags, toc = require("wiki.ui_select").toc, links = require("wiki.ui_select").links, } < Default (Vim): >vim let g:wiki_select_method = { \ 'pages': function('wiki#fzf#pages'), \ 'tags': function('wiki#fzf#tags'), \ 'toc': function('wiki#fzf#toc'), \ 'links': function('wiki#fzf#links'), \} < *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: reverse ~ Default: |v:false| Whether to print the index in reverse chronological order. 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-schemes| 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 = { \ 'reverse': v:false, \ '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 for a given filetype. The keys are filetype extensions (|wiki-filetype-specification|). 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|) Markdown style links. `wiki` (|wiki-link-wiki|) Wiki style links. `org` (|wiki-link-org|) Orgmode style links. `adoc_xref_bracket` (|wiki-link-adoc_xref_bracket|) `adoc_xref_inline` (|wiki-link-adoc_xref_inline|) AsciiDoc cross-reference style links (angled brackets style or inline `xref:...` style). url_extension ~ A string that, if not empty, will be appended to the target url. url_transform ~ A |Funcref| for a function used to transform operated text to the desired URL. This can also be an |anonymous-function|. If it is undefined, the the original text will be taken as the URL. The function requires a single string argument and should return the target URL without any file extension. This is useful e.g. to substitute space characters, apply URL encoding, or similar. An example may be useful. The following configuration will convert all characters to lowercase and substitute each set of one or more spaces into a single dash character. >vim let g:wiki_link_creation = { \ 'md': { \ 'url_transform': { x -> \ substitute(tolower(x), '\s\+', '-', 'g') }, \ }, \} < path_transform ~ A |Funcref| for a function used to transform an absolute path to the desired URL. This can also be an |anonymous-function| and has the same signature as `url_transform`. The function takes a single string argument that represents the input path to the file for which we are creating a link. It should return the target URL without any file extension. This can be useful for people who use custom resolvers, e.g. to change from using rooted urls like `[description](/Folder/file)` to using relative urls like `[description](../file)`, e.g.: >vim let g:wiki_link_creation = { \ 'md': { \ 'path_transform': { x -> \ fnamemodify( \ wiki#paths#relative(x, expand('%:p')), \ ':h' \ ) \ }, \ }, \} link_text ~ A |Funcref| for a function used by |WikiLinkAdd| to determine the link text of the added link. This can also be an |anonymous-function|. If it is undefined, the default link text is empty. The function requires a single string argument, which is the path to the link target. It should return a string - the desired link text. < Default: >vim let g:wiki_link_creation = { \ 'md': { \ 'link_type': 'md', \ 'url_extension': '.md', \ 'url_transform': { x -> \ wiki#url#utils#url_encode_specific(x, '()') }, \ 'link_text': { url -> wiki#toc#get_page_title(url) }, \ }, \ 'org': { \ 'link_type': 'org', \ 'url_extension': '.org', \ }, \ 'adoc': { \ 'link_type': 'adoc_xref_bracket', \ 'url_extension': '', \ }, \ '_': { \ 'link_type': 'wiki', \ 'url_extension': '', \ }, \} *g:wiki_link_default_schemes* A dictionary to configure the default URL scheme for link types, i.e. the scheme assumed if the URL does not contain an initial scheme specifier. See |wiki-link| for more information about link types and a more proper definition of URLs and schemes. The keys represent the link type and the values are either strings, in which case they specify the default scheme, or dictionaries between filetypes (notice |wiki-filetype-specification|) and default schemes. Note: Reference-style links are special and do not allow to override the scheme. See |wiki-link-reference|. Default: >vim let g:wiki_link_default_schemes = { \ 'wiki': { 'wiki': 'wiki', 'adoc': 'adoc' }, \ 'md': 'md', \ 'md_fig': 'file', \ 'org': 'wiki', \ 'adoc_xref_inline': 'adoc', \ 'adoc_xref_bracket': 'adoc', \ 'adoc_link': 'file', \ 'ref_target': '', \ 'date': 'journal', \ 'cite': 'zot', \} *g:wiki_link_schemes* A dictionary to configure how URLs are handled. The keys represent the schemes and the values are dictionaries that specify the desired `resolver` and `handler` functions: resolver ~ |Funcref|: (URL object) => URL object (OPTIONAL) This function parses the URL object and returns a new URL object. This is useful to e.g. enrich or change the URL before handing it to the `handler`. For example, the `resolver` can be used to apply URL encoding or decoding. handler ~ |Funcref|: (URL object, edit_cmd) => NONE (REQUIRED) A function that takes a possibly resolved URL object and an `edit_cmd` and acts on it. The `edit_cmd` is necessary to implement the various commands like |WikiLinkFollow|, |WikiLinkFollowSplit|, and |WikiLinkFollowTab|. Only the `handler` is required. Both functions has as input a URL object, which is a dictionary that initially looks like this (before any `resolver` has been applied): >vim let l:url = { \ 'url': 'URL HERE', \ 'scheme': 'SCHEME', \ 'stripped': 'URL WITHOUT SCHEME', \ 'origin': 'THE ORIGIN FILE' \} < IMPORTANT: The `resolver` can return an object with different properties. However, the `scheme` attribute is required as it is used to select the appropriate `handler`. Notice that the `resolver` and `handler` needs to "fit". That is, the `handler` may depend on properties of the URL object that are added or changed by a corresponding `resolver`. For example, many of the built-in resolvers will add a `path` attribute that specifies the full path to a file. This is in turn used by the `handler` to open the corresponding file. Finally, notice that built-in resolvers and handlers are found automatically. That is, this option is not the mechanism used internally for resolving the relevant function. Instead, this option provides an interface to users to allow to easily override the built-in functions and add support for new schemes. See |wiki-advanced-configuration| for examples of how to add support for a new scheme and for how to modify one of the existing schemes. Default: `{}` *g:wiki_link_transform_on_follow* This option allows disabling the transform behaviour in |WikiLinkFollow| where "normal" text under the cursor is transformed into links. The behaviour is enabled by default. If disabled, one may still use |WikiLinkTransform| to transform text into links. Default: 1 *g:wiki_link_transforms* This option specifies the template for transforming a specific type of link with |WikiLinkTransform| or |(wiki-link-transform)|. This allows customizing how links are changed when they are transformed. For instance, to add/remove extensions for wiki and markdown style links, one could use: >vim function TransformWikiToMd(url, text, link) abort dict return wiki#link#templates#md( \ a:url . '.wiki', \ empty(a:text) ? a:url : a:text, \ a:link) endfunction function TransformMdToWiki(url, text, link) abort dict let l:url = substitute(a:url, '\.wiki$', '', '') return wiki#link#templates#wiki(l:url, a:text, a:link) endfunction let g:wiki_link_transforms = { \ 'md': 'TransformMdToWiki', \ 'wiki': 'TransformWikiToMd', \} < Default: >vim let g:wiki_link_transforms = { \ 'wiki': 'wiki#link#templates#md', \ 'md': 'wiki#link#templates#wiki', \ 'org': 'wiki#link#templates#org', \ 'adoc_xref_bracket': 'wiki#link#templates#adoc_xref_inline', \ 'adoc_xref_inline': 'wiki#link#templates#adoc_xref_bracket', \ 'date': 'wiki#link#templates#wiki', \ 'cite': 'wiki#link#templates#md', \ 'url': 'wiki#link#templates#md', \} *g:wiki_mappings_use_defaults* Whether or not to use default mappings (see |wiki-mappings-default|). The allowed values are: - `'all'` use all default mappings - `'local'` use only buffer-local default mappings - `'global'` use only global default mappings - `'none'` do not use any of the default mappings Default: `'all'` *g:wiki_mappings_prefix* The common mapping prefix. If you don't like the default `w`, you can change it with this option. Default: `'w'` *g:wiki_mappings_global* *g:wiki_mappings_local* *g:wiki_mappings_local_journal* These options allow one to customize global and buffer local mappings through dictionaries where the keys are the right-hand sides and the values are the desired left-hand side mappings, e.g.: >vim let g:wiki_mappings_global = { \ '(wiki-reload)' : ',wx', \} < This example maps `,wx` to |(wiki-reload)|. The other maps are kept at their default (unless |g:wiki_mappings_use_defaults| specifies otherwise). All default mappings are listed in |wiki-mappings-default|. Some mappings are defined in other modes than normal mode. In this case, one can use the following syntax: >vim let g:wiki_mappings_local = { \ '(wiki-export)' : '', \ 'x_(wiki-export)' : '', \} < Here `` is mapped to |(wiki-export)| in normal mode and visual mode, respectively. The available `` mappings are listed in |wiki-mappings|. For any local mappings that should only be applied in journal entries, consider setting |g:wiki_mappings_local_journal|. For example, similar to above: >vim let g:wiki_mappings_local_journal = { \ '(wiki-journal-prev)' : '[w', \ '(wiki-journal-next)' : ']w', \} < Here we create a pair of mappings `[w` and `]w` to navigate between journal entries. Finally, to disable a map, one may set it to an empty string, e.g.: >vim let g:wiki_mappings_local_journal = { \ '(wiki-tag-list)': '', \ '(wiki-tag-search)': '', \ '(wiki-tag-reload)': '', \ '(wiki-tag-rename)': '', \} < Default: Undefined *g:wiki_root* Option to specify the wiki root path, i.e. the wiki that is opened with the `ww` mapping. The option value must be a string that is either i) a specific path, or ii) the name of a function that returns a path. The latter method allows more flexible determination of the root path, e.g. project specific root paths. An example: >vim function! WikiRoot() let l:local = finddir('wiki', ';./') return !empty(l:local) ? l:local : '~/wiki' endfunction let g:wiki_root = 'WikiRoot' < The `WikiRoot` function first searches for a `wiki` directory in the current directory (the one you see with |:pwd|), then upwords until it finds a `wiki` directory. If no `wiki` directory is found with |finddir|, the function will use `~/wiki` as a fallback. Note: The (returned) path must be either a relative or absolute path to an existing directory. Default: `''` *g:wiki_toc_filetypes* A dictionary to map a filetype extension to a filetype used to parse the TOC. The supported filetype formats are currently: * markdown * asciidoc * org Default: >vim let g:wiki_toc_filetypes = { \ '_' : 'markdown', \ 'md' : 'markdown', \ 'adoc' : 'asciidoc', \ 'org' : 'org', \} *g:wiki_toc_title* The title of TOC listings. Default: `'Contents'` *g:wiki_toc_depth* The number of sections to parse for the TOC. Default: `6` *g:wiki_tag_list* A dictionary that specifies the default options for |WikiTagList|. Default: >vim let g:wiki_tag_list = { \ 'output' : 'loclist', \} *g:wiki_tag_search* A dictionary that specifies the default options for |WikiTagSearch|. Default: >vim let g:wiki_tag_search = { \ 'output' : 'loclist', \} *g:wiki_tag_parsers* A list of parsers used to source the tags. The parsers are tried in the order they're specified. If a parser matches, then it is selected and used. A tag parser is a dictionary object with the following keys: match ~ A function (|FuncRef|) that takes a single argument, the current line. It should return |v:true| or 1 if the line contains any tags. parse ~ A function (|FuncRef|) that takes a single argument, the current line. It should return a list of the tags in the given line. make ~ A function (|FuncRef|) that takes two arguments: a list of tags, and the current line. It should return a new line with the list of tags formatted appropriately. This new line will replace the current line. This function is used by |WikiTagRename|. re_findstart ~ `OPTIONAL` A regular expression (|String|) that should match the start of the current tag for tag completion (|wiki-completion|). See |g:wiki#tags#default_parser| for an example. As an example, one can use the following to parse tags in lines that match `tags: keyword1, keyword2` in addition to the default parser: >vim let g:wiki_tag_parsers = [ \ g:wiki#tags#default_parser, \ { 'match': {x -> x =~# '^tags: '}, \ 'parse': {x -> split(matchstr(x, '^tags:\zs.*'), '[ ,]\+')}, \ 'make': {t, x -> 'tags: ' . empty(t) ? '' : join(t, ', ')}} \] < See |g:wiki#tags#default_parser| for details on the default tag parser. Default: >vim let g:wiki_tag_parsers = [g:wiki#tags#default_parser] < *g:wiki_tag_scan_num_lines* A number of lines to read from the top of a page when scanning tags. To scan lines from the bottom, use a negative number, e.g. >vim let g:wiki_tag_scan_num_lines = -10 < To scan the entire files, use: >vim let g:wiki_tag_scan_num_lines = 'all' < Default: >vim let g:wiki_tag_scan_num_lines = 15 *g:wiki_templates* A list of templates for prefilling new pages. Each template should be specified as a dictionary with a matcher and a source. Matching may be done with regular expressions or with user functions. Similarly, sources can be specified as a file source as specified in |wiki-templates-format|, or as a user function with a single argument `context` as specified in |wiki-templates-context|. The possible dictionary keys of a template are: match_re ~ |String| A regular expression that will be matched against the new page name. Note: The name is not the same as the path and it does not include the file name extension. For more advanced matching, you need a custom matcher function, i.e. the next key. match_func ~ |Funcref| A function that should return |v:true| if the template should be applied or |v:false| if it should not apply. source_filename ~ |String| The path to a template file. If this is a relative path, then it will be relative to whichever path Vim or neovim is currently at when the template is executed. If the template file is not found, then the template will not be applied and the next template in the list will be tried. source_func ~ |Funcref| A user function that can use e.g. |append()| to add lines to the file. For example: >vim function! TemplateFallback(context) call append(0, '# ' . a:context.name) call append(1, '') call append(2, 'Foobar') endfunction let g:wiki_templates = [ \ { 'match_re': 'index', \ 'source_filename': '/home/user/templates/index.md'}, \ { 'match_re': 'foo', \ 'source_filename': '.footemplate.md'}, \ { 'match_func': {x -> v:true}, \ 'source_func': function('TemplateFallback')}, \] < See |wiki-advanced-config-4| for an example of matching file names and directory structures. Default: `[]` *g:wiki_template_month_names* A list of the names for each month. Used e.g. for interpolating month names in the month template, |g:wiki_template_title_month|. Default: `['January', 'February', ..., 'December']` *g:wiki_template_title_month* A string that specifies the title of the month template. The following keys are interpolated: `%(month)` Month number `%(month-name)` Name of month (see |g:wiki_template_month_names|) `%(year)` Year (4 digits) See |wiki-templates-journal-summaries| for more info. Default: `'# Summary, %(year) %(month-name)'` *g:wiki_template_title_week* A string that specifies the title of the week template. The following keys are interpolated: `%(week)` Week number `%(year)` Year (4 digits) See |wiki-templates-journal-summaries| for more info. Default: `'# Summary, %(year) week %(week)'` *g:wiki_ui_method* A dictionary that specifies the backend for various input methods. The method names are the keys of the dictionary and the backend choices are the values. The available methods: confirm: Confirm dialogues, e.g. before deleting a pages. input: Input dialogues, e.g. when renaming a page. select: Selection dialogues, e.g. when creating a link from text with |(wiki-link-follow)|, where the text can refer to multiple target pages. The available backends: nvim: Popup menu created with neovim APIs. vim: Currently there is no Vim-specific implementation. Setting the backend to "vim" will currently fallback to "legacy". legacy: Legacy backends that are created by |:echo|ing the menus and using |input()| and similar for getting input. Default: >vim " On neovim let g:wiki_ui_method = { \ 'confirm': 'nvim', \ 'input': 'nvim', \ 'select': 'nvim', \} " Otherwise let g:wiki_ui_method = { \ 'confirm': 'legacy', \ 'input': 'legacy', \ 'select': 'legacy', \} *g:wiki_viewer* A dictionary that specifies which viewer to use for any given filetype, see |wiki-filetype-specification|. The entry `_` specifies the fallback or generic viewer. This option thus allows one to setup different viewers for different file types that are used by the generic link scheme handler (|g:wiki_link_schemes|) and by |WikiExport|. The special value `':edit'` indicates to open the file in the current Vim or neovim session as with |:edit|. Default: OS dependent >vim " Common let g:wiki_viewer = { \ 'md' : ':edit', \ 'wiki' : ':edit' \} " Linux let g:wiki_viewer._ = 'xdg-open' " MacOS let g:wiki_viewer._ = 'open' *g:wiki_write_on_nav* Option to specify whether or not to save the current file automatically before navigating (forward or backward) between wiki links. Default: 1 *g:wiki_zotero_root* A string that specifies the Zotero root folder used for the Zotero URL scheme, see |wiki-link-schemes|. Default: `'~/.local/zotero'` ============================================================================== EVENTS *wiki-events* Users events can be used by users to add custom behaviour after an event is triggered. It is probably best explained by a simple example: >vim augroup MyWikiAutocmds autocmd! autocmd User WikiLinkFollowed normal! zz autocmd User WikiBufferInitialized \ nmap gf (wiki-link-follow) autocmd User WikiBufferInitialized WikiLinkIncomingToggle augroup END `wiki.vim` provides the following |User| events: *WikiBufferInitialized* Event is triggered after the buffer features are initialized. This event allows one to apply custom mappings and similar. *WikiLinkFollowed* Event is triggered after a link has been followed. *WikiReloadPost* Event is triggered after `wiki.vim` has been reloaded with |WikiReload|. ============================================================================== MAPPINGS AND COMMANDS *wiki-mappings* Here we describe the mappings and commands provided by `wiki.vim`. We first list the default mappings, then provide a full reference of all mappings and commands. ------------------------------------------------------------------------------ DEFAULT MAPPINGS *wiki-mappings-default* This is a list of default mappings. Follow the help tags to see more detailed description of each mapping. The default mappings can be changed with the following configuration options: - |g:wiki_mappings_use_defaults| - |g:wiki_mappings_prefix| - |g:wiki_mappings_global| - |g:wiki_mappings_local| - |g:wiki_mappings_local_journal| In the table below, the mode specifier is a single letter which indicates which mode the mapping is valid in. See e.g. |nmap|, |imap|, |omap| or |xmap| for more information about the different modes. The lines annotated with `[GLOBAL]` specify global mappings available anywhere, and the lines annotated `[JOURNAL]` are only available within the journal. Note: In the below list, the default prefix of `w` is assumed. It can easily be changed with |g:wiki_mappings_prefix|. Note: For those who want to adjust the mappings, it may be useful to know that the default maps are available in a dictionary format compatible with the above mentioned configuration options. The global mappings are defined in the wiki.vim source code in `plugin/wiki.vim` (cf. the `s:mappings` dictionary), whereas the buffer mappings are defined in `autoload/wiki/buffer.vim` (cf. the `l:mappings` dictionary). MODE LHS RHS ~ ==== === === `n` ww |(wiki-index)| [GLOBAL] `n` ww |(wiki-journal)| [GLOBAL] `n` |(wiki-pages)| [GLOBAL] `n` |(wiki-tags)| [GLOBAL] `n` wn |(wiki-open)| [GLOBAL] `n` wx |(wiki-reload)| [GLOBAL] `n` wgb |(wiki-graph-find-backlinks)| `n` wgr |(wiki-graph-related)| `n` wgc |(wiki-graph-check-links)| `n` wgC |(wiki-graph-check-links-g)| `n` wgO |(wiki-graph-check-orphans)| `n` wgi |(wiki-graph-in)| `n` wgo |(wiki-graph-out)| `n` wf |(wiki-link-transform)| `n` wd |(wiki-page-delete)| `n` wr |(wiki-page-rename)| `n` wt |(wiki-toc-generate)| `n` wT |(wiki-toc-generate-local)| `n` wp |(wiki-export)| `x` wp |(wiki-export)| `n` wll |(wiki-link-show)| `n` wlh |(wiki-link-extract-header)| `x` wlh |(wiki-link-extract-header)| `n` wli |(wiki-link-incoming-toggle)| `n` wlI |(wiki-link-incoming-hover)| `n` wsl |(wiki-tag-list)| `n` wsr |(wiki-tag-reload)| `n` wsn |(wiki-tag-rename)| `n` wss |(wiki-tag-search)| `nx` wa |(wiki-link-add)| `i` |(wiki-link-add)| `n` wlr |(wiki-link-remove)| `n` |(wiki-link-next)| `n` |(wiki-link-prev)| `n` |(wiki-link-follow)| `n` |(wiki-link-follow-split)| `n` |(wiki-link-follow-vsplit)| `n` u |(wiki-link-follow-tab)| `n` |(wiki-link-return)| `n` gl |(wiki-link-transform-operator)| `x` |(wiki-link-transform-visual)| `ox` au |(wiki-au)| `ox` iu |(wiki-iu)| `ox` at |(wiki-at)| `ox` it |(wiki-it)| `n` |(wiki-journal-prev)| [JOURNAL] `n` |(wiki-journal-next)| [JOURNAL] `n` |(wiki-journal-copy-tonext)| [JOURNAL] `n` wu |(wiki-journal-toweek)| [JOURNAL] `n` wm |(wiki-journal-tomonth)| [JOURNAL] ------------------------------------------------------------------------------ MAPPINGS AND COMMANDS REFERENCE *wiki-mappings-reference* *WikiEnable* Load `wiki.vim` for the current file. If the current file type is not in |g:wiki_filetypes|, then it will be added, so that interwiki links will be possible. *(wiki-index)* *WikiIndex* *WikiIndex!* Go to the wiki index for the main wiki specified by |g:wiki_root| and |g:wiki_index_name|. `:WikiIndex!` (with the bang) will first look the index of the current local wiki. This is useful for users that maintains multiple wikis. The command falls back to the main wiki. *(wiki-journal)* *WikiJournal* *WikiJournal!* Go to the current journal entry in the main wiki. For the default journal frequency, this means today's entry. See also |g:wiki_journal| and the `frequency` description. `:WikiJournal!` (with the bang) will first look for a journal in the current local wiki. It falls back to the main wiki journal if no local wiki is found. *(wiki-pages)* *WikiPages* *WikiPages!* List wiki files in the main wiki. Select from list to open target page. This uses the UI select method defined by |g:wiki_select_method|. fzf specific behaviour ~ If |g:wiki_select_method| is `'fzf'`, then it is possible to create a new page by pressing |g:wiki_fzf_force_create_key| (alt-enter, by default). That is, a page whose name is equal to the fzf query will be created if it doesn't already exist. If the page exists, the existing page will be opened. For convenience, if the input query does not have any results, simply pressing enter will also create a page. E.g., if you searched for "My Fzf Page", and this term does not exist, then it will instead open a new page "My Fzf Page.wiki" (or similar, depending on the value of other options). `:WikiPages!` (with the bang) will first look for a local wiki and list files for that if it is found. It falls back to the main wiki if no local wiki was detected. *(wiki-tags)* *WikiTags* *WikiTags!* List tags from the main wiki. Allows to search for and navigate to a tag. This uses the UI select method defined by |g:wiki_select_method|. `:WikiTags!` (with the bang) will first look for a local wiki and list tags for that if it is found. It falls back to the main wiki if no local wiki was detected. *(wiki-open)* *WikiOpen* `:[range]WikiOpen [page]` Open (or create) a page. The command supports completion of the page argument. If the `page` argument is not provided, then ask for user input to specify the page name. When not already inside a wiki, the wiki root is given by |g:wiki_root|. The settings from |g:wiki_link_creation| are applied based on the current 'filetype'. If the filetype is not specified or if it is not listed in |g:wiki_filetypes|, then the first filetype in this list is assumed. *(wiki-reload)* *WikiReload* Reload the wiki plugin. Mostly useful for plugin development. *(wiki-graph-find-backlinks)* *WikiGraphFindBacklinks* Find backlinks to current page. *(wiki-graph-related)* *WikiGraphRelated* Open a scratch buffer that shows how a page relates to other pages by links into (on the left) and out of (on the right). *(wiki-graph-check-links)* *WikiGraphCheckLinks* Check the current wiki page for broken links. If any broken links are found, they are added to the location list (|location-list|) and the location list is opened. *(wiki-graph-check-links-g)* *WikiGraphCheckLinksG* Check the entire wiki for broken links. If any broken links are found, they are added to the location list (|location-list|) and the location list is opened. This can take a while if you have a large wiki. *(wiki-graph-check-orphans)* *WikiGraphCheckOrphans* Check the entire wiki for orphaned pages; i.e. pages without any incoming links. These pages are added to the location list (|location-list|) and the location list is opened. *(wiki-graph-in)* *(wiki-graph-out)* *WikiGraphIn* *WikiGraphOut* Show links in to or out of the current page. A count may be given to show a specified depth of links. Notice that a large count can take a while if you have a large wiki. *(wiki-link-remove)* *WikiLinkRemove* Remove the link under the cursor. This behaves as described in the following table: Original link Result after operation ~ ------------- ---------------------- ~ This is [a link](url) This is a link This is [[url|a link]] This is a link This is a [](url) This is a url This is a [[url]] This is a url *(wiki-link-add)* *WikiLinkAdd* List the wiki files in the current wiki. Select from the list to add a link to that target page. This uses the UI select method defined by |g:wiki_select_method|. The mapping also works from insert and visual mode. In visual mode, the selected text becomes the link text. Otherwise, the link text is determined by the `link_text` key of |g:wiki_link_creation|. fzf specific behaviour ~ If |g:wiki_select_method| is `'fzf'`, then it is possible to create a new page by pressing |g:wiki_fzf_force_create_key| (alt-enter, by default). That is, a link whose name is equal to the fzf query will be created. For convenience, if the input query does not have any results, simply pressing enter will also create a page. E.g., if you searched for "My Fzf Page", and this term does not exist, then it will instead create a new link "My Fzf Page.wiki" (or similar, depending on the value of other options). *(wiki-link-next)* *WikiLinkNext* Go to next link. *(wiki-link-prev)* *WikiLinkPrev* Go to previous link. *(wiki-link-follow)* *WikiLinkFollow* Follow a link. If the text under the cursor is not a link, then it will be converted via |WikiLinkTransform|, unless |g:wiki_link_transform_on_follow| is disabled. *#User#WikiLinkFollowed* The user autocommand `WikiLinkFollowed` is triggered after a wiki link has been followed. This allows the user to add custom functionality after following wiki links. For example, to center the cursor inside the window after following a link: >vim augroup MyWikiAutocmds autocmd! autocmd User WikiLinkFollowed normal! zz augroup END *(wiki-link-follow-split)* *(wiki-link-follow-vsplit)* *WikiLinkFollowSplit* Similar to |WikiLinkfollow|, except wiki links are followed in a |split|. The `vsplit` mapping uses a vertical split. Modifiers such as |:vertical| are allowed for the command, e.g. >vim :vert topleft WikiLinkfollowSplit *(wiki-link-follow-tab)* *WikiLinkFollowTab* Similar to |WikiLinkfollow|, except wiki links are followed in a |tabedit|. *(wiki-link-return)* *WikiLinkReturn* Go back to previous page, i.e. undo the last follow operation. *(wiki-link-transform)* *(wiki-link-transform-visual)* |xmap| *(wiki-link-transform-operator)* |map-operator| *WikiLinkTransform* Transform a link from one type to another based on the value of |g:wiki_link_transforms|. Additionally, this command and the mappings can be used to convert regular text to a link. The behaviour is controlled by |g:wiki_link_creation| and follows the following set of rules. If we are inside the journal: ~ We would generally not want anything other than journal entries within the journal directory. Therefore we have some special rules here: - Check if any page exists inside the journal that matches the selected text/current word. If so, create link to that page. - Check if any page exists at the wiki root that matches the selected text/current word. If so, create link to that page. - Check if there are pages at the wiki root where the selected text/current word matches at the beginning. If so, let user choose which page to link to. - If neither of the above, then create a link to a page with name based on the selected text/current word at the wiki root. Everywhere else: ~ The general idea is that links should be relative to the current directory. To make a link to a page at root, one may simply prepend a `/` to specify a "rooted" link. The conversion rules are therefore as follows: - Check if any page exists inside the current directory that matches the selected text/current word. If so, create link to that page. - Check if there are pages at the current directory where the selected text/current word matches at the beginning. If so, let user choose which page to link to. - If neither of the above, then create a link to a page with name based on the selected text/current word in current directory. *(wiki-link-show)* *WikiLinkShow* Show some info on link under cursor. *(wiki-link-extract-header)* *WikiLinkExtractHeader* Set link titles from the first header of the target file. In normal mode, this works on the link under the cursor. In visual mode, it works on all links in the current visual selection. *(wiki-link-incoming-toggle)* *WikiLinkIncomingToggle* NB: Neovim only! Toggle display of incoming links. When enabled, the buffer will be enriched with signs and virtual text to indicate any incoming links. *(wiki-link-incoming-hover)* *WikiLinkIncomingHover* When activated at a line to which there is an incoming link, this will show a menu that lists all incoming links to this line. If one of these are selected, you will navigate there. *(wiki-page-delete)* *WikiPageDelete* Delete wiki page. *(wiki-page-rename)* *WikiPageRename* Rename wiki page (will update all links to the page). *(wiki-toc-generate)* *WikiTocGenerate* Create/Update table of contents. *(wiki-toc-generate-local)* *WikiTocGenerateLocal* Create/Update table of contents (section local variant). *(wiki-journal-index)* *WikiJournalIndex* Insert a sorted list of links to all journal pages below the cursor. It uses the link type specified in |g:wiki_link_creation| for the current filetype. *(wiki-journal-next)* *WikiJournalNext* Go to the next journal entry (at current level of daily, weekly, monthly). *(wiki-journal-prev)* *WikiJournalPrev* Go to the previous journal entry (at current level of daily, weekly, monthly). *(wiki-journal-copy-tonext)* *WikiJournalCopyToNext* Copy current entry to the next (unless that entry already exists). Also opens the next entry. *(wiki-journal-toweek)* *WikiJournalToWeek* Go to week summary. If not existing, then parse the day entries to make a first draft. The title is given by |g:wiki_template_title_week|. For more info, see |wiki-templates-journal-summaries|. *(wiki-journal-tomonth)* *WikiJournalToMonth* Go to month summary. If not existing, then parse the day entries and relevant week summaries to make a first draft. The title is given by |g:wiki_template_title_month|. See also |wiki-templates-journal-summaries|. *(wiki-export)* *WikiExport* `:[range]WikiExport [options] [fname]` Export the current wiki file with `pandoc` (https://pandoc.org/). The main argument `fname` specifies the target filename and format (implied by the file extension), e.g. `test.pdf` or `test.html`. If `fname` is not specified, then the `-path` option is used to determine the output location. In this case, the `-view` option is activated regardless of the basic configuration. Available options are given below. The default values are specified in the dictionary |g:wiki_export|. -args ~ Specify extra arguments for `pandoc`. -from-format FRMT | -f FRMT ~ Specify format of the wiki page. -ext EXT ~ Specify extension to use if `fname` is not provided. -link_ext_replace ~ Set to true to replace in-wiki link extensions with html. This enables in-browser wiki navigation, but for it to work well, it requires that: `-ext` is set to `html`. -output ~ Set output directory where the exported file is stored. Relative paths are relative to the wiki root. -view ~ Set to true to open documents with specified `viewer` by default. -viewer PATH ~ Specify viewer to use to open the exported file. This implies `-view` and overrides the |g:wiki_viewer| option. Note: This feature requires `pandoc` (https://pandoc.org/) to build the output files. *(wiki-tag-list)* *WikiTagList* List all tags and the wiki pages that contain them. Available options are (use |g:wiki_tag_list| to set default values): -output TRG ~ Where to put the search result. `TRG` may be one of: - `loclist` Use |location-list| - `echo` Display results on screen - `scratch` Add results to a scratch buffer - `cursor` Insert result below cursor *(wiki-tag-reload)* *WikiTagReload* Source wiki files and reload tags. *(wiki-tag-search)* *WikiTagSearch* [options] [tag] List wiki pages that contain the desired `tag`. If the argument `tag` is not supplied, the command asks for input. See also |wiki-tags| for more information on the tags feature and |WikiTags| for an alternative search mechanism. Available options are (use |g:wiki_tag_search| to set default values): -output TRG ~ Where to put the search result. `TRG` may be one of: - `loclist` Use |location-list| - `echo` Display results on screen - `scratch` Add results to a scratch buffer - `cursor` Insert result below cursor *(wiki-tag-rename)* *WikiTagRename* [old_tag] [new_tag] Rename `old_tag` to `new_tag` in all pages. If zero or one arguments are supplied, the command asks for input. This command uses the `make` function of |g:wiki_tag_parsers|. *(wiki-au)* Text object that matches an entire link object. *(wiki-iu)* Text object that matches the URL part of a link. *(wiki-at)* *(wiki-it)* Text object for link texts. For a link such as `[[url|text]]`, the `at` variant will match `|text`, whereas `it` only matches `text`. *(wiki-toc)* *WikiToc* Open a table of contents for the current wiki page with the UI select method specified by |g:wiki_select_method|. ============================================================================== COMPLETION *wiki-completion* `wiki.vim` provides an |omni-complete| function to complete various link URLs and tags. The feature is enabled by default; set |g:wiki_completion_enabled| to 0 to disable it. Link completion is available for: - Markdown links with implied `wiki` scheme (|wiki-link-md|) - Wiki links with implied `wiki` scheme (|wiki-link-wiki|) - AsciiDoc links with implied `adoc` scheme (|wiki-link-adoc_xref_bracket|) - Cite links with implied `zot` scheme (|wiki-link-cite|) Tag completion completes tags where the tag parser's `re_findstart` value matches the current line. See |g:wiki#tags#default_parser| for more info. Related settings: - |g:wiki_completion_enabled| - |g:wiki_completion_case_sensitive| ============================================================================== TAGS *wiki-tags* Wiki pages may be tagged with keywords for organization. It is relatively easy to define and specify custom tag parsers with |g:wiki_tag_parsers|. `wiki.vim` ships a default parser that is automatically used, see |wiki-tags-default|. The number of lines in which tags are recognized can be customized by modifying the |g:wiki_tag_scan_num_lines| variable. Related commands: - |WikiTagList| - |WikiTagReload| - |WikiTagSearch| - |WikiTagRename| - |WikiTags| Related settings: - |g:wiki_tag_list| - |g:wiki_tag_search| - |g:wiki_tag_parsers| ------------------------------------------------------------------------------ DEFAULT TAG PARSER *wiki-tags-default* *g:wiki#tags#default_parser* The default tag parser adds support for tags within colons, i.e. `:tag-name:`. Multiple tags may be specified both with `:tag1: :tag2:` and with the short form `:tag1:tag2:`. The tag name must consist of purely non-space characters. The full implementation is given in `autoload/wiki/tags.vim` and should be used as a template for those who want to make a custom parser. For simple customizations, one may customize the default parser by adjusting `re_match`, `re_findstart`, `re_parse`, and `make`. E.g., to instead recognize hashed tags like `#tag1` and `#my-other-tag`, one could add the following in one's vimrc: >vim let s:tag_parser = deepcopy(g:wiki#tags#default_parser) let s:tag_parser.re_match = '\v%(^|\s)#\zs[^# ]+' let s:tag_parser.re_findstart = '\v%(^|\s)#\zs[^# ]+' let s:tag_parser.re_parse = '\v#\zs[^# ]+' let s:tag_parser.make = {t, l -> empty(t) ? '' : join(map(t, '"#" . v:val'))} let g:wiki_tag_parsers = [s:tag_parser] ------------------------------------------------------------------------------ ORGMODE TAG PARSER *wiki-tags-orgmode* *g:wiki#tags#orgmode_parser* `wiki.vim` also ships a parser for Orgmode style tags, though it is not activated my default. The main difference to the default parser is that Orgmode style tags always use the short form `:tag1:tag2:`. They also only ever appear at the end of headlines and the `#+FILETAGS:` property. The full implementation is given in `autoload/wiki/tags.vim`. It is very similar to |g:wiki#tags#default_parser|, so it is not repeated here. To use the Orgmode tag parser, simply specify it in |g:wiki_tag_parsers|: >vim let g:wiki_tag_parsers = [g:wiki#tags#orgmode_parser] ============================================================================== TEMPLATES *wiki-templates* New pages are empty by default. However, it is possible to define templates for prefilling new pages. Templates are specified with the option |g:wiki_templates|, and if a template matches the new page it will be applied. Only the first template that matches will be applied. The templates can be specified as user functions or as template files. User functions assume a single variable such as described in |wiki-templates-context|. The template files should be formatted as described in |wiki-templates-format|. There is also a special kind of journal summary template. It is described in detail in |wiki-templates-journal-summaries|. See |wiki-advanced-config-4| for an example of how to match templates against file names and directory structures. Related settings: - |g:wiki_templates| ------------------------------------------------------------------------------ TEMPLATE FUNCTION CONTEXT *wiki-templates-context* The functions in |g:wiki_templates| assume a single argument `context` which is a dictionary with the following values: Key Description Example ~ === =========== ======= `name` Filename (no extension) "New Page" `path` Full path "/path/to/wiki/sub/New Page.md" `path_wiki` Wiki path "/sub/New Page.md" `origin` Origin position and link `{...}` `date` ISO date 2021-07-01 `time` Time (24h format) 19:30 The `origin` value is a dictionary that represents the position before following a link to create the page. It also includes the link object itself. One may expect it to have one or more of the following keys: file ~ Filename of file that contains the link. curpos ~ Cursor position when the link was followed/activated. link ~ A dictionary that contains the link object itself. This includes the link url and link text. The text part can be of interest if one wants to use it as the title of a document. ------------------------------------------------------------------------------ TEMPLATE FILE FORMAT *wiki-templates-format* A template file is essentially a simple text file to your liking. There are two rules that allow dynamic templates: 1. Variable substitution with `{variable}` strings. The allowed variables are the same as those available in |wiki-templates-context|. To access the contents of the `origin` dictionary, one may use dot notation, e.g. `{origin.origin}` and `{origin.pos_start}`. 2. Function substitution with `{{Function Text String Here}}` strings. The context dictionary (|wiki-templates-context|) is always passed as the first argument. The text string, if it is not empty, is passed as a single string argument. The function is assumed to return either a string or a list of strings. The first rule is applied first, which allows the arguments in Rule 2 to be variable substitutions. Pre-defined functions Description ~ ===================== =========== `wiki#template#case_title(ctx, string)` Returns `string` title cased An example ~ It may be hard to fully understand how all of the above works, so an example is in order. Let's assume you keep a separate blog directory in your wiki, then you could add a `.template.md` file with the following content to ensure that you follow the same structure: > # {{wiki#template#case_title {name}}} Created: {date} {time} {{CustomUserFunc A new blog post}} # Introduction # Conclusion Here `CustomUserFunc` must be defined, e.g. in your vimrc file. As explained, the first argument is `ctx` - the context dictionary from |wiki-templates-context|. The text "A new blog post" is passed as the second argument as a string. The full content of the function is of course up to the user, but it would look something like this: >vim function! CustomUserFunc(ctx, text) abort return a:ctx.name . ': ' . substitute(a:text, 'A new', 'An old', '') endfunction ------------------------------------------------------------------------------ JOURNAL SUMMARIES *wiki-templates-journal-summaries* `wiki.vim` supports parsing the journal entries in order to make weekly and monthly summaries. A summary is automatically created when a summary file is opened. One may also move from a daily entry to the corresponding week with |WikiJournalToWeek|, and similarly to the corresponding month with |WikiJournalToMonth|. Again, if these entries do not exist, they are automatically created and journal entries are parsed to fill the contents. The parsed results typically need manual editing, and it currently only works for "list based" journals. That is, the summary generator works like this: * First collect the text from entries to be summarized. * Parse the text as topic lists (see example below). * Combine the topic list entries in chronological order. * Ignore all text after the first heading. An example of a journal entry that will be parsed properly: > Topic 1 * List based summary * With perhaps * sub lists Topic 2 * List based summary * With perhaps * sub lists Topic 3 * Link to [[#Specific note ...]] # Specific note (e.g. meeting note or similar) Everything from this section header and on will be ignored. Note: There is no guarantee that this feature will work well if the journal entries are structured in other ways! However, the summary is generated through the template system, so it can be customized or replaced with |g:wiki_templates|. See |wiki-advanced-config-5| for an example of how to prefill the weekly summary with a custom template. The summary file-name format is defined by |g:wiki_journal|`.date_format.weekly` and |g:wiki_journal|`.date_format.monthly`. Related settings: - |g:wiki_journal| - |g:wiki_template_title_week| A string that specifies the title of the weekly summary. - |g:wiki_template_title_month| A string that specifies the title of the monthly summary. Related commands: - |WikiJournalToWeek| - |WikiJournalToMonth| ============================================================================== ADVANCED CONFIGURATION GUIDE *wiki-advanced-configuration* `wiki.vim` provides several options that allow users to customize its behavior, such as how link URLs are resolved and handled, how pages are selected, and how templates are matched against new pages. The following are some examples of how to use these options. Several of the examples build upon the built-in functions. These functions are not documented, but most of the useful ones should be relatively self documented. The link-related functions are found here: - `autoload/wiki/url/resolvers.vim` - `autoload/wiki/url/handlers.vim` - `autoload/wiki/url/utils.vim` Example 1: New scheme `test` ~ *wiki-advanced-config-1* In this example, we add a new scheme `test` that should act like the `wiki` scheme, except we want the handler to simply print the URL object. This way, we could inspect the object provided to the handler function, which could be useful to understand what you have to work with. In Vimscript, the example looks like this: >vim function! MyTestHandler(resolved, ...) abort echo a:resolved endfunction let g:wiki_link_schemes = { \ 'test': { \ 'resolver': function('wiki#url#resolvers#wiki'), \ 'handler': function('MyTestHandler'), \ } \} The same, but for Lua in neovim: >lua vim.g.wiki_link_schemes = { test = { resolver = vim.fn["wiki#url#resolvers#wiki"], handler = function(x) print(vim.inspect(x)) end, } } Example 2: Adjust the `wiki` scheme to apply URL decoding ~ *wiki-advanced-config-2* The standard `wiki` scheme does not perform any form of URL encoding or decoding. If you want the link URLs to be encoded, but the actual file names to be unencoded, then you could do something like this: >vim " This is basically the same as wiki#url#resolvers#wiki, except we added " a line to decode the encoded URL before we resolve the path. function! MyWikiResolver(url) abort let l:url = deepcopy(a:url) let l:url.anchor = wiki#url#utils#extract_anchor(l:url.stripped) let l:path = split(l:url.stripped, '#', 1)[0] let l:path = wiki#url#utils#url_decode(l:path) let l:url.path = wiki#url#utils#resolve_path(l:path, l:url.origin) return l:url endfunction " Change the wiki scheme resolver let g:wiki_link_schemes = { \ 'wiki': { \ 'resolver': function('MyWikiResolver'), \ } \} " Only change the url_transform - will keep other parts at default settings let g:wiki_link_creation = { \ 'md': { \ 'url_transform': { x -> wiki#url#utils#url_encode(x) }, \ }, \ 'wiki': { \ 'url_transform': { x -> wiki#url#utils#url_encode(x) }, \ }, \} Example 3: Customize the `wiki` select method ~ *wiki-advanced-config-3* `wiki.vim` allows to customize the select method used for |WikiPage|, |WikiTags| and |WikiToc|. Built-in choices include Telescope, |vim.ui.select|, fzf.vim, and fzf-lua (see |g:wiki_select_method|). But you can use whatever fuzzy finder you want by creating the selection functions yourself. See e.g. `lua/wiki/fzf_lua.lua` for an example of how to do this. Example 4: Template matching ~ *wiki-advanced-config-4* Templates are matched against new pages with |g:wiki_templates|. Matching file names and directory structures is done a bit differently. To match a file name, you can use a regular expression: >lua vim.g.wiki_templates = { { match_re = [[\d\d\d\d-\d\d-\d\d]], source_filename = "/home/USER/wiki/.templates/daily.md" }, } To match a template for a new file in an ISO date-based directory structure, you might use a custom matcher function instead: >lua vim.g.wiki_templates = { { match_func = function(context) return context.path_wiki:find "%d%d%d%d/%d%d/%d%d" end, source_filename = "~/wiki/templates/daily.md" }, } Example 5: Prefill the weekly summary with a custom template ~ *wiki-advanced-config-5* The weekly summary generated for |WikiJournalToWeek| is created through the built-in |wiki-templates-journal-summaries| logic. And that logic is probably quite opinionated. But you can supply your own template for the weekly summary nodes by using |g:wiki_templates|. To keep the auto-generated summary and add your own scaffolding below it, let the template call the built-in parser and then append extra lines: >lua vim.g.wiki_templates = { { -- Matches weekly journal nodes like "2024_w05". -- The default weekly format is %Y_w%V; adjust the regex if you -- changed g:wiki_journal.date_format.weekly. match_re = [[\d\d\d\d_w\d\d]], source_func = function(ctx) -- ctx.name is the node name, e.g. "2024_w05" local year, week = ctx.name:match "(%d%d%d%d)_w(%d%d)" -- Reuse the built-in day-entry parser to prefill the summary vim.fn["wiki#template#weekly_summary"](year, week) -- Append your own scaffolding below the generated summary vim.fn.append(vim.fn.line "$", { "", "## Goals for next week", "", "* ", }) end, }, } If you want a fully custom template and prefer to include the daily entries verbatim at the bottom, you can read the entries yourself instead of reusing `wiki#template#weekly_summary`: >lua vim.g.wiki_templates = { { match_re = [[\d\d\d\d_w\d\d]], source_func = function(ctx) local year, week = ctx.name:match "(%d%d%d%d)_w(%d%d)" -- A custom template local lines = { "# Summary, " .. year .. " week " .. week, "", "## Highlights", "", "## Goals for next week", "", "## Journal entries", } -- Append the full content of each existing daily entry of the week. -- wiki#url#resolve maps the ISO date to the journal file path, so it -- respects g:wiki_journal.date_format and the journal root. for _, date in ipairs(vim.fn["wiki#date#get_week_dates"](week, year)) do local url = vim.fn["wiki#url#resolve"]("journal:" .. date) if vim.fn.filereadable(url.path) == 1 then table.insert(lines, "") table.insert(lines, "### " .. date) table.insert(lines, "") vim.list_extend(lines, vim.fn.readfile(url.path)) end end vim.fn.append(0, lines) end, }, } Note that `match_re` is a Vim regular expression tested against the node name (`ctx.name`), whereas the Lua `string.match` patterns above are used to parse the year and week from that name. The same approach works for the monthly summary by matching `\d\d\d\d_m\d\d` and iterating over the days of the month. vim:tw=78:ts=8:ft=help:norl:fdm=marker:cole=2: