%title%

From 8625978e9955c43a8135751a21da262b0e0d8af4 Mon Sep 17 00:00:00 2001 From: Hugues Hiegel Date: Tue, 23 Dec 2014 17:00:28 +0100 Subject: [plugins] VimWiki + Todo Power --- doc/vimwiki.txt | 2372 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 2372 insertions(+) create mode 100644 doc/vimwiki.txt (limited to 'doc') diff --git a/doc/vimwiki.txt b/doc/vimwiki.txt new file mode 100644 index 0000000..4ae55d9 --- /dev/null +++ b/doc/vimwiki.txt @@ -0,0 +1,2372 @@ +*vimwiki.txt* A Personal Wiki for Vim + + __ __ ___ __ __ _ _ ___ ___ _ ___ ~ + | | | || | | |_| || | _ | || | | | | || | ~ + | |_| || | | || || || || | | |_| || | ~ + | || | | || || | | _|| | ~ + | || | | || || | | |_ | | ~ + | | | | | ||_|| || _ || | | _ || | ~ + |___| |___| |_| |_||__| |__||___| |___| |_||___| ~ + + + Version: 2.1 + +============================================================================== +CONTENTS *vimwiki-contents* + + 1. Intro |vimwiki| + 2. Prerequisites |vimwiki-prerequisites| + 3. Mappings |vimwiki-mappings| + 3.1. Global mappings |vimwiki-global-mappings| + 3.2. Local mappings |vimwiki-local-mappings| + 3.3. Text objects |vimwiki-text-objects| + 4. Commands |vimwiki-commands| + 4.1. Global commands |vimwiki-global-commands| + 4.2. Local commands |vimwiki-local-commands| + 5. Wiki syntax |vimwiki-syntax| + 5.1. Typefaces |vimwiki-syntax-typefaces| + 5.2. Links |vimwiki-syntax-links| + 5.3. Headers |vimwiki-syntax-headers| + 5.4. Paragraphs |vimwiki-syntax-paragraphs| + 5.5. Lists |vimwiki-syntax-lists| + 5.6. Tables |vimwiki-syntax-tables| + 5.7. Preformatted text |vimwiki-syntax-preformatted| + 5.8. Mathematical formulae |vimwiki-syntax-math| + 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| + 6. Folding/Outline |vimwiki-folding| + 7. Placeholders |vimwiki-placeholders| + 8. Todo lists |vimwiki-todo-lists| + 9. Tables |vimwiki-tables| + 10. Diary |vimwiki-diary| + 11. Options |vimwiki-options| + 11.1. Registered Wiki |vimwiki-register-wiki| + 11.2. Temporary Wiki |vimwiki-temporary-wiki| + 11.3. Per-Wiki Options |vimwiki-local-options| + 11.4. Global Options |viwmiki-global-options| + 12. Help |vimwiki-help| + 13. Developers |vimwiki-developers| + 14. Changelog |vimwiki-changelog| + 15. License |vimwiki-license| + + +============================================================================== +1. Intro *vimwiki* + +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. + +To do a quick start press ww (this is usually \ww) to go to your index +wiki file. By default it is located in: > + ~/vimwiki/index.wiki + +Feed it with the following example: + += My knowledge base = + * Tasks -- things to be done _yesterday_!!! + * Project Gutenberg -- good books are power. + * 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 +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 +select the words to be linked and press Enter. Try it with 'Project +Gutenberg'. The result should look something like: + += My knowledge base = + * [[Tasks]] -- things to be done _yesterday_!!! + * [[Project Gutenberg]] -- good books are power. + * Scratchpad -- various temporary stuff. + +============================================================================== +2. Prerequisites *vimwiki-prerequisites* + +Make sure you have these settings in your vimrc file: > + set nocompatible + filetype plugin on + syntax on + +Without them Vimwiki will not work properly. + + +============================================================================== +3. Mappings *vimwiki-mappings* + +There are global and local mappings in vimwiki. + +------------------------------------------------------------------------------ +3.1. Global mappings *vimwiki-global-mappings* + +[count]ww or VimwikiIndex + Open index file of the [count]'s wiki. + + ww opens the first wiki from |g:vimwiki_list|. + 1ww as above, opens the first wiki from |g:vimwiki_list|. + 2ww opens the second wiki from |g:vimwiki_list|. + 3ww opens the third wiki from |g:vimwiki_list|. + etc. + To remap: > + :nmap w VimwikiIndex +< +See also |:VimwikiIndex| + + +[count]wt or VimwikiTabIndex + Open index file of the [count]'s wiki in a new tab. + + wt tabopens the first wiki from |g:vimwiki_list|. + 1wt as above tabopens the first wiki from |g:vimwiki_list|. + 2wt tabopens the second wiki from |g:vimwiki_list|. + 3wt tabopens the third wiki from |g:vimwiki_list|. + etc. + To remap: > + :nmap t VimwikiTabIndex +< +See also |:VimwikiTabIndex| + + +ws or VimwikiUISelect + List and select available wikies. + To remap: > + :nmap wq VimwikiUISelect +< +See also |:VimwikiUISelect| + + +[count]wi or VimwikiDiaryIndex + Open diary index file of the [count]'s wiki. + + wi opens diary index file of the first wiki from + |g:vimwiki_list|. + 1wi the same as above. + 2wi opens diary index file of the second wiki from + |g:vimwiki_list|. + etc. + To remap: > + :nmap i VimwikiDiaryIndex + +See also |:VimwikiDiaryIndex| + + +[count]ww or VimwikiMakeDiaryNote + Open diary wiki-file for today of the [count]'s wiki. + + ww opens diary wiki-file for today in the first wiki + from |g:vimwiki_list|. + 1ww as above opens diary wiki-file for today in the + first wiki from |g:vimwiki_list|. + 2ww opens diary wiki-file for today in the second wiki + from |g:vimwiki_list|. + 3ww opens diary wiki-file for today in the third wiki + from |g:vimwiki_list|. + etc. + To remap: > + :nmap d VimwikiMakeDiaryNote +< +See also |:VimwikiMakeDiaryNote| + + +[count]wt or VimwikiTabMakeDiaryNote + Open diary wiki-file for today of the [count]'s wiki in a new tab. + + wt tabopens diary wiki-file for today in the first + wiki from |g:vimwiki_list|. + 1wt as above tabopens diary wiki-file for today in the + first wiki from |g:vimwiki_list|. + 2wt tabopens diary wiki-file for today in the second + wiki from |g:vimwiki_list|. + 3wt tabopens diary wiki-file for today in the third + wiki from |g:vimwiki_list|. + etc. + To remap: > + :nmap dt VimwikiTabMakeDiaryNote +< +See also |:VimwikiTabMakeDiaryNote| + + +------------------------------------------------------------------------------ +3.2. Local mappings + +NORMAL MODE *vimwiki-local-mappings* + *vimwiki_wh* +wh Convert current wiki page to HTML. + Maps to |:Vimwiki2HTML| + To remap: > + :nmap wc Vimwiki2HTML +< + *vimwiki_whh* +whh Convert current wiki page to HTML and open it in + webbrowser. + Maps to |:Vimwiki2HTML| + To remap: > + :nmap wcc Vimwiki2HTMLBrowse +< + *vimwiki_wi* +wi Update diary section (delete old, insert new) + Only works from the diary index. + Maps to |:VimwikiDiaryGenerateLinks| + To remap: > + :nmap wcr VimwikiDiaryGenerateLinks +< + *vimwiki_* + Follow/create wiki link (create target wiki page if + needed). + Maps to |:VimwikiFollowLink|. + To remap: > + :nmap wf VimwikiFollowLink +< + *vimwiki_* + Split and follow (create target wiki page if needed). + May not work in some terminals. Remapping could help. + Maps to |:VimwikiSplitLink|. + To remap: > + :nmap we VimwikiSplitLink +< + *vimwiki_* + Vertical split and follow (create target wiki page if + needed). + May not work in some terminals. Remapping could help. + Maps to |:VimwikiVSplitLink|. + To remap: > + :nmap wq VimwikiVSplitLink +< + *vimwiki_* *vimwiki_* +, Follow wiki link (create target wiki page if needed), + opening in a new tab. + May not work in some terminals. Remapping could help. + Maps to |:VimwikiTabnewLink|. + To remap: > + :nmap wt VimwikiTabnewLink +< + *vimwiki_* + Go back to previous wiki page. + Maps to |:VimwikiGoBackLink|. + To remap: > + :nmap wb VimwikiGoBackLink +< + *vimwiki_* + Find next link on the current page. + Maps to |:VimwikiNextLink|. + To remap: > + :nmap wn VimwikiNextLink +< + *vimwiki_* + Find previous link on the current page. + Maps to |:VimwikiPrevLink|. + To remap: > + :nmap wp VimwikiPrevLink +< + *vimwiki_wd* +wd Delete wiki page you are in. + Maps to |:VimwikiDeleteLink|. + To remap: > + :nmap dd VimwikiDeleteLink +< + *vimwiki_wr* +wr Rename wiki page you are in. + Maps to |:VimwikiRenameLink|. + To remap: > + :nmap rr VimwikiRenameLink +< + *vimwiki_* + Toggle list item on/off (checked/unchecked) + Maps to |:VimwikiToggleListItem|. + To remap: > + :nmap tt VimwikiToggleListItem +< See |vimwiki-todo-lists|. + + *vimwiki_=* += Add header level. Create if needed. + There is nothing to indent with '==' command in + vimwiki, so it should be ok to use '=' here. + To remap: > + :nmap == VimwikiAddHeaderLevel +< + *vimwiki_-* +- Remove header level. + To remap: > + :nmap -- VimwikiRemoveHeaderLevel +< + *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 . + + *vimwiki_glm* +glm Increase the indent of a single-line list item. + + *vimwiki_gll* +gll Decrease the indent of a single-line list item. + + *vimwiki_glstar* *vimwiki_gl8* +gl* or gl8 Switch or insert a "*" symbol. Only available in + supported syntaxes. + + *vimwiki_gl#* *vimwiki_gl3* +gl# or gl3 Switch or insert a "#" symbol. Only available in + supported syntaxes. + + *vimwiki_gl-* +gl- Switch or insert a "-" symbol. Only available in + supported syntaxes. + + *vimwiki_gl1* +gl1 Switch or insert a "1." symbol. Only available in + supported syntaxes. + + *vimwiki_gqq* *vimwiki_gww* +gqq Format table. If you made some changes to a table + or without swapping insert/normal modes this command +gww will reformat it. + + *vimwiki_* + Move current table column to the left. + See |:VimwikiTableMoveColumnLeft| + To remap: > + :nmap wtl VimwikiTableMoveColumnLeft +< + *vimwiki_* + Move current table column to the right. + See |:VimwikiTableMoveColumnRight| + To remap: > + :nmap wtr VimwikiTableMoveColumnRight +< + *vimwiki_* + Open the previous day's diary link if available. + See |:VimwikiDiaryPrevDay| + + *vimwiki_* + Open the next day's diary link if available. + See |:VimwikiDiaryNextDay| + + +Works only if |g:vimwiki_use_mouse| is set to 1. +<2-LeftMouse> Follow wiki link (create target wiki page if needed). + + Split and follow wiki link (create target wiki page if + needed). + + Vertical split and follow wiki link (create target + wiki page if needed). + + Go back to previous wiki page. + +Note: <2-LeftMouse> is just left double click. + + + +INSERT MODE *vimwiki-table-mappings* + *vimwiki_i_* + Go to the table cell beneath the current one, create + a new row if on the last one. + + *vimwiki_i_* + Go to the next table cell, create a new row if on the + last cell. +See |g:vimwiki_table_mappings| to turn them off. + + +------------------------------------------------------------------------------ +3.3. Text objects *vimwiki-text-objects* + +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. + +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. + + +============================================================================== +4. Commands *vimwiki-commands* + +------------------------------------------------------------------------------ +4.1. Global Commands *vimwiki-global-commands* + +*:VimwikiIndex* + Open index file of the current wiki. + +*:VimwikiTabIndex* + Open index file of the current wiki in a new tab. + +*:VimwikiUISelect* + Open index file of the selected wiki. + +*:VimwikiDiaryIndex* + Open diary index file of the current wiki. + +*:VimwikiMakeDiaryNote* + Open diary wiki-file for today of the current wiki. + +*:VimwikiTabMakeDiaryNote* + Open diary wiki-file for today of the current wiki in a new tab. + + +------------------------------------------------------------------------------ +4.2. Local commands *vimwiki-local-commands* + +*:VimwikiFollowLink* + Follow wiki link (create target wiki page if needed). + +*:VimwikiGoBackLink* + Go back to the wiki page you came from. + +*:VimwikiSplitLink* + Split and follow wiki link (create target wiki page if needed). + +*:VimwikiVSplitLink* + Vertical split and follow wiki link (create target wiki page if needed). + +*:VimwikiTabnewLink* + Follow wiki link in a new tab (create target wiki page if needed). + +*:VimwikiNextLink* + Find next link on the current page. + +*:VimwikiPrevLink* + Find previous link on the current page. + +*:VimwikiGoto* + Goto link provided by an argument. For example: > + :VimwikiGoto HelloWorld +< opens opens/creates HelloWorld wiki page. + +*:VimwikiDeleteLink* + Delete the wiki page that you are in. + +*:VimwikiRenameLink* + Rename the wiki page that you are in. + +*:Vimwiki2HTML* + 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. + +*:VimwikiAll2HTML* + Convert all wiki pages to HTML. + Default css file (style.css) is created if there is no one. + +*:VimwikiToggleListItem* + Toggle list item on/off (checked/unchecked) + See |vimwiki-todo-lists|. + +*:VimwikiListChangeLevel* CMD + Change the nesting level, or symbol, for a single-line list item. + CMD may be ">>" or "<<" to change the indentation of the item, or + one of the syntax-specific bullets: "*", "#", "1.", "-". + See |vimwiki-todo-lists|. + +*:VimwikiSearch* /pattern/ +*:VWS* /pattern/ + Search for /pattern/ 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. + +*:VimwikiBacklinks* +*:VWB* + 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. + + +*:VimwikiTable* + Create a table with 5 cols and 2 rows. + + :VimwikiTable cols rows + Create a table with the given cols and rows + + :VimwikiTable cols + Create a table with the given cols and 2 rows + + +*:VimwikiTableMoveColumnLeft* , *:VimwikiTableMoveColumnRight* + Move current column to the left or to the right: + Example: > + + | head1 | head2 | head3 | head4 | head5 | + |--------|--------|--------|--------|--------| + | value1 | value2 | value3 | value4 | value5 | + + + Cursor is on 'head1'. + :VimwikiTableMoveColumnRight + + | head2 | head1 | head3 | head4 | head5 | + |--------|--------|--------|--------|--------| + | value2 | value1 | value3 | value4 | value5 | + + Cursor is on 'head3'. + :VimwikiTableMoveColumnLeft + + | head2 | head3 | head1 | head4 | head5 | + |--------|--------|--------|--------|--------| + | value2 | value3 | value1 | value4 | value5 | +< + + Commands are mapped to and respectively. + + +*:VimwikiGenerateLinks* + Insert all available links into current buffer. + +*:VimwikiDiaryGenerateLinks* + Delete old, insert new diary section into diary index file. + +*:VimwikiDiaryNextDay* + Open next day diary link if available. + Mapped to . + +*:VimwikiDiaryPrevDay* + Open previous day diary link if available. + Mapped to . + + +============================================================================== +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. + +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 +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 +definitions and routines in syntax/vimwiki_xxx_custom.vim and +autoload/vimwiki/xxx_base.vim. Currently, only Markdown includes this level +of support. + +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: > + *bold text* + _italic text_ + ~~strikeout text~~ + `code (no syntax) text` + super^script^ + sub,,script,, + + +------------------------------------------------------------------------------ +5.2. Links *vimwiki-syntax-links* + +Wikilinks~ + +Link with spaces in it: > + [[This is a link]] +or: > + [[This is a link source|Description of the link]] + +Links to directories (ending with a "/") are also supported: > + [[/home/somebody/|Home Directory]] + +Use |g:vimwiki_dir_link| to control the behaviour when opening directories. + +Raw URLs~ + +Raw URLs are also supported: > + http://code.google.com/p/vimwiki + mailto:habamax@gmail.com + ftp://vim.org + + +Markdown Links~ + +These links are only available for Markdown syntax. See +http://daringfireball.net/projects/markdown/syntax#link. + +Inline link: > + [Looks like this](URL) + +Image link: > + ![Looks like this](URL) + +The URL can be anything recognized by vimwiki as a raw URL. + + +Reference-style links: > + a) [Link Name][Id] + b) [Id][], using the "implicit link name" shortcut + +Reference style links must always include *two* consecutive pairs of +[-brackets, and field entries can not use "[" or "]". + + +NOTE: (in Vimwiki's current implementation) Reference-style links are a hybrid +of Vimwiki's default "Wikilink" and the tradition reference-style link. + +If the Id is defined elsewhere in the source, as per the Markdown standard: > + [Id]: URL + +then the URL is opened with the system default handler. Otherwise, Vimwiki +treats the reference-style link as a Wikilink, interpreting the Id field as a +wiki page name. + +Highlighting of existing links when |vimwiki-option-maxhi| is activated +identifies links whose Id field is not defined, either as a reference-link or +as a wiki page. + +To scan the page for new or changed definitions for reference-links, simply +re-open the page ":e". + + +------------------------------------------------------------------------------ +5.3. Headers *vimwiki-syntax-headers* + += Header level 1 =~ +By default all headers are highlighted using |hl-Title| highlight group. + +== Header level 2 ==~ +You can set up different colors for each header level: > + :hi VimwikiHeader1 guifg=#FF0000 + :hi VimwikiHeader2 guifg=#00FF00 + :hi VimwikiHeader3 guifg=#0000FF + :hi VimwikiHeader4 guifg=#FF00FF + :hi VimwikiHeader5 guifg=#00FFFF + :hi VimwikiHeader6 guifg=#FFFF00 +Set up colors for all 6 header levels or none at all. + +=== Header level 3 ===~ +==== Header level 4 ====~ +===== Header level 5 =====~ +====== Header level 6 ======~ + + +You can center your headers in HTML by placing spaces before the first '=': + = Centered Header L1 =~ + + +------------------------------------------------------------------------------ +5.4. Paragraphs *vimwiki-syntax-paragraphs* + +A paragraph is a group of lines starting in column 1 (no indentation). +Paragraphs are separated by a blank line: + +This is first paragraph +with two lines. + +This is a second paragraph with +two lines. + + +------------------------------------------------------------------------------ +5.5. Lists *vimwiki-syntax-lists* + +Unordered lists: > + * Bulleted list item 1 + * Bulleted list item 2 + * Bulleted list sub item 1 + * Bulleted list sub item 2 + * more ... + * and more ... + * ... + * Bulleted list sub item 3 + * etc. +or: > + - Bulleted list item 1 + - Bulleted list item 2 + - Bulleted list sub item 1 + - Bulleted list sub item 2 + - more ... + - and more ... + - ... + - Bulleted list sub item 3 + - etc. + +or mix: > + - Bulleted list item 1 + - Bulleted list item 2 + * Bulleted list sub item 1 + * Bulleted list sub item 2 + * more ... + - and more ... + - ... + * Bulleted list sub item 3 + * etc. + +Ordered lists: > + # Numbered list item 1 + # Numbered list item 2 + # Numbered list sub item 1 + # Numbered list sub item 2 + # more ... + # and more ... + # ... + # Numbered list sub item 3 + # etc. + +It is possible to mix bulleted and numbered lists: > + * Bulleted list item 1 + * Bulleted list item 2 + # Numbered list sub item 1 + # Numbered list sub item 2 + +Note that a space after *, - or # is essential. + +Multiline list items: > + * Bulleted list item 1 + List item 1 continued line. + List item 1 next continued line. + * Bulleted list item 2 + * Bulleted list sub item 1 + List sub item 1 continued line. + List sub item 1 next continued line. + * Bulleted list sub item 2 + * etc. + +Definition lists: > +Term 1:: Definition 1 +Term 2:: +:: Definition 2 +:: Definition 3 + + +------------------------------------------------------------------------------ +5.6. Tables *vimwiki-syntax-tables* + +Tables are created by entering the content of each cell separated by | +delimiters. You can insert other inline wiki syntax in table cells, including +typeface formatting and links. +For example: > + + | Year | Temperature (low) | Temperature (high) | + |------|-------------------|--------------------| + | 1900 | -10 | 25 | + | 1910 | -15 | 30 | + | 1920 | -10 | 32 | + | 1930 | _N/A_ | _N/A_ | + | 1940 | -2 | 40 | +> + +In HTML the following part > + | Year | Temperature (low) | Temperature (high) | + |------|-------------------|--------------------| +> +is higlighted 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. +For example: > + + | a | b | c | d | + | \/ | e | > | f | + | \/ | \/ | > | g | + | h | > | > | > | +> + +See |vimwiki-tables| for more details on how to manage tables. + + +------------------------------------------------------------------------------ +5.7. Preformatted text *vimwiki-syntax-preformatted* + +Use {{{ and }}} to define a block of preformatted text: +{{{ > + Tyger! Tyger! burning bright + In the forests of the night, + What immortal hand or eye + Could frame thy fearful symmetry? + In what distant deeps or skies + Burnt the fire of thine eyes? + On what wings dare he aspire? + What the hand dare sieze the fire? +}}} + + +You can add optional information to {{{ tag: > +{{{class="brush: python" > + def hello(world): + for x in range(10): + print("Hello {0} number {1}".format(world, x)) +}}} + +Result of HTML export: > +

+ def hello(world):
+     for x in range(10):
+         print("Hello {0} number {1}".format(world, x))
+

+ +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. +See |vimwiki-option-nested_syntaxes| + + +------------------------------------------------------------------------------ +5.8. Mathematical formulae *vimwiki-syntax-math* + +Mathematical formulae are highlighted, and can be rendered in HTML using the +powerful open source display engine MathJax (http://www.mathjax.org/). + +There are three supported syntaxes, which are inline, block display and +block environment. + +Inline math is for short formulae within text. It is enclosed by single +dollar signs, e.g.: + $ \sum_i a_i^2 = 1 $ + +Block display creates a centered formula with some spacing before and after +it. It must start with a line including only {{$, then an arbitrary number +of mathematical text are allowed, and it must end with a line including only +}}$. +E.g.: + {{$ + \sum_i a_i^2 + = + 1 + }}$ + +Note: no matter how many lines are used in the text file, the HTML will +compress it to *one* line only. + +Block environment is similar to block display, but is able to use specific +LaTeX environments, such as 'align'. The syntax is the same as for block +display, except for the first line which is {{$%environment%. +E.g.: + {{$%align% + \sum_i a_i^2 &= 1 + 1 \\ + &= 2. + }}$ + +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 +have two *alternative* options: + +1. using the MathJax server for rendering (needs an internet connection). +Add to your HTML template the following line: + + + +2. installing MathJax locally (faster, no internet required). Choose a +folder on your hard drive and save MathJax in it. Then add to your HTML +template the following line: + + + +where is the folder on your HD, as a relative path to the +template folder. For instance, a sensible folder structure could be: + +- wiki + - text + - html + - templates + - mathjax + +In this case, would be "../mathjax" (without quotes). + + +------------------------------------------------------------------------------ +5.9. Blockquotes *vimwiki-syntax-blockquotes* + +Text started with 4 or more spaces is a blockquote. + + 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. + + +------------------------------------------------------------------------------ +5.10. Comments *vimwiki-syntax-comments* + +Text line started 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' (

): > + ---- +< + +------------------------------------------------------------------------------ +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: "wiki#:", "local:", "diary:", +"file:", and schemeless. + +While "wiki:#", "diary" and schemeless links are automatically opened in Vi, +all other links are opened with the system command. 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 "wiki#:" in front of a link: > + [[wiki#:This is a link]] +or: > + [[wiki#:This is a link source|Description of the link]] + +The number "#", in the range 0..N-1, 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]] + +Local:~ + +A local resource that is not a wiki page may be specified with a path relative +to the current page: > + [[local:../assets/data.csv|data (CSV)]] + +When followed or converted to HTML, extensions of local-scheme links are not +modified. + +File:~ + +The file scheme allows you to directly link to arbitray resources using +absolute paths and extensions: > + [[file:///home/somebody/a/b/c/music.mp3]] + +Schemeless:~ + +Schemeless URLs, which are the default, are treated internally as "wiki#:" +URLs in all respects except when converted to Html. + +Schemeless links convert to plain relative path URLs, nearly verbatim: > + relpath/wikipage.html + +The "wiki#:", "local:", and "diary:" schemes use absolute paths as URLs: > + file:///abs_path_to_html#/relpath/wikipage.html + +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: > + {{local:../../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: > + Vimwiki

+ +Transclude image with alternate text and some style: > + {{http://.../vimwiki_logo.png|cool stuff|style="width:150px; height: 120px;"}} +in HTML: > +

+ +Transclude image _without_ alternate text and with css class: > + {{http://.../vimwiki_logo.png||class="center flow blabla"}} +in HTML: > +

+ +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: > + +

+ %title% + + + +

+ %content% +