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 immiediate 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
[enter].
Jump back to the previous opened file with Ctrl-o.
