vviki

1 *vviki.txt* AsciiDoc-flavored wiki plugin for Vim 2 ____ ________ ____ __ __ __ ~ 3 \ \ / /\ \ / /|__| | _|__| ~ 4 \ v / \ v / | | |/ / | ~ 5 \ / \ / | | <| | ~ 6 \___/ \___/ |__|__|_ \__| ~ 7 \/ ~ 8 9 *vviki* 10 1. Introduction |vviki-introduction| 11 2. Usage |vviki-usage| 12 3. Mappings |vviki-mappings| 13 <CR> |vviki-enter| 14 <Backspace> |vviki-back| 15 <Tab> |vviki-next| 16 <S-Tab> |vviki-previous| 17 3.1 Custom Mappings |vviki-custom-mappings| 18 Open a wiki |vviki-open-mapping| 19 Multiple wikis |vviki-multiple-wikis| 20 4. Configuration |vviki-configuration| 21 g:vviki_root |vviki_root| 22 g:vviki_ext |vviki_ext| 23 g:vviki_index |vviki_index| 24 g:vviki_conceal_links |vviki_conceal_links| 25 g:vviki_page_link_syntax |vviki_page_link_syntax| 26 g:vviki_visual_link_creation |vviki_visual_link_creation| 27 g:vviki_links_include_ext |vviki_links_include_ext| 28 g:vviki_custom_uri_function |vviki_custom_uri_function| 29 5. Version History |vviki-versions| 30 6. Testing |vviki-testing| 31 7. License |vviki-license| 32 33 34 ============================================================================== 35 1. Introduction *vviki-introduction* 36 37 VViki provides "wiki-like" functionality for Vim. It aims to make creating 38 linked 'pages' of content as painless as possible by providing simple keyboard 39 mappings to link pages, create new pages, and navigate between pages. 40 41 VViki was inspired by VimWiki (and shares many of the same mappings). 42 43 VViki uses AsciiDoc syntax because that is what the author prefers (AsciiDoc 44 is lightweight and readable like Markdown, but has the expressive power of 45 DocBook - a markup language intended for authoring technical documentation.) 46 VViki uses Vim's existing AsciiDoc syntax highlighting (or you are free to 47 substitute any other AsciiDoc syntax highlighter - or none at all). 48 49 VViki is excellent for: 50 51 * Technical documentation 52 * Mind-mapping 53 * Note-taking 54 * Diary entries 55 * Website authoring 56 57 VViki is ready for your content now! 58 59 60 ============================================================================== 61 2. Usage *vviki-usage* 62 63 There is plentiful information about AsciiDoc syntax available on the Web. 64 Much of the basic formatting is very similar to Markdown. 65 66 The most important thing to understand is the link "macro" syntax: 67 > 68 link:http://example.com[Example] external URL 69 link:mypage[My Page] (same dir)/mypage.adoc 70 link:/mypage[My Page] (wiki root)/mypage.adoc 71 link:../mypage[My Page] (up a dir)/mypage.adoc 72 link:mydir/mypage2[My Page Two] (same dir)/mydir/mypage2.adoc 73 link:mydir/[My Dir] (same dir)/mydir/index.adoc 74 < 75 (Examples assume VViki defaults - see |vviki_page_link_syntax|.) 76 77 AsciiDoc's `link:<path>[label]` format is a little verbose, and that's where 78 VViki's link mapping comes in handy. Enter creates links from plain words or 79 follows existing links. (|vviki-enter|) 80 81 Assuming VViki is installed and no defaults have been changed, here's what an 82 initial wiki session might look like: 83 84 1. `:e ~/wiki/index.adoc` to create and edit the wiki index page. 85 2. Enter the following content: 86 > 87 = My Wiki 88 89 I like toys and paper. 90 < 91 3. In normal mode, press Enter on the words "toys" and "paper" to turn them 92 into links: 93 > 94 = My Wiki 95 96 I like link:toys[toys] and link:paper[paper]. 97 < 98 4. Still in normal mode, press Enter on the "toys" link to create the content 99 on that page. 100 5. Press Backspace to return to the index page. You do not have to save the 101 toys page manually. VViki automatically saves as you navigate from page 102 to page. 103 6. Repeat for the "paper" page. 104 105 You now have a wiki with three pages. 106 107 108 ============================================================================== 109 3. Mappings *vviki-mappings* 110 111 VViki has no global mappings. When a new wiki page is detected (based on 112 directory), the following local mappings are available: 113 114 <CR> Create/follow link under cursor. |vviki-enter| 115 116 <Backspace> Return to previous page. |vviki-back| 117 118 <Tab> Jump cursor to next link on page. 119 120 <S-Tab> Jump cursor to previous link on page. 121 122 (See the action descriptions below for more details about what each mapping 123 does.) 124 125 126 Enter *vviki-enter* 127 128 Put your cursor on a plain "word" in normal mode and press Enter to convert 129 the word to a link. The link destination and label will both be the word. For 130 example, the link below was created by pressing Enter on the word 'cheese'. 131 > 132 Click on link:cheese[cheese] to learn more. 133 < 134 Pressing Enter again on the new 'cheese' link will open `cheese.adoc` for 135 editing (whether it already exists or not). 136 137 Pressing Enter on an external (Web) link will attempt to open the URL using 138 the `xdg-open` application. 139 140 NOTE: At this time, VViki happily creates new pages, but doesn't create 141 directories. You may want to create subdirectories before editing pages within 142 them. 143 144 145 Back *vviki-back* 146 147 VViki keeps a history of visited wiki pages. Pressing Backspace in normal mode 148 visits the previously visited page and the page before that until you run out 149 of history. 150 151 152 Next *vviki-next* 153 154 Pressing the Tab key in normal mode jumps the cursor to the next available 155 wiki link in the current document. 156 157 158 Previous *vviki-previous* 159 160 Pressing the Shift-Tab key in normal mode jumps the cursor to the previous 161 available wiki link in the current document. 162 163 164 ------------------------------------------------------------------------------ 165 3.1 Custom Mappings *vviki-custom-mappings* 166 167 Rather than attempt to predict and accommodate all possible setups, VViki 168 highly encourages you to create your own Vim shortcuts and scripts to make 169 your setup efficient for you! 170 171 172 Open a wiki *vviki-open-mapping* 173 174 You'll probably also want to add a mapping to make it easy to open your wiki. 175 The easier it is to get to the wiki, the more likely you are to use it as 176 needed. This example mimics VimWiki's default behavior, opening the wiki index: 177 > 178 nnoremap <leader>ww :e ~/wiki/index.adoc<cr> 179 < 180 Tip: consider creating other mappings to open other wiki pages you use 181 frequently! 182 183 184 Multiple wikis *vviki-multiple-wikis* 185 186 Because VViki uses global settings for each Vim session, it can only edit one 187 wiki AT A TIME. But this is probably not as big a barrier to having multiple 188 wikis as you might think. 189 190 The following opens two different wikis with `<leader>w1` and `<leader>w2` 191 shortcuts. Both wikis can be edited in the same Vim session. Only one will 192 have active link navigation, etc. at a time. 193 > 194 function! OpenWiki() 195 execute 'edit '.g:vviki_root.'/'.g:vviki_index.g:vviki_ext 196 endfunction 197 198 function! OpenDiary() 199 let g:vviki_root = '~/diary_wiki' 200 let g:vviki_index = 'contents' 201 let g:vviki_ext = '.txt' 202 call OpenWiki() 203 endfunction 204 205 function! OpenNotes() 206 let g:vviki_root = '~/project1/notes' 207 let g:vviki_index = 'index' 208 let g:vviki_ext = '.adoc' 209 call OpenWiki() 210 endfunction 211 212 nnoremap <leader>w1 :call OpenDiary()<CR> 213 nnoremap <leader>w2 :call OpenNotes()<CR> 214 < 215 Though this example may seem large at first, any part of it can be used as the 216 basis for a huge variety of customizations. The mind reels at the endless 217 possibilities. 218 219 220 ============================================================================== 221 4. Configuration *vviki-configuration* 222 223 Any changes to the VViki configuration settings would most likely be set in 224 your `~.vimrc` file or equivalent. 225 226 VViki has these default values: 227 228 Setting | Default Value 229 --------------------------------+--------------- 230 `g:vviki_root` | "~/wiki" 231 `g:vviki_ext` | ".adoc" 232 `g:vviki_index` | "index" 233 `g:vviki_conceal_links` | 1 234 `g:vviki_page_link_syntax` | "link" 235 `g:vviki_visual_link_creation` | 0 236 `g:vviki_links_include_ext` | 0 237 238 Each is explained in detail below: 239 240 241 g:vviki_root *vviki_root* 242 243 Set the root directory of the wiki using `g:vviki_root`. VViki will use this 244 root to detect wiki pages when they are opened. Files outside of this root 245 will not be detected as wiki pages regardless of file extension. 246 247 Here's how you might use a custom directory for your wiki: 248 > 249 let g:vviki_root = "~/my_cool_wiki" 250 < 251 252 253 g:vviki_ext *vviki_ext* 254 255 Set the file extension for wiki pages with `g:vviki_ext`. Since VViki is 256 intended to be used with AsciiDoc source files, you may wish to use .adoc (the 257 default) or .asciidoc, but anything is allowed. VViki will use this extension 258 to find existing files (by appending the extension to link names to make a 259 file path) and when it creates new pages. 260 261 Here's an example of using a non-default file extension: 262 > 263 let g:vviki_ext = ".asciidoc" 264 < 265 266 g:vviki_index *vviki_index* 267 268 You can define a custom name for "index" pages - the default page accessed by 269 a link to a directory (ending in a slash). These are analogous to the default 270 documents served up by web servers (such as "index.html"). With the default 271 setting, the following links are exactly equivalent. Both will open 272 `cheese/index.adoc` (assuming the default extension): 273 > 274 Notes about link:cheese/[Cheese]. 275 Notes about link:cheese/index[Cheese]. 276 < 277 278 Here's an example of an alternative wiki index page: 279 > 280 let g:vviki_index = "home" 281 < 282 283 284 g:vviki_conceal_links *vviki_conceal_links* 285 286 With this option turned on (default), links will appear as just their titles 287 until your cursor reaches the same line. This uses Vim's 'conceal' syntax 288 feature and was inspired by VimWiki's same feature. Set this variable to 0 to 289 turn this feature off. 290 291 To turn off link syntax concealing, set it to 0 like so: 292 > 293 let g:vviki_conceal_links = 0 294 < 295 296 297 g:vviki_page_link_syntax *vviki_page_link_syntax* 298 299 Unfortunately, AsciiDoc does not define syntax for linking across documents. 300 Therefore, VViki currently supports three syntax styles. All three will work 301 exactly the same within Vim. The differences will be noticed when you attempt 302 to export your AsciiDoc pages to another format (such as HTML). 303 304 To use a non-default link syntax style, set it like so: 305 > 306 let g:vviki_page_link_syntax = 'olink' 307 < 308 309 (Note that VViki will recognize all supported link syntax styles as links and 310 follow them regardless of setting - all other features (such as syntax 311 concealing and creating new links) will use the chosen syntax style 312 exclusively.) 313 314 The available syntax options: 315 316 Syntax | Example | asciidoc | asciidoctor 317 ------------------+-------------------+----------+------------- 318 "link" (default) | `link:foo[My Foo]` | foo | foo 319 "olink" | `olink:foo[My Foo]` | | 320 "xref_hack" | `<<foo#,My Foo>>` | foo | foo.html 321 322 Because the need for the different syntax styles lies in the conversion of 323 pages to other formats (such as HTML), the above table shows the linked page 324 filename as exported by each of the two most popular command line tools 325 `asciidoc` (Python) and `asciidoctor` (Ruby) as they would export each of the 326 different link syntaxes. 327 328 You'll note that only one combination produces relative (wiki-internal) page 329 filename links with a ".html" file extension when exporting to HTML. (More 330 about the "olink" results in a moment.) 331 332 The author of VViki uses the default "link" syntax and actually prefers the 333 "extensionless" filenames. When delivered from an Apache web server, they are 334 recognized correctly as HTML and display correctly in all browsers, giving 335 so-called "clean URLs". 336 337 One could certainly write pre- or post-processing scripts to manipulate the 338 AsciiDoc source files to add file extensions to links as well. 339 340 DocBook (the XML format on which AsciiDoc is based) has a link syntax 341 specifically addressing the issue of "establishing links across documents." 342 The "olink" type links to a document by name rather than FILEname. It is the 343 author's hope that an "olink" macro will someday be recognized by major 344 AsciiDoc processing applications for this specific purpose. None do at this 345 time, so the option in VViki is purely aspirational. 346 347 348 g:vviki_visual_link_creation *vviki_visual_link_creation* 349 350 This setting allows you to select multiple words of text using Vim's visual 351 mode and turn them into a link by pressing the Enter key. The resulting link 352 page and description will both be the exact text selected visually. 353 354 This option is off by default. Turn it on like so: 355 > 356 let g:vviki_visual_link_creation = 1 357 < 358 359 360 g:vviki_links_include_ext *vviki_links_include_ext* 361 362 By default, VViki creates wiki document links without file extensions. With 363 this option turned on, the file extension (see |vviki_ext|) will be included 364 in the link path (e.g. `link:foo[My Foo]` becomes `link:foo.adoc[My Foo]`). 365 366 Note that the two styles are incompatible - links created with the option on 367 will not work when the option is off and vice versa. 368 369 This option is off by default. Turn it on like so: 370 > 371 let g:vviki_links_include_ext = 1 372 < 373 374 375 g:vviki_custom_uri_function *vviki_custom_uri_function* 376 377 By default, VViki creates new wiki file name links based on the selected text. 378 You can override this behaviour by setting this variable to a function name 379 that will return a new file name. The function cannot take any arguments. 380 381 If you wanted all links to have links in the format `link:202401122207[Foo]` 382 you would need to add a configuration like this: 383 384 > 385 function! MakeCustomWikiUri() 386 return strftime("%Y%m%d%H%M%S") 387 endfunction 388 389 let g:vviki_custom_uri_function = "MakeCustomWikiUri" 390 < 391 392 393 ============================================================================== 394 5. Version History *vviki-versions* 395 396 1.1.0 December 2020 397 * Added new link sytanx style options 398 * Added multi-word link from visual selection option 399 * Added file extension in link option 400 * Added interactive test script system 401 402 1.0.0 June 2020 403 * Added Tab mapping (jump cursor to next link) 404 * Added default 'index' page for directory links 405 * Fixed link creation bug - thanks ds26gte! 406 407 Pre-1.0 development starting in late 2019 408 * Proof of concept with Enter key to navigate to existing links 409 * Initial commit 2020-02-01 410 * Backspace back navigation added 411 * Link macro syntax concealing added 412 * Help documentation added 413 414 415 ============================================================================== 416 6. Testing *vviki-testng* 417 418 The VViki project contains a test script at test/test.vim. The script sets up 419 test wiki pages with particular settings to be interactively tested. 420 421 Running the test script is an easy way to try out VViki's basic functionality 422 without setting up or installing anything (VViki does not even need to be 423 installed as a plugin!) 424 425 To start the test system, enter the VViki project directory and run the 426 script: 427 > 428 cd ~/coolstuff/vviki 429 vim -S test/test.vim 430 < 431 432 The first test document should open immediately. It contains instructions for 433 using the tests (shortcut keys are mapped for fast/easy usage). All tests are 434 self-documented. 435 436 437 ============================================================================== 438 7. License *vviki-license* 439 440 MIT License 441 442 Copyright (c) 2020 Dave Gauer 443 444 Permission is hereby granted, free of charge, to any person obtaining a copy 445 of this software and associated documentation files (the "Software"), to deal 446 in the Software without restriction, including without limitation the rights 447 to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 448 copies of the Software, and to permit persons to whom the Software is 449 furnished to do so, subject to the following conditions: 450 451 The above copyright notice and this permission notice shall be included in all 452 copies or substantial portions of the Software. 453 454 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 455 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 456 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 457 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 458 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 459 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 460 SOFTWARE.