y0rune/vimwiki
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Clean up the help file (part 1)

Browse Source 
Notably, integrate the parts about schemes, transclusion and thumbnails
into the part about links. I hope that makes things more clear.
This commit is contained in:
EinfachToll 2015-11-20 13:51:19 +01:00
parent ad4a12612c
commit debd308eea
1 changed files with 229 additions and 251 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

478
doc/vimwiki.txt
View File

@ -12,7 +12,7 @@
Version: 2.1
==============================================================================
CONTENTS *vimwiki-contents*
CONTENTS *vimwiki*
1. Intro |vimwiki|
2. Prerequisites |vimwiki-prerequisites|
@ -35,9 +35,6 @@ CONTENTS *vimwiki-contents*
5.9. Blockquotes |vimwiki-syntax-blockquotes|
5.10. Comments |vimwiki-syntax-comments|
5.11. Horizontal line |vimwiki-syntax-hr|
5.12. Schemes |vimwiki-syntax-schemes|
5.13. Transclusions |vimwiki-syntax-transclude|
5.14. Thumbnails |vimwiki-syntax-thumbnails|
5.15. Tags |vimwiki-syntax-tags|
6. Folding/Outline |vimwiki-folding|
7. Placeholders |vimwiki-placeholders|
@ -51,26 +48,27 @@ CONTENTS *vimwiki-contents*
12.3. Per-Wiki Options |vimwiki-local-options|
12.4. Global Options |vimwiki-global-options|
13. Miscellaneous |vimwiki-misc|
14. Help |vimwiki-help|
14. Contributing |vimwiki-contributing|
15. Developers |vimwiki-developers|
16. Changelog |vimwiki-changelog|
17. License |vimwiki-license|
==============================================================================
1. Intro *vimwiki*
1. Intro *vimwiki-intro*
Vimwiki is a personal wiki for Vim -- a number of linked text files that have
their own syntax highlighting.
With vimwiki you can:
- organize notes and ideas;
- manage todo-lists;
- write documentation.
With Vimwiki you can:
- organize notes and ideas
- manage todo-lists
- write documentation
- maintain a diary
- export everything to HTML
To do a quick start press <Leader>ww (this is usually \ww) to go to your index
wiki file. By default it is located in: >
~/vimwiki/index.wiki
wiki file. By default it is located in ~/vimwiki/index.wiki
Feed it with the following example:
@ -80,11 +78,11 @@ Feed it with the following example:
* Scratchpad -- various temporary stuff.
Place your cursor on 'Tasks' and press Enter to create a link. Once pressed,
'Tasks' will become '[[Tasks]]' -- a vimwiki link. Press Enter again to
'Tasks' will become '[[Tasks]]' -- a Vimwiki link. Press Enter again to
open it. Edit the file, save it, and then press Backspace to jump back to your
index.
A vimwiki link can be constructed from more than one word. Just visually
A Vimwiki link can be constructed from more than one word. Just visually
select the words to be linked and press Enter. Try it with 'Project
Gutenberg'. The result should look something like:
@ -107,7 +105,7 @@ Without them Vimwiki will not work properly.
==============================================================================
3. Mappings *vimwiki-mappings*
There are global and local mappings in vimwiki.
There are global and local mappings in Vimwiki.
------------------------------------------------------------------------------
3.1. Global mappings *vimwiki-global-mappings*
@ -141,7 +139,7 @@ See also |:VimwikiTabIndex|
<Leader>ws or <Plug>VimwikiUISelect
List and select available wikies.
List and select available wikis.
To remap: >
:nmap <Leader>wq <Plug>VimwikiUISelect
<
@ -225,7 +223,7 @@ NORMAL MODE *vimwiki-local-mappings*
:nmap <Leader>wc <Plug>Vimwiki2HTML
<
*vimwiki_<Leader>whh*
<Leader>whh Convert current wiki page to HTML and open it in
<Leader>whh Convert current wiki page to HTML and open it in the
webbrowser.
Maps to |:Vimwiki2HTMLBrowse|
To remap: >
@ -269,19 +267,19 @@ NORMAL MODE *vimwiki-local-mappings*
:nmap <Leader>wt <Plug>VimwikiTabnewLink
<
*vimwiki_<Backspace>*
<Backspace> Go back to previous wiki page.
<Backspace> Go back to previously visited wiki page.
Maps to |:VimwikiGoBackLink|.
To remap: >
:nmap <Leader>wb <Plug>VimwikiGoBackLink
<
*vimwiki_<Tab>*
<Tab> Find next link on the current page.
<Tab> Find next link in the current page.
Maps to |:VimwikiNextLink|.
To remap: >
:nmap <Leader>wn <Plug>VimwikiNextLink
<
*vimwiki_<S-Tab>*
<S-Tab> Find previous link on the current page.
<S-Tab> Find previous link in the current page.
Maps to |:VimwikiPrevLink|.
To remap: >
:nmap <Leader>wp <Plug>VimwikiPrevLink
@ -301,7 +299,7 @@ NORMAL MODE *vimwiki-local-mappings*
*vimwiki_=*
= Add header level. Create if needed.
There is nothing to indent with '==' command in
vimwiki, so it should be ok to use '=' here.
Vimwiki, so it should be ok to use '=' here.
To remap: >
:nmap == <Plug>VimwikiAddHeaderLevel
<
@ -313,17 +311,17 @@ NORMAL MODE *vimwiki-local-mappings*
*vimwiki_+*
+ Create and/or decorate links. Depending on the
context, this command will: convert words into
Wikilinks; convert raw URLs into Wikilinks; and add
placeholder text to Wiki- or Weblinks that are missing
descriptions. Can be activated in normal mode with
the cursor over a word or link, or in visual mode with
the selected text.
wikilinks; convert raw URLs into wikilinks; and add
placeholder description text to wiki- or weblinks that
are missing descriptions. Can be activated in normal
mode with the cursor over a word or link, or in visual
mode with the selected text.
To remap: >
:nmap ++ <Plug>VimwikiNormalizeLink
:vmap ++ <Plug>VimwikiNormalizeLinkVisual
<
*vimwiki_<C-Space>*
<C-Space> Toggle checkbox of a list item on/off
<C-Space> Toggle checkbox of a list item on/off.
Maps to |:VimwikiToggleListItem|.
See |vimwiki-todo-lists|.
To remap: >
@ -351,8 +349,10 @@ gLh Decrease the level of a list item and all child items.
:map >>> <Plug>VimwikiDecreaseLvlWholeItem
<
*vimwiki_glr* *vimwiki_gLr*
glr Renumber list items in the current list.
gLr Renumber list items in the whole buffer.
glr Renumber list items if the cursor is on a numbered
list item.
gLr Renumber list items in all numbered lists in the whole
file.
Also readjust checkboxes.
To remap: >
:nmap <c-r> <Plug>VimwikiRenumberList
@ -532,15 +532,15 @@ ah A section segment (the area between two consecutive
headings) including trailing empty lines.
ih A section segment without trailing empty lines.
You can 'vah' to select a section segment with its contents or 'dah' to delete
it or 'yah' to yank it or 'cah' to change it.
You can type 'vah' to select a section segment with its contents or 'dah' to
delete it or 'yah' to yank it or 'cah' to change it.
a\ A cell in a table.
i\ An inner cell in a table.
ac A column in a table.
ic An inner column in a table.
al A list item plus it's children.
al A list item plus its children.
il A single list item.
@ -573,7 +573,7 @@ il A single list item.
4.2. Local commands *vimwiki-local-commands*
*:VimwikiFollowLink*
Follow wiki link (create target wiki page if needed).
Follow wiki link (or create target wiki page if needed).
*:VimwikiGoBackLink*
Go back to the wiki page you came from.
@ -601,24 +601,24 @@ il A single list item.
Supports |cmdline-completion| for link name.
*:VimwikiDeleteLink*
Delete the wiki page that you are in.
Delete the wiki page you are in.
*:VimwikiRenameLink*
Rename the wiki page that you are in.
Rename the wiki page you are in.
*:Vimwiki2HTML*
Convert current wiki page to HTML using vimwiki's own converter or a
Convert current wiki page to HTML using Vimwiki's own converter or a
user-supplied script (see |vimwiki-option-custom_wiki2html|).
*:Vimwiki2HTMLBrowse*
Convert current wiki page to HTML and open it in webbrowser.
Convert current wiki page to HTML and open it in the webbrowser.
*:VimwikiAll2HTML*
Convert all wiki pages to HTML.
Default css file (style.css) is created if there is no one.
Default CSS file (style.css) is created if there is no one.
*:VimwikiToggleListItem*
Toggle checkbox of a list item on/off
Toggle checkbox of a list item on/off.
See |vimwiki-todo-lists|.
*:VimwikiListChangeLevel* CMD
@ -636,8 +636,8 @@ il A single list item.
*:VimwikiBacklinks*
*:VWB*
Search for wikilinks to the [[current wiki page]]
in all files of current wiki.
Search for wikilinks to the current wiki page in all files of current
wiki.
To display all matches use |:lopen| command.
To display next match use |:lnext| command.
To display previous match use |:lprevious| command.
@ -681,7 +681,7 @@ il A single list item.
*:VimwikiGenerateLinks*
Insert all available links into current buffer.
Insert the links of all available wiki files into the current buffer.
*:VimwikiDiaryGenerateLinks*
Delete old, insert new diary section into diary index file.
@ -696,37 +696,38 @@ il A single list item.
*:VimwikiTOC*
Create or update the Table of Contents for the current wiki file.
See |vimwiki-toc|
See |vimwiki-toc|.
*:VimwikiCheckLinks*
Search through all wiki files and check if the targets of all wiki links
and links to external files actually exist. It checks also if all wiki
files are reachable from the index file. Errors are shown in the quickfix
and links to external files actually exist. Check also if all wiki files
are reachable from the index file. The results are shown in the quickfix
window.
*:VimwikiRebuildTags*
Rebuilds the tags metadata file for the current wiki file.
Rebuilds the tags metadata file for all wiki files newer than the metadata
file.
Necessary for all tags related commands: |vimwiki-syntax-tags|.
:VimwikiRebuildTags! does the same for all files in the current wiki.
:VimwikiRebuildTags! does the same for all files.
*:VimwikiSearchTags*
Searches over the pages in current wiki and finds all locations of a given
tag. Supports |cmdline-completion|.
*:VimwikiGenerateTags*
Similar to |:VimwikiGenerateLinks|. In the current buffer, appends tags
and references to all their instances. Supports |cmdline-completion|. If
*:VimwikiGenerateTags* tagname1 tagname2 ...
Creates or updates an overview on all tags of the wiki with links to all
their instances. Supports |cmdline-completion|. If
no arguments (tags) are specified, outputs all tags.
==============================================================================
5. Wiki syntax *vimwiki-syntax*
There are a lot of different wikies out there. Most of them have their own
syntax and vimwiki's default syntax is not an exception here.
There are a lot of different wikis out there. Most of them have their own
syntax and Vimwiki is not an exception here.
Vimwiki has evolved its own syntax that closely resembles google's wiki
Vimwiki has evolved its own syntax that closely resembles Google's wiki
markup. This syntax is described in detail below.
Vimwiki also supports alternative syntaxes, like Markdown and MediaWiki, to
@ -734,7 +735,7 @@ varying degrees; see |vimwiki-option-syntax|. Static elements like headers,
quotations, and lists are customized in syntax/vimwiki_xxx.vim, where xxx
stands for the chosen syntax.
Interactive elements such as links and vimwiki commands are supported by
Interactive elements such as links and Vimwiki commands are supported by
definitions and routines in syntax/vimwiki_xxx_custom.vim and
autoload/vimwiki/xxx_base.vim. Currently, only Markdown includes this level
of support.
@ -744,8 +745,9 @@ Vimwiki2HTML is currently functional only for the default syntax.
------------------------------------------------------------------------------
5.1. Typefaces *vimwiki-syntax-typefaces*
There are a few typefaces that gives you a bit of control over how your
text should be decorated: >
There are a few typefaces that give you a bit of control over how your text
is decorated: >
*bold text*
_italic text_
~~strikeout text~~
@ -759,9 +761,9 @@ text should be decorated: >
Wikilinks~
Link with spaces in it: >
Plain link: >
[[This is a link]]
or: >
With description: >
[[This is a link source|Description of the link]]
Wiki files don't need to be in the root directory of your wiki, you can put
@ -786,6 +788,40 @@ Typing wikilinks can be simplified by using Vim's omni completion (see
[[ind<C-X><C-O>
which opens up a popup menu with all the wiki files starting with "ind".
When |vimwiki-option-maxhi| equals 1, a distinct highlighting style is used to
identify wikilinks whose targets are not found.
Interwiki:~
If you maintain more than one wiki, you can create interwiki links between them
by adding a numbered prefix "wikiX:" in front of a link: >
[[wiki1:This is a link]]
or: >
[[wiki1:This is a link source|Description of the link]]
The number behind "wiki" is in the range 0..N-1 and identifies the destination
wiki in |g:vimwiki_list|.
Diary:~
The "diary:" scheme is used to concisely link to diary entries: >
[[diary:2012-03-05]]
This scheme precludes explicit inclusion of |vimwiki-option-diary_rel_path|,
and is most useful on subwiki pages to avoid links such as: >
[[../../diary/2012-03-05]]
Anchors~
A wikilink, interwiki link or diary link can be followed by a '#' and the name
of an anchor. When opening a link, the cursor jumps to the anchor. >
[[Todo List#Tomorrow|Tasks for tomorrow]]
To jump inside the current wiki file you can omit the file: >
[[#Tomorrow]]
See |vimwiki-anchors| for how to set an anchor.
Raw URLs~
Raw URLs are also supported: >
@ -795,21 +831,70 @@ Raw URLs are also supported: >
External files~
You can open arbitrary files like this: >
[[file:/important/documents/document.pdf]]
The "file:" and "local:" schemes allow you to directly link to arbitray
resources using absolute or relative paths: >
[[file:/home/somebody/a/b/c/music.mp3]]
[[file:C:/Users/somebody/d/e/f/music.mp3]]
[[file:~/a/b/c/music.mp3]]
[[file:../assets/data.csv|Important Data]]
[[local:C:/Users/somebody/d/e/f/music.mp3]]
[[file:/home/user/documents/|Link to a directory]]
See |vimwiki-syntax-schemes|.
These links are opened with the system command, i.e. !xdg-open (Linux), !open
(Mac), or !start (Windows). To customize this behavior, see
|VimwikiLinkHandler|.
Anchors~
In Vim, "file:" and "local:" behave the same, i.e. you can use them with both
relative and absolute links. When converted to HTML, however, "file:" links
will become absolute links, while "local:" links become relative to the HTML
output directory. The latter can be useful if you copy your HTML files to
another computer.
To customize the HTML conversion of links, see |VimwikiLinkConverter|.
A URL can be followed by a '#' and the name of an anchor. When opening a
link, Vimwiki then jumps to the anchor. >
[[Todo List#Tomorrow|Tasks for tomorrow]]
Transclusion (Wiki-Include) Links~
To jump inside the current wiki file you can omit the file: >
[[#Tomorrow]]
Links that use "{{" and "}}" delimiters signify content that is to be
included into the HTML output, rather than referenced via hyperlink.
See |vimwiki-anchors|.
Wiki-include URLs may use any of the supported schemes, may be absolute or
relative, and need not end with an extension.
The primary purpose for wiki-include links is to include images.
Transclude from a local URL: >
{{file:../../images/vimwiki_logo.png}}
or from a universal URL: >
{{http://vimwiki.googlecode.com/hg/images/vimwiki_logo.png}}
Transclude image with alternate text: >
{{http://vimwiki.googlecode.com/hg/images/vimwiki_logo.png|Vimwiki}}
in HTML: >
<img src="http://vimwiki.googlecode.com/hg/images/vimwiki_logo.png"
alt="Vimwiki"/>
Transclude image with alternate text and some style: >
{{http://.../vimwiki_logo.png|cool stuff|style="width:150px; height: 120px;"}}
in HTML: >
<img src="http://vimwiki.googlecode.com/hg/images/vimwiki_logo.png"
alt="cool stuff" style="width:150px; height:120px"/>
Transclude image _without_ alternate text and with a CSS class: >
{{http://.../vimwiki_logo.png||class="center flow blabla"}}
in HTML: >
<img src="http://vimwiki.googlecode.com/hg/images/vimwiki_logo.png"
alt="" class="center flow blabla"/>
A trial feature allows you to supply your own handler for wiki-include links.
See |VimwikiWikiIncludeHandler|.
Thumbnail links~
>
Thumbnail links are constructed like this: >
[[http://someaddr.com/bigpicture.jpg|{{http://someaddr.com/thumbnail.jpg}}]]
in HTML: >
<a href="http://someaddr.com/ ... /.jpg">
<img src="http://../thumbnail.jpg /></a>
Markdown Links~
@ -822,7 +907,7 @@ Inline link: >
Image link: >
![Looks like this](URL)
The URL can be anything recognized by vimwiki as a raw URL.
The URL can be anything recognized by Vimwiki as a raw URL.
Reference-style links: >
@ -925,8 +1010,8 @@ or: >
II) Numbered list item 2
III) Numbered list item 3
or: >
# Bulleted list item 1 ← will be converted to numbers in HTML
# Bulleted list item 2
# Bulleted list item 1
# the # become numbers when converted to HTML
Note that a space after the list item symbols (-, *, 1. etc.) is essential.
@ -989,8 +1074,8 @@ is highlighted as a table header.
If you indent a table then it will be centered in HTML.
If you set > in a cell, the cell spans the left column.
If you set \/ in a cell, the cell spans the above row.
If you put > in a cell, the cell spans the left column.
If you put \/ in a cell, the cell spans the above row.
For example: >
| a | b | c | d |
@ -1018,7 +1103,7 @@ Use {{{ and }}} to define a block of preformatted text:
}}}
You can add optional information to {{{ tag: >
You can add optional information after the {{{: >
{{{class="brush: python" >
def hello(world):
for x in range(10):
@ -1032,10 +1117,10 @@ Result of HTML export: >
print("Hello {0} number {1}".format(world, x))
</pre>
This might be useful for coloring program code with external js tools
such as google's syntax highlighter.
This might be useful for coloring program code with external JS tools
such as Google's syntax highlighter.
You can setup vimwiki to highlight code snippets in preformatted text.
You can setup Vimwiki to highlight code snippets in preformatted text.
See |vimwiki-option-nested_syntaxes|
@ -1078,10 +1163,10 @@ E.g.:
Similar compression rules for the HTML page hold (as MathJax interprets the
LaTeX code).
Note: the highlighting in VIM is automatic. For the rendering in HTML, you
Note: the highlighting in Vim is automatic. For the rendering in HTML, you
have two *alternative* options:
1. using the MathJax server for rendering (needs an internet connection).
1. using the MathJax server for rendering (needs internet connection).
Add to your HTML template the following line:
<script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
@ -1107,9 +1192,9 @@ In this case, <mathjax_folder> would be "../mathjax" (without quotes).
------------------------------------------------------------------------------
5.9. Blockquotes *vimwiki-syntax-blockquotes*
Text started with 4 or more spaces is a blockquote.
Text which starts with 4 or more spaces is a blockquote.
This would be a blockquote in vimwiki. It is not highlighted in vim but
This would be a blockquote in Vimwiki. It is not highlighted in Vim but
could be styled by CSS in HTML. Blockquotes are usually used to quote a
long piece of text from another source.
@ -1117,145 +1202,31 @@ Text started with 4 or more spaces is a blockquote.
------------------------------------------------------------------------------
5.10. Comments *vimwiki-syntax-comments*
Text line started with %% is a comment.
A line that starts with %% is a comment.
E.g.: >
%% this text would not be in HTML
<
------------------------------------------------------------------------------
5.11. Horizontal line *vimwiki-syntax-hr*
4 or more dashes at the start of the line is a 'horizontal line' (<hr />): >
4 or more dashes at the start of the line is a horizontal line (<hr />): >
----
<
------------------------------------------------------------------------------
5.12. Schemes *vimwiki-syntax-schemes*
In addition to standard web schemes (e.g. "http:", "https:", "ftp:", etc.) a
number of special schemes are supported: "wikiX:", "diary:", "file:", "local:"
and schemeless.
While "wikiX", "diary" and schemeless links are automatically opened in Vim,
all other links are opened with the system command, i.e. !xdg-open (Linux),
!open (Mac), or !start (Windows). To customize this behavior, see
|VimwikiLinkHandler|.
Interwiki:~
If you maintain more than one wiki, you can create interwiki links between them
by adding a numbered prefix "wikiX:" in front of a link: >
[[wiki1:This is a link]]
or: >
[[wiki1:This is a link source|Description of the link]]
The number behind "wiki" is in the range 0..N-1 and identifies the destination
wiki in |g:vimwiki_list|.
Diary:~
The diary scheme is used to concisely link to diary entries: >
[[diary:2012-03-05]]
This scheme precludes explicit inclusion of |vimwiki-option-diary_rel_path|,
and is most useful on subwiki pages to avoid links such as: >
[[../../diary/2012-03-05]]
External files:~
The file and local schemes allow you to directly link to arbitray resources
using absolute or relative paths with extension: >
[[file:/home/somebody/a/b/c/music.mp3]]
[[file:C:/Users/somebody/d/e/f/music.mp3]]
[[file:~/a/b/c/music.mp3]]
[[file:../assets/data.csv|data (CSV)]]
[[local:C:/Users/somebody/d/e/f/music.mp3]]
[[file:/home/user/documents/|Link to a directory]]
In Vim, "file:" and "local:" behave the same, i.e. you can use them with both
relative and absolute links. When converted to HTML, however, "file:" links
will become absolute links, while "local:" links become relative to the HTML
output directory. The latter can be useful if you copy your HTML files to
another computer.
To customize the HTML conversion of links, see |VimwikiLinkConverter|.
Schemeless:~
Schemeless URLs, which are the default, are treated internally as "wikiX:"
URLs in all respects, where X is the number of the current wiki.
When |vimwiki-option-maxhi| equals 1, a distinct highlighting style is used to
identify schemeless links whose targets are not found. All other links appear
as regular links even if the files to which they refer do not exist.
------------------------------------------------------------------------------
5.13. Transclusions *vimwiki-syntax-transclude*
Transclusion (Wiki-Include) Links~
Links that use "{{" and "}}" delimiters signify content that is to be
included into the Html output, rather than referenced via hyperlink.
Wiki-include URLs may use any of the supported schemes, may be absolute or
relative, and need not end with an extension.
The primary purpose for wiki-include links is to include images.
Transclude from a local URL: >
{{file:../../images/vimwiki_logo.png}}
or from a universal URL: >
{{http://vimwiki.googlecode.com/hg/images/vimwiki_logo.png}}
Transclude image with alternate text: >
{{http://vimwiki.googlecode.com/hg/images/vimwiki_logo.png|Vimwiki}}
in HTML: >
<img src="http://vimwiki.googlecode.com/hg/images/vimwiki_logo.png"
alt="Vimwiki"/>
Transclude image with alternate text and some style: >
{{http://.../vimwiki_logo.png|cool stuff|style="width:150px; height: 120px;"}}
in HTML: >
<img src="http://vimwiki.googlecode.com/hg/images/vimwiki_logo.png"
alt="cool stuff" style="width:150px; height:120px"/>
Transclude image _without_ alternate text and with css class: >
{{http://.../vimwiki_logo.png||class="center flow blabla"}}
in HTML: >
<img src="http://vimwiki.googlecode.com/hg/images/vimwiki_logo.png"
alt="" class="center flow blabla"/>
A trial feature allows you to supply your own handler for wiki-include links.
See |VimwikiWikiIncludeHandler|.
------------------------------------------------------------------------------
5.14. Thumbnails *vimwiki-syntax-thumbnails*
Thumbnail links~
>
Thumbnail links are constructed like this: >
[[http://someaddr.com/bigpicture.jpg|{{http://someaddr.com/thumbnail.jpg}}]]
in HTML: >
<a href="http://someaddr.com/ ... /.jpg">
<img src="http://../thumbnail.jpg /></a>
------------------------------------------------------------------------------
5.15. Tags *vimwiki-syntax-tags*
Tags~
>
Vimwiki supports notion of tags. A tag is a sequence of non-space characters
between two colons: >
You can tag a wiki file, a header or an arbitrary place in a wiki file. Then,
you can use Vim's built-in tag search functionality (see |tagsrch.txt|) or
Vimwiki's tag related commands to quickly jump to all occurrences of the tag.
A tag is a sequence of non-space characters between two colons: >
:tag-example:
<
It is allowed to concatenate multiple tags in one line: >
:tag-one:tag-two:
<
A tag can be placed anywhere in a file (except for header line, and wikilink).
If placed under a header, within 5 lines below it, the header is then "tagged"
with this tag, and tag search commands will jump to this specific header.
Otherwise the entire page is tagged, and search commands will jump
@ -1270,12 +1241,10 @@ which opens up a popup menu with all tags defined in the wiki starting with
Tags are also treated as |vimwiki-anchors| (similar to bold text).
Note that tag search/jump/completion commands need certain metadata saved in
the wiki folder. This metadata can be manually updated by running
|:VimwikiRebuildTags|. There is an option |vimwiki-option-auto_tags|, when
enabled, tags metadata will be auto-updated on each page save.
the wiki folder. This metadata file can be manually updated by running
|:VimwikiRebuildTags|. When the option |vimwiki-option-auto_tags| is enabled,
the tags metadata will be auto-updated on each page save.
Once tags metadata has been built, one can use Vim's built-in tag search
functionality (see |tagsrch.txt|).
Tags-related commands and options:
* |:VimwikiRebuildTags|
@ -1319,8 +1288,8 @@ Hit |zr| one more time:
* [ ] Do stuff 2~
* [ ] Do stuff 3~
NOTE:If you use the default vimwiki syntax, folding on list items will work
properly only if all of them are indented using current |shiftwidth|.
Note: If you use the default Vimwiki syntax, folding on list items will work
properly only if all of them are indented using the current |shiftwidth|.
For MediaWiki, * or # should be in the first column.
To turn folding on/off check |g:vimwiki_folding|.
@ -1371,8 +1340,8 @@ is in a list item. To make a list item with more than one line, press <S-CR>
or press <CR> and <C-L><C-M>.
Note that the mapping <S-CR> is not available in all terminals.
Furthermore, <CR> and <S-CR> have different behavior when the cursor is behind
an empty list item. See the table below.
Furthermore, <CR> and <S-CR> behave differently when the cursor is behind an
empty list item. See the table below.
You can configure the behavior of <CR> and of <S-CR> like this: >
inoremap <CR> <Esc>:VimwikiReturn 1 5<CR>
@ -1488,7 +1457,7 @@ Roman numerals go up to MMMM) and numbers up to 2147483647. or
Also note that you can, of course, mix different list symbols in one list, but
if you have the strange idea of putting a list with Romanian numerals right
after a list using letters or vice versa, vimwiki will get confused because
after a list using letters or vice versa, Vimwiki will get confused because
it cannot distinguish which is which (at least if the types are both upper
case or both lower case).
@ -1600,10 +1569,10 @@ To indent table indent the first row. Then format it with 'gqq'.
10. Diary *vimwiki-diary*
The diary helps you make daily notes. You can easily add information into
vimwiki that should be sorted out later. Just hit <Leader>w<Leader>w to create
new daily note with name based on current date.
Vimwiki that should be sorted out later. Just hit <Leader>w<Leader>w to create
a new note for today with a name based on the current date.
To generate diary section with all available links one can use
To generate the diary section with all available links one can use
|:VimwikiDiaryGenerateLinks| or <Leader>w<Leader>i .
Note: it works only for diary index file.
@ -1675,11 +1644,11 @@ For jumping inside a single file, you can omit the file in the link: >
------------------------------------------------------------------------------
Table of Contents *vimwiki-toc* *vimwiki-table-of-contents*
You can add a 'table of contents' to your wiki file.
You can create a "table of contents" at the top of your wiki file.
The commando |:VimwikiTOC| creates the magic header >
= Contents =
at the top of your file and below it a list of all the headers in the current
file as links, so you can directly jump to specific parts of the file.
in the current file and below it a list of all the headers in this file as
links, so you can directly jump to specific parts of the file.
For the indentation of the list, the value of |vimwiki-option-list_margin| is
used.
@ -1699,7 +1668,7 @@ If you want to keep the TOC up to date automatically, use the option
12. Options *vimwiki-options*
There are global options and local (per-wiki) options available to tune
vimwiki.
Vimwiki.
Global options are configured via global variables. For a complete list of
them, see |vimwiki-global-options|.
@ -1757,21 +1726,21 @@ For clarity, in your .vimrc file you can define wiki options using separate
The creation of temporary wikis allows you to open files that would not
normally be recognized by vimwiki.
normally be recognized by Vimwiki.
If a file with a registered wiki extension (see |vimwiki-register-extension|)
is opened in a directory that: 1) is not listed in |g:vimwiki_list|, and 2) is
not a subdirectory of any such directory, then a temporary wiki may be created
and appended to the list of configured wikis in |g:vimwiki_list|.
In addition to vimwiki's editing functionality, the temporary wiki enables: 1)
In addition to Vimwiki's editing functionality, the temporary wiki enables: 1)
wiki-linking to other files in the same subtree, 2) highlighting of existing
wiki pages when |vimwiki-option-maxhi| is activated, and 3) html generation to
|vimwiki-option-path_html|.
Temporary wikis are configured using default |vimwiki-local-options|, except
for the path, extension, and syntax options. The path and extension are set
using the file's location and extension. The syntax is set to vimwiki's
using the file's location and extension. The syntax is set to Vimwiki's
default unless another syntax is registered via |vimwiki-register-extension|.
Use |g:vimwiki_global_ext| to turn off creation of temporary wikis.
@ -1863,8 +1832,8 @@ Key Default value Values~
syntax default default, markdown, or media
Description~
Wiki syntax. You can use different markup languages (currently: vimwiki's
default, Markdown, and MediaWiki), but only vimwiki's default markup will be
Wiki syntax. You can use different markup languages (currently: Vimwiki's
default, Markdown, and MediaWiki), but only Vimwiki's default markup will be
converted to HTML at the moment.
To use Markdown's wiki markup: >
@ -1975,11 +1944,11 @@ This disables filesystem checks for wiki links.
*vimwiki-option-nested_syntaxes*
------------------------------------------------------------------------------
Key Default value Values~
nested_syntaxes {} pairs of highlight keyword and vim filetype
nested_syntaxes {} pairs of highlight keyword and Vim filetype
Description~
You can configure preformatted text to be highlighted with any syntax
available for vim.
available for Vim.
For example the following setup in your vimrc: >
let wiki = {}
let wiki.path = '~/my_wiki/'
@ -2147,7 +2116,7 @@ Checked list items can be highlighted with a color:
* [X] the whole line can be highlighted with the option set to 1.
* this line is highlighted as well with the option set to 2
* [ ] I wish vim could use strikethru.
* [ ] I wish Vim could use strikethru.
Value Description~
0 Don't highlight anything.
@ -2179,7 +2148,7 @@ Value Description~
If your preferred wiki extension is .txt then you can >
let g:vimwiki_global_ext = 0
to restrict vimwiki's operation to only those paths listed in g:vimwiki_list.
to restrict Vimwiki's operation to only those paths listed in g:vimwiki_list.
Other text files wouldn't be treated as wiki pages.
Default: 1
@ -2189,16 +2158,16 @@ Default: 1
*g:vimwiki_ext2syntax* *vimwiki-register-extension*
A many-to-one map between file extensions and syntaxes whose purpose is to
register the extensions with vimwiki.
register the extensions with Vimwiki.
E.g.: >
let g:vimwiki_ext2syntax = {'.md': 'markdown',
\ '.mkd': 'markdown',
\ '.wiki': 'media'}
An extension that is registered with vimwiki can trigger creation of a
An extension that is registered with Vimwiki can trigger creation of a
|vimwiki-temporary-wiki| with the associated syntax. File extensions used in
|g:vimwiki_list| are automatically registered with vimwiki using the default
|g:vimwiki_list| are automatically registered with Vimwiki using the default
syntax.
Default: {}
@ -2207,7 +2176,7 @@ Default: {}
------------------------------------------------------------------------------
*g:vimwiki_menu*
GUI menu of available wikies to select.
GUI menu of available wikis to select.
Value Description~
'' No menu
@ -2246,7 +2215,7 @@ Default: 0
------------------------------------------------------------------------------
*g:vimwiki_folding*
Enable/disable vimwiki's folding (outline) functionality. Folding in vimwiki
Enable/disable Vimwiki's folding (outline) functionality. Folding in Vimwiki
can uses either the 'expr' or the 'syntax' |foldmethod| of Vim.
Value Description~
@ -2317,7 +2286,7 @@ something else: >
endfunction
A second example handles a new scheme, "vfile:", which behaves similar to
"file:", but the files are always opened with Vim: >
"file:", but the files are always opened with Vim in a new tab: >
function! VimwikiLinkHandler(link)
" Use Vim to open external files with the 'vfile:' scheme. E.g.:
@ -2343,8 +2312,11 @@ A second example handles a new scheme, "vfile:", which behaves similar to
*VimwikiLinkConverter*
This function can be overridden in your .vimrc to specify what a link looks
like when converted to HTML. It should return the HTML link if successful or
an empty string '' otherwise.
like when converted to HTML. The parameters of the function are:
- the link as a string
- the full path to the wiki file where the link is in
- the full path to the output html file
It should return the HTML link if successful or an empty string '' otherwise.
This example changes how relative links to external files using the "local:"
scheme look like in HTML. Per default, they would become links relative to
@ -2535,7 +2507,7 @@ Default: '' (empty)
------------------------------------------------------------------------------
*g:vimwiki_valid_html_tags*
Case-insensitive comma separated list of HTML tags that can be used in vimwiki.
Case-insensitive comma separated list of HTML tags that can be used in Vimwiki.
Default: 'b,i,s,u,sub,sup,kbd,br,hr'
@ -2549,7 +2521,7 @@ should not be deleted after |:VimwikiAll2HTML|.
Default: ''
Example:
Consider you have 404.html and search.html in your vimwiki 'path_html'.
Consider you have 404.html and search.html in your Vimwiki 'path_html'.
With: >
let g:vimwiki_user_htmls = '404.html,search.html'
they would not be deleted after |:VimwikiAll2HTML|.
@ -2558,10 +2530,10 @@ they would not be deleted after |:VimwikiAll2HTML|.
------------------------------------------------------------------------------
*g:vimwiki_conceallevel*
In vim73 |conceallevel| is local to window, thus if you open vimwiki buffer in
In vim73 |conceallevel| is local to window, thus if you open Vimwiki buffer in
a new tab or window, it would be set to default value.
Vimwiki sets |conceallevel| to g:vimwiki_conceallevel everytime vimwiki buffer
Vimwiki sets |conceallevel| to g:vimwiki_conceallevel everytime Vimwiki buffer
is entered.
With default settings, Vimwiki conceals one-character markers, shortens long
@ -2573,7 +2545,7 @@ Default: 2
------------------------------------------------------------------------------
*g:vimwiki_autowriteall*
In vim |autowriteall| is a global setting. With g:vimwiki_autowriteall vimwiki
In Vim |autowriteall| is a global setting. With g:vimwiki_autowriteall Vimwiki
makes it local to its buffers.
Value Description~
@ -2646,7 +2618,7 @@ let g:vimwiki_diary_months = {
------------------------------------------------------------------------------
*g:vimwiki_toc_header*
A string with the magic header that tells vimwiki where the Table of Contents
A string with the magic header that tells Vimwiki where the Table of Contents
is located in the file. You can change it to the appropriate word in your
mother tongue like this: >
let g:vimwiki_toc_header = 'Inhalt'
@ -2666,13 +2638,13 @@ The default is '<Leader>w'.
------------------------------------------------------------------------------
*g:vimwiki_auto_chdir*
When set to 1, enables auto-cd feature. Whenever vimwiki page is opened,
vimwiki performs an |:lcd| to the vimwiki folder to where the page belongs.
When set to 1, enables auto-cd feature. Whenever Vimwiki page is opened,
Vimwiki performs an |:lcd| to the Vimwiki folder to where the page belongs.
Value Description~
0 Do not change directory.
1 Change directory to vimwiki folder on opening page.
1 Change directory to Vimwiki folder on opening page.
Default: 0
@ -2688,14 +2660,20 @@ the instructions in it.
==============================================================================
14. Help *vimwiki-help*
14. Contributing *vimwiki-contributing*
Your help in making vimwiki better is really appreciated!
Your help in making Vimwiki better is really appreciated!
Any help, whether it is a spelling correction or a code snippet to patch --
everything is welcomed.
Before filing a bug or starting to write a patch, check the latest development
version from https://github.com/vimwiki/vimwiki/tree/dev to see if your
problem is already fixed.
Issues can be filed at https://github.com/vimwiki/vimwiki/issues/ .
If you want to provide a pull request on GitHub, please start from the dev
branch, not from the master branch.
==============================================================================
15. Developers *vimwiki-developers*
@ -2783,9 +2761,9 @@ Summary ~
* No more [http://link description] links.
* No more plain image links. Use transclusions.
* No more image links identified by extension. Use transclusions.
* Interwiki links. See |vimwiki-syntax-schemes|.
* Link schemes. See |vimwiki-syntax-schemes|.
* Transclusions. See |vimwiki-syntax-transclude|.
* Interwiki links
* More link schemes
* Transclusions
* Normalize link command. See |vimwiki_+|.
* Improved diary organization and generation. See |vimwiki-diary|.
* List manipulation. See |vimwiki-list-manipulation|.