*vviki.txt*           AsciiDoc-flavored wiki plugin for Vim
                    ____   ________   ____ __ __    __                       ~
                    \   \ /   /\   \ /   /|__|  | _|__|                      ~
                     \   v   /  \   v   / |  |  |/ /  |                      ~
                      \     /    \     /  |  |    <|  |                      ~
                       \___/      \___/   |__|__|_ \__|                      ~
                                                  \/                         ~

                                                                       *vviki*
1. Introduction      |vviki-introduction|
2. Usage             |vviki-usage|
3. Mappings          |vviki-mappings|
     <CR>            |vviki-enter|
     <Backspace>     |vviki-back|
     <Tab>           |vviki-next|
     <S-Tab>         |vviki-previous|
3.1 Custom Mappings  |vviki-custom-mappings|
     Open a wiki     |vviki-open-mapping|
     Multiple wikis  |vviki-multiple-wikis|
4. Configuration     |vviki-configuration|
     g:vviki_root                 |vviki_root|
     g:vviki_ext                  |vviki_ext|
     g:vviki_index                |vviki_index|
     g:vviki_conceal_links        |vviki_conceal_links|
     g:vviki_page_link_syntax     |vviki_page_link_syntax|
     g:vviki_visual_link_creation |vviki_visual_link_creation|
     g:vviki_links_include_ext    |vviki_links_include_ext|
     g:vviki_custom_uri_function  |vviki_custom_uri_function|
5. Version History   |vviki-versions|
6. Testing           |vviki-testing|
7. License           |vviki-license|


==============================================================================
1. Introduction                                           *vviki-introduction*

VViki provides "wiki-like" functionality for Vim. It aims to make creating
linked 'pages' of content as painless as possible by providing simple keyboard
mappings to link pages, create new pages, and navigate between pages.

VViki was inspired by VimWiki (and shares many of the same mappings).

VViki uses AsciiDoc syntax because that is what the author prefers (AsciiDoc
is lightweight and readable like Markdown, but has the expressive power of
DocBook - a markup language intended for authoring technical documentation.)
VViki uses Vim's existing AsciiDoc syntax highlighting (or you are free to
substitute any other AsciiDoc syntax highlighter - or none at all).

VViki is excellent for:

 * Technical documentation
 * Mind-mapping
 * Note-taking
 * Diary entries
 * Website authoring

VViki is ready for your content now!


==============================================================================
2. Usage                                                         *vviki-usage*

There is plentiful information about AsciiDoc syntax available on the Web.
Much of the basic formatting is very similar to Markdown.

The most important thing to understand is the link "macro" syntax:
>
	link:http://example.com[Example]     external URL
	link:mypage[My Page]                 (same dir)/mypage.adoc
	link:/mypage[My Page]                (wiki root)/mypage.adoc
	link:../mypage[My Page]              (up a dir)/mypage.adoc
    link:mydir/mypage2[My Page Two]      (same dir)/mydir/mypage2.adoc
    link:mydir/[My Dir]                  (same dir)/mydir/index.adoc
<
(Examples assume VViki defaults - see |vviki_page_link_syntax|.)

AsciiDoc's `link:<path>[label]` format is a little verbose, and that's where
VViki's link mapping comes in handy. Enter creates links from plain words or
follows existing links. (|vviki-enter|)

Assuming VViki is installed and no defaults have been changed, here's what an
initial wiki session might look like:

1. `:e ~/wiki/index.adoc` to create and edit the wiki index page.
2. Enter the following content:
>
    = My Wiki

    I like toys and paper.
<
3. In normal mode, press Enter on the words "toys" and "paper" to turn them
   into links:
>
    = My Wiki

    I like link:toys[toys] and link:paper[paper].
<
4. Still in normal mode, press Enter on the "toys" link to create the content
   on that page.
5. Press Backspace to return to the index page.  You do not have to save the
   toys page manually. VViki automatically saves as you navigate from page
   to page.
6. Repeat for the "paper" page.

You now have a wiki with three pages.


==============================================================================
3. Mappings                                                   *vviki-mappings*

VViki has no global mappings.  When a new wiki page is detected (based on
directory), the following local mappings are available:

<CR>         Create/follow link under cursor. |vviki-enter|

<Backspace>  Return to previous page. |vviki-back|

<Tab>        Jump cursor to next link on page.

<S-Tab>      Jump cursor to previous link on page.

(See the action descriptions below for more details about what each mapping
does.)


Enter                                                            *vviki-enter*

Put your cursor on a plain "word" in normal mode and press Enter to convert
the word to a link. The link destination and label will both be the word. For
example, the link below was created by pressing Enter on the word 'cheese'.
>
    Click on link:cheese[cheese] to learn more.
<
Pressing Enter again on the new 'cheese' link will open `cheese.adoc` for
editing (whether it already exists or not).

Pressing Enter on an external (Web) link will attempt to open the URL using
the `xdg-open` application.

NOTE: At this time, VViki happily creates new pages, but doesn't create
directories. You may want to create subdirectories before editing pages within
them.


Back                                                              *vviki-back*

VViki keeps a history of visited wiki pages. Pressing Backspace in normal mode
visits the previously visited page and the page before that until you run out
of history.


Next                                                              *vviki-next*

Pressing the Tab key in normal mode jumps the cursor to the next available
wiki link in the current document.


Previous                                                      *vviki-previous*

Pressing the Shift-Tab key in normal mode jumps the cursor to the previous
available wiki link in the current document.


------------------------------------------------------------------------------
3.1 Custom Mappings                                    *vviki-custom-mappings*

Rather than attempt to predict and accommodate all possible setups, VViki
highly encourages you to create your own Vim shortcuts and scripts to make
your setup efficient for you!


Open a wiki                                               *vviki-open-mapping*

You'll probably also want to add a mapping to make it easy to open your wiki.
The easier it is to get to the wiki, the more likely you are to use it as
needed. This example mimics VimWiki's default behavior, opening the wiki index:
>
    nnoremap <leader>ww :e ~/wiki/index.adoc<cr>
<
Tip: consider creating other mappings to open other wiki pages you use
frequently!


Multiple wikis                                          *vviki-multiple-wikis*

Because VViki uses global settings for each Vim session, it can only edit one
wiki AT A TIME. But this is probably not as big a barrier to having multiple
wikis as you might think.

The following opens two different wikis with `<leader>w1` and `<leader>w2`
shortcuts. Both wikis can be edited in the same Vim session. Only one will
have active link navigation, etc. at a time.
>
   function! OpenWiki()
		execute 'edit '.g:vviki_root.'/'.g:vviki_index.g:vviki_ext
	endfunction

	function! OpenDiary()
		let g:vviki_root  = '~/diary_wiki'
		let g:vviki_index = 'contents'
		let g:vviki_ext   = '.txt'
		call OpenWiki()
	endfunction

	function! OpenNotes()
		let g:vviki_root  = '~/project1/notes'
		let g:vviki_index = 'index'
		let g:vviki_ext   = '.adoc'
		call OpenWiki()
	endfunction

	nnoremap <leader>w1 :call OpenDiary()<CR>
	nnoremap <leader>w2 :call OpenNotes()<CR>
< 
Though this example may seem large at first, any part of it can be used as the
basis for a huge variety of customizations. The mind reels at the endless
possibilities.


==============================================================================
4. Configuration                                         *vviki-configuration*

Any changes to the VViki configuration settings would most likely be set in
your `~.vimrc` file or equivalent.

VViki has these default values:

      Setting                     | Default Value
    --------------------------------+---------------
     `g:vviki_root`                 | "~/wiki"
     `g:vviki_ext`                  | ".adoc"
     `g:vviki_index`                | "index"
     `g:vviki_conceal_links`        | 1
     `g:vviki_page_link_syntax`     | "link"
     `g:vviki_visual_link_creation` | 0
     `g:vviki_links_include_ext`    | 0

Each is explained in detail below:


g:vviki_root                                                      *vviki_root*

Set the root directory of the wiki using `g:vviki_root`. VViki will use this
root to detect wiki pages when they are opened. Files outside of this root
will not be detected as wiki pages regardless of file extension.

Here's how you might use a custom directory for your wiki:
>
    let g:vviki_root = "~/my_cool_wiki"
<


g:vviki_ext                                                        *vviki_ext*

Set the file extension for wiki pages with `g:vviki_ext`. Since VViki is
intended to be used with AsciiDoc source files, you may wish to use .adoc (the
default) or .asciidoc, but anything is allowed. VViki will use this extension
to find existing files (by appending the extension to link names to make a
file path) and when it creates new pages.

Here's an example of using a non-default file extension:
>
    let g:vviki_ext = ".asciidoc"
<

g:vviki_index                                                    *vviki_index*

You can define a custom name for "index" pages - the default page accessed by
a link to a directory (ending in a slash). These are analogous to the default
documents served up by web servers (such as "index.html"). With the default
setting, the following links are exactly equivalent. Both will open
`cheese/index.adoc` (assuming the default extension):
>
    Notes about link:cheese/[Cheese].
    Notes about link:cheese/index[Cheese].
<

Here's an example of an alternative wiki index page:
>
    let g:vviki_index = "home"
<


g:vviki_conceal_links                                    *vviki_conceal_links*

With this option turned on (default), links will appear as just their titles
until your cursor reaches the same line. This uses Vim's 'conceal' syntax
feature and was inspired by VimWiki's same feature. Set this variable to 0 to
turn this feature off.

To turn off link syntax concealing, set it to 0 like so:
>
    let g:vviki_conceal_links = 0
<


g:vviki_page_link_syntax                              *vviki_page_link_syntax*

Unfortunately, AsciiDoc does not define syntax for linking across documents.
Therefore, VViki currently supports three syntax styles. All three will work
exactly the same within Vim. The differences will be noticed when you attempt
to export your AsciiDoc pages to another format (such as HTML).

To use a non-default link syntax style, set it like so:
>
    let g:vviki_page_link_syntax = 'olink'
<

(Note that VViki will recognize all supported link syntax styles as links and
follow them regardless of setting - all other features (such as syntax
concealing and creating new links) will use the chosen syntax style
exclusively.)

The available syntax options:

        Syntax        | Example           | asciidoc | asciidoctor
    ------------------+-------------------+----------+-------------
     "link" (default) | `link:foo[My Foo]`  | foo      | foo
     "olink"          | `olink:foo[My Foo]` |          |
     "xref_hack"      | `<<foo#,My Foo>>`   | foo      | foo.html

Because the need for the different syntax styles lies in the conversion of
pages to other formats (such as HTML), the above table shows the linked page
filename as exported by each of the two most popular command line tools
`asciidoc` (Python) and `asciidoctor` (Ruby) as they would export each of the
different link syntaxes.

You'll note that only one combination produces relative (wiki-internal) page
filename links with a ".html" file extension when exporting to HTML. (More
about the "olink" results in a moment.)

The author of VViki uses the default "link" syntax and actually prefers the
"extensionless" filenames. When delivered from an Apache web server, they are
recognized correctly as HTML and display correctly in all browsers, giving
so-called "clean URLs".

One could certainly write pre- or post-processing scripts to manipulate the
AsciiDoc source files to add file extensions to links as well.

DocBook (the XML format on which AsciiDoc is based) has a link syntax
specifically addressing the issue of "establishing links across documents."
The "olink" type links to a document by name rather than FILEname. It is the
author's hope that an "olink" macro will someday be recognized by major
AsciiDoc processing applications for this specific purpose. None do at this
time, so the option in VViki is purely aspirational.


g:vviki_visual_link_creation                      *vviki_visual_link_creation*

This setting allows you to select multiple words of text using Vim's visual
mode and turn them into a link by pressing the Enter key. The resulting link
page and description will both be the exact text selected visually.

This option is off by default. Turn it on like so:
>
    let g:vviki_visual_link_creation = 1
<


g:vviki_links_include_ext                            *vviki_links_include_ext*

By default, VViki creates wiki document links without file extensions. With
this option turned on, the file extension (see |vviki_ext|) will be included
in the link path (e.g. `link:foo[My Foo]` becomes `link:foo.adoc[My Foo]`).

Note that the two styles are incompatible - links created with the option on
will not work when the option is off and vice versa.

This option is off by default. Turn it on like so:
>
    let g:vviki_links_include_ext = 1
<


g:vviki_custom_uri_function                        *vviki_custom_uri_function*

By default, VViki creates new wiki file name links based on the selected text.
You can override this behaviour by setting this variable to a function name
that will return a new file name. The function cannot take any arguments.

If you wanted all links to have links in the format `link:202401122207[Foo]`
you would need to add a configuration like this:

>
    function! MakeCustomWikiUri()
        return strftime("%Y%m%d%H%M%S")
    endfunction

    let g:vviki_custom_uri_function = "MakeCustomWikiUri"
<


==============================================================================
5. Version History                                            *vviki-versions*

1.1.0 December 2020
 * Added new link sytanx style options
 * Added multi-word link from visual selection option
 * Added file extension in link option
 * Added interactive test script system

1.0.0 June 2020
 * Added Tab mapping (jump cursor to next link)
 * Added default 'index' page for directory links
 * Fixed link creation bug - thanks ds26gte!

Pre-1.0 development starting in late 2019
 * Proof of concept with Enter key to navigate to existing links
 * Initial commit 2020-02-01
 * Backspace back navigation added
 * Link macro syntax concealing added
 * Help documentation added


==============================================================================
6. Testing                                                      *vviki-testng*

The VViki project contains a test script at test/test.vim. The script sets up
test wiki pages with particular settings to be interactively tested.

Running the test script is an easy way to try out VViki's basic functionality
without setting up or installing anything (VViki does not even need to be
installed as a plugin!)

To start the test system, enter the VViki project directory and run the
script:
>
    cd ~/coolstuff/vviki
    vim -S test/test.vim
<

The first test document should open immediately. It contains instructions for
using the tests (shortcut keys are mapped for fast/easy usage). All tests are
self-documented.


==============================================================================
7. License                                                     *vviki-license*

MIT License

Copyright (c) 2020 Dave Gauer

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.