README.md (9532B)
1  2 3 [中文](README-cn.md) 4 5 - [Intro](#introduction) 6 - [Screenshots](#screenshots) 7 - [Installation](#installation) 8 - [Prerequisites](#prerequisites) 9 - [VIM Packages](#installation-using-vim-packages-since-vim-741528) 10 - [Pathogen](#installation-using-pathogen) 11 - [Vim-Plug](#installation-using-vim-plug) 12 - [Vundle](#installation-using-vundle) 13 - [Basic Markup](#basic-markup) 14 - [Lists](#lists) 15 - [Key Bindings](#key-bindings) 16 - [Commands](#commands) 17 - [Changing Wiki Syntax](#changing-wiki-syntax) 18 - [Getting Help](#getting-help) 19 - [Helping VimWiki](#helping-vimwiki) 20 - [Wiki](https://github.com/vimwiki/vimwiki/wiki) 21 - [License](#license) 22 23 ---- 24 25 ## Introduction 26 27 VimWiki is a personal wiki for Vim -- a number of linked text files that have 28 their own syntax highlighting. See the [VimWiki Wiki](https://vimwiki.github.io/vimwikiwiki/) 29 for an example website built with VimWiki! 30 31 If you are interested in contributing see [this section](#helping-vimwiki). 32 33 With VimWiki, you can: 34 35 - Organize notes and ideas 36 - Manage to-do lists 37 - Write documentation 38 - Maintain a diary 39 - Export everything to HTML 40 41 To do a quick start, press `<Leader>ww` (default is `\ww`) to go to your index 42 wiki file. By default, it is located in `~/vimwiki/index.wiki`. See 43 `:h vimwiki_list` for registering a different path/wiki. 44 45 Feed it with the following example: 46 47 ```text 48 = My knowledge base = 49 * Tasks -- things to be done _yesterday_!!! 50 * Project Gutenberg -- good books are power. 51 * Scratchpad -- various temporary stuff. 52 ``` 53 54 Place your cursor on `Tasks` and press Enter to create a link. Once pressed, 55 `Tasks` will become `[[Tasks]]` -- a VimWiki link. Press Enter again to 56 open it. Edit the file, save it, and then press Backspace to jump back to your 57 index. 58 59 A VimWiki link can be constructed from more than one word. Just visually 60 select the words to be linked and press Enter. Try it, with `Project Gutenberg`. 61 The result should look something like: 62 63 ```text 64 = My knowledge base = 65 * [[Tasks]] -- things to be done _yesterday_!!! 66 * [[Project Gutenberg]] -- good books are power. 67 * Scratchpad -- various temporary stuff. 68 ``` 69 70 ## Screenshots 71 72  73  74  75  76 77 ## Installation 78 79 VimWiki has been tested on **Vim >= 7.3**. It may work on older versions but 80 will not be officially supported. It is known to work on NeoVim, although 81 it is likely to have 82 [NeoVim-specific bugs](https://github.com/vimwiki/vimwiki/labels/neovim). 83 84 ### Prerequisites 85 86 Make sure you have these settings in your vimrc file: 87 88 ```vim 89 set nocompatible 90 filetype plugin on 91 syntax on 92 ``` 93 94 Without them, VimWiki will not work properly. 95 96 #### Installation using [Vim packages](http://vimhelp.appspot.com/repeat.txt.html#packages) (since Vim 7.4.1528) 97 98 ```sh 99 100 git clone https://github.com/vimwiki/vimwiki.git ~/.vim/pack/plugins/start/vimwiki 101 102 # to generate documentation i.e. ':h vimwiki' 103 vim -c 'helptags ~/.vim/pack/plugins/start/vimwiki/doc' -c quit 104 105 ``` 106 107 Notes: 108 109 - See `:h helptags` for issues with installing the documentation. 110 - For general information on vim packages see `:h packages`. 111 112 #### Installation using [Pathogen](https://github.com/tpope/vim-pathogen) 113 114 ```sh 115 116 cd ~/.vim 117 mkdir bundle 118 cd bundle 119 git clone https://github.com/vimwiki/vimwiki.git 120 121 ``` 122 123 #### Installation using [Vim-Plug](https://github.com/junegunn/vim-plug) 124 125 Add the following to the plugin-configuration in your vimrc: 126 127 ```vim 128 129 Plug 'vimwiki/vimwiki' 130 131 ``` 132 133 Then run `:PlugInstall`. 134 135 #### Installation using [Vundle](https://github.com/VundleVim/Vundle.vim) 136 137 Add `Plugin 'vimwiki/vimwiki'` to your vimrc file and run: 138 139 ```sh 140 141 vim +PluginInstall +qall 142 143 ``` 144 145 #### Manual Install 146 147 Download the [zip archive](https://github.com/vimwiki/vimwiki/archive/dev.zip) 148 and extract it in `~/.vim/bundle/` 149 150 Then launch Vim, run `:Helptags` and then `:help vimwiki` to verify it was 151 installed. 152 153 ## Basic Markup 154 155 ```text 156 = Header1 = 157 == Header2 == 158 === Header3 === 159 160 161 *bold* -- bold text 162 _italic_ -- italic text 163 164 [[wiki link]] -- wiki link 165 [[wiki link|description]] -- wiki link with description 166 ``` 167 168 ### Lists 169 170 ```text 171 * bullet list item 1 172 - bullet list item 2 173 - bullet list item 3 174 * bullet list item 4 175 * bullet list item 5 176 * bullet list item 6 177 * bullet list item 7 178 - bullet list item 8 179 - bullet list item 9 180 181 1. numbered list item 1 182 2. numbered list item 2 183 a) numbered list item 3 184 b) numbered list item 4 185 ``` 186 187 For other syntax elements, see `:h vimwiki-syntax` 188 189 ### Todo lists 190 191 ```text 192 - [.] Partially completed item with sub-tasks 193 - [X] Completed sub-task 194 - [ ] Incomplete sub-task 195 - [ ] Other incomplete sub-task 196 - [ ] Incomplete item 197 ``` 198 199 ## Key bindings 200 201 ### Normal mode 202 203 **Note:** your terminal may prevent capturing some of the default bindings 204 listed below. See `:h vimwiki-local-mappings` for suggestions for alternative 205 bindings if you encounter a problem. 206 207 #### Basic key bindings 208 209 - `<Leader>ww` -- Open default wiki index file. 210 - `<Leader>wt` -- Open default wiki index file in a new tab. 211 - `<Leader>ws` -- Select and open wiki index file. 212 - `<Leader>wd` -- Delete wiki file you are in. 213 - `<Leader>wr` -- Rename wiki file you are in. 214 - `<Enter>` -- Follow/Create wiki link. 215 - `<Shift-Enter>` -- Split and follow/create wiki link. 216 - `<Ctrl-Enter>` -- Vertical split and follow/create wiki link. 217 - `<Backspace>` -- Go back to parent(previous) wiki link. 218 - `<Tab>` -- Find next wiki link. 219 - `<Shift-Tab>` -- Find previous wiki link. 220 221 #### Advanced key bindings 222 223 Refer to the complete documentation at `:h vimwiki-mappings` to see many 224 more bindings. 225 226 ## Commands 227 228 - `:Vimwiki2HTML` -- Convert current wiki link to HTML. 229 - `:VimwikiAll2HTML` -- Convert all your wiki links to HTML. 230 - `:help vimwiki-commands` -- List all commands. 231 - `:help vimwiki` -- General vimwiki help docs. 232 233 ## Changing Wiki Syntax 234 235 VimWiki currently ships with 3 syntaxes: VimWiki (default), Markdown 236 (markdown), and MediaWiki (media). Of these, the native VimWiki syntax is 237 best supported, followed by Markdown. No promises are made for MediaWiki. 238 239 **NOTE:** Only the default syntax ships with a built-in HTML converter. For 240 Markdown or MediaWiki see `:h vimwiki-option-custom_wiki2html`. Some examples 241 and 3rd party tools are available 242 [here](https://vimwiki.github.io/vimwikiwiki/Related%20Tools.html#Related%20Tools-External%20Tools). 243 244 If you would prefer to use either Markdown or MediaWiki syntaxes, set the 245 following option in your `.vimrc`: 246 247 ```vim 248 249 let g:vimwiki_list = [{'path': '~/vimwiki/', 250 \ 'syntax': 'markdown', 'ext': 'md'}] 251 252 ``` 253 254 This option will treat all markdown files in your system as part of vimwiki 255 (check `set filetype?`). Add 256 257 ```vim 258 let g:vimwiki_global_ext = 0 259 ``` 260 261 to your `.vimrc` to restrict Vimwiki's operation to only those paths listed in 262 `g:vimwiki_list`. Other markdown files wouldn't be treated as wiki pages. 263 See [g:vimwiki_global_ext](https://github.com/vimwiki/vimwiki/blob/619f04f89861c58e5a6415a4f83847752928252d/doc/vimwiki.txt#L2631). 264 265 if you want to turn off support for other extension(for example, disabling 266 accidently creating new wiki and link for normal markdown files), set the 267 following option in your `.vimrc` before packadd vimwiki: 268 269 ```vim 270 let g:vimwiki_ext2syntax = {} 271 ``` 272 273 See [g:vimiki_ext2syntax](https://github.com/vimwiki/vimwiki/blob/619f04f89861c58e5a6415a4f83847752928252d/doc/vimwiki.txt#L2652) 274 275 ## Getting help 276 277 [GitHub issues](https://github.com/vimwiki/vimwiki/issues) are the primary 278 method for raising bug reports or feature requests. 279 280 Additional resources: 281 282 - The IRC channel [#vimwiki](ircs://irc.libera.chat:6697/vimwiki) on 283 irc.libera.chat is the "official" discussion and support channel 284 - [Connect via webchat](https://web.libera.chat/?channels=#vimwiki) 285 - [@vimwiki@wikis.world](https://wikis.world/@vimwiki) on the Fediverse 286 287 ## Helping VimWiki 288 289 VimWiki has a lot of users but only very few recurring developers or people 290 helping the community. Your help is therefore appreciated. Everyone can help! 291 See [#625](https://github.com/vimwiki/vimwiki/issues/625) for information on how 292 you can help. 293 294 Also, take a look at [CONTRIBUTING.md](https://github.com/vimwiki/vimwiki/blob/master/CONTRIBUTING.md) 295 and [design_notes.md](doc/design_notes.md) 296 297 ---- 298 299 ## License 300 301 MIT License 302 303 Copyright (c) 2008-2010 Maxim Kim 304 2013-2017 Daniel Schemala 305 306 Permission is hereby granted, free of charge, to any person obtaining a copy 307 of this software and associated documentation files (the "Software"), to deal 308 in the Software without restriction, including without limitation the rights 309 to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 310 copies of the Software, and to permit persons to whom the Software is 311 furnished to do so, subject to the following conditions: 312 313 The above copyright notice and this permission notice shall be included in all 314 copies or substantial portions of the Software. 315 316 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 317 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 318 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 319 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 320 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 321 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 322 SOFTWARE.