commit 8ec1cccb36f0054a613c94005a535f3b376abe31
parent 585a9fd16bb47b9b65ef2308dc3baf8dde864600
Author: Rane Brown <rane.brown@gmail.com>
Date: Mon, 15 Jul 2019 07:28:12 -0600
Update documentation for intro and folding sections.
Originals modifications from PR #694.
Diffstat:
| M | doc/vimwiki.txt | | | 83 | ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++------------------- |
1 file changed, 63 insertions(+), 20 deletions(-)
diff --git a/doc/vimwiki.txt b/doc/vimwiki.txt
@@ -57,40 +57,53 @@ CONTENTS *vimwiki*
==============================================================================
1. Intro *vimwiki-intro*
-Vimwiki is a personal wiki for Vim -- a number of linked text files that have
-their own syntax highlighting.
+Vimwiki makes it very easy for you create a personal wiki using the Vim text
+editor. A wiki is a collection of text documents linked together and formatted
+with wiki or markdown syntax that can be highlighted for readability using
+Vim's syntax highlighting feature.
With Vimwiki you can:
- organize notes and ideas
- manage todo-lists
- write documentation
- maintain a diary
- - export everything to HTML
+ - export your documents 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
+Getting started with Vimwiki is easy. Once intalled, simply type `vim` into
+your terminal to launch Vim and then type <Leader>ww (the <Leader> key is `\`
+by default) to create or open the index wiki file, the "top" page in your
+hierarchical collection of wiki pages. By default, this page will be located
+at ~/vimwiki/index.wiki.
-Feed it with the following example:
+Now add the following example lines to the document:
= 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.
+Next, move your cursor to the word 'Tasks' and press `Enter`. This will create
+a Vimwiki link by surrounding 'Tasks' with double square brackets:
+'[[Tasks]]'. Pressing `Enter` a second time will generate a new blank buffer
+in Vim where you can input your tasks. After you add some tasks and save the
+new file, you can hit `Backspace` to jump back to the index document.
-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:
+A Vimwiki link can contain multiple words by entering Vim's "visual" mode (the
+"v" key, by default) and selecting the words to be linked. Once selected,
+press `Enter`.
+
+Try this now by selecting 'Project Gutenberg' in visual mode and hitting
+`Enter`. The sample text should now look something like this:
= My knowledge base =
* [[Tasks]] -- things to be done _yesterday_!!!
* [[Project Gutenberg]] -- good books are power.
* Scratchpad -- various temporary stuff.
+By continuing this way and creating sub pages with links to even more sub
+pages, you can create an unlimited number of neatly structured, interconnected
+documents to help you organize your notes, documenation, and tasks.
+
==============================================================================
2. Prerequisites *vimwiki-prerequisites*
@@ -1499,11 +1512,15 @@ Tags-related commands and options:
==============================================================================
6. Folding/Outline *vimwiki-folding*
-Vimwiki can fold or outline sections using headers and preformatted blocks.
-Alternatively, one can fold list subitems instead. Folding is not enabled
-by default, and requires the |g:vimwiki_folding| variable to be set.
+Vimwiki allows you to use Vim's folding methods and options so you can fold
+your outline to make it less distracting and easier to navigate. You can use
+Vimwiki's built-in folding methods or supply custom methods for folding. You
+control how folds behave with by setting the |g:vimwiki_folding| variable to
+the desired value in your configuration file: >
+
+ let g:vimwiki_folding = 'value'
-Example for list folding with |g:vimwiki_folding| set to 'list':
+Here's an example of how folds work with |g:vimwiki_folding| set to 'list':
= My current task =
* [ ] Do stuff 1
@@ -1545,8 +1562,34 @@ 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 Markdown and MediaWiki syntax, * or # should be in the first column.
-To turn folding on/off check |g:vimwiki_folding|.
+For maximum control over folds, set |g:vimwiki_folding| to 'custom' so you can
+allow other plugins or your vim configuration file to control how folding is
+performed. For example, let's say you are using markdown syntax and prefer to
+fold so that the last blank line before a header is not folded, you can add
+this function to your configuration file: >
+
+ function! VimwikiFoldLevelCustom(lnum)
+ let pounds = strlen(matchstr(getline(a:lnum), '^#\+'))
+ if (pounds)
+ return '>' . pounds " start a fold level
+ endif
+ if getline(a:lnum) =~? '\v^\s*$'
+ if (strlen(matchstr(getline(a:lnum + 1), '^#\+')))
+ return '-1' " don't fold last blank line before header
+ endif
+ endif
+ return '=' " return previous fold level
+ endfunction
+
+Note that you will also need to add the following vim options to your configuration: >
+
+ augroup VimrcAuGroup
+ autocmd!
+ autocmd FileType vimwiki setlocal foldmethod=expr |
+ \ setlocal foldenable | set foldexpr=VimwikiFoldLevelCustom(v:lnum)
+ augroup END
+See the |g:vimwiki_folding| documentation for more details.
==============================================================================
7. Placeholders *vimwiki-placeholders*
@@ -2697,8 +2740,8 @@ Value Description~
'expr' Folding based on expression (folds sections and code blocks)
'syntax' Folding based on syntax (folds sections; slower than 'expr')
'list' Folding based on expression (folds list subitems; much slower)
-'custom' Leave the folding settings as they are (e.g. set by another
- plugin)
+'custom' Allow folding options to be set by another plugin or a vim
+ configuration file
Default: ''
