box.matto.nl
Enjoying Open Source Software

Posted:

Using Vimwiki tags

Vimwiki, a very powerful wiki-like plugin for Vim, features among other things support for tags.

Adding tags

The Vimwiki format for tags is colon-tagname-colon, like 

:this-is-my-tag:

It is also possible to combine several tags, with the colon as separator. Like:

:this-is-my-tag:some-other-tag:third-tag:

Scope of a tag

  • When a tag or some tags are entered on the top two lines of the Vimwiki-file, the tags are considered to refer to the whole page.
  • When a tag is entered just below a header, than the tag refers to that header. This is the case when the tagline is in the two lines immediate below the header.
  • When a tag is entered on a different line, than the tags refers to that specific line,

Building a tag index

Tags have to be indexed, for this Vimwiki uses a tagfile. This tag file is needed for several functions. The tagfile is a file in the root of the wiki, with the filename ".vimwiki_tags".

The command ::VimwikiRebuildTags the tag-file gets rebuild.

There is an option to keep this tag file automagicly updated on each file save, In the .vimrc file add the option "auto_tags':1" to the vimwiki definition line, e.g.:

let g:vimwiki_list = [
\{'path': '~/vimwiki/','auto_tags':1}
\]

Tag completion

In insert-mode you can use omni completion for tag completion. Just type a colon followed by the beginning of the tag and than type Ctrl-x Ctrl-o, this either complete tag or it will bring up a pop-up menu.

Walk through the pop-up menu with Ctrl-n and Ctrl-p.

Searching for tags

Searching for tags is the main reason to use tags.

Use :VimwikiSearchTags for finding one or more Vimwiki files with a certain tag.

Depending on the scope of the tag, Vim will either jump to the file, or to the specific header or to the specific line.

If there is only one Vimwiki file with the tag, than this file will be opened. If there is more than one Vimwiki file with the tag, than the first found file is open and also the search result is stored in the so called "location-list". This is a list that contains the found files. Open the next cq previous file with either :lnext or :lprevious.

Another option is to open the list in a split window with :lopen. Than just use up and down (either j and k or the arrow keys) to go to a specific file and hit .

Jump back to the previous opened file with Ctrl-o.

Tags:

⇽ Tmux key-binding to open task calender and list tasks Transform Mardown to Vimwiki format with sed ⇾