From 62d71b832af248c4913565b25e0cfbcf8256352e Mon Sep 17 00:00:00 2001 From: Monkin Date: Mon, 1 Apr 2019 16:13:40 +0200 Subject: [PATCH] Update and format README.md --- CONTRIBUTING.md | 2 +- LICENSE => LICENSE.md | 0 README.md | 303 +++++++++++++++++++++++++----------------- 3 files changed, 180 insertions(+), 125 deletions(-) rename LICENSE => LICENSE.md (100%) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5a03fae..0ae050f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -12,7 +12,7 @@ If you want to provide a pull request on GitHub, please start from the `dev` bra # More info and advice for (aspiring) core developers - Before implementing a non-trivial feature, think twice what it means for the user. We should - always try to keep backward compatiblility. If you are not sure, discuss it on GitHub. + always try to keep backward compatibility. If you are not sure, discuss it on GitHub. - Also, when thinking about adding a new feature, it should be something which fits into the overall design of Vimwiki and which a significant portion of the users may like. Keep in mind that everybody has their own way to use Vimwiki. diff --git a/LICENSE b/LICENSE.md similarity index 100% rename from LICENSE rename to LICENSE.md diff --git a/README.md b/README.md index 1dc0417..70ef4cc 100644 --- a/README.md +++ b/README.md @@ -1,90 +1,173 @@ -A Personal Wiki For Vim -============================================================================== +# VimWiki: A Personal Wiki For Vim [中文](README-cn.md) -![screenshot1](doc/screenshot_1.png) -![screenshot2](doc/screenshot_2.png) * +- [Intro](#intro) +- [Installation](#installation) + - [Prerequisites](#prerequisites) + - [VIM Packages](#installation-using-vim-packages-since-vim-741528) + - [Pathogen](#installation-using-pathogen) + - [Vim-Plug](#installation-using-vim-plug) + - [Vundle](#installation-using-vundle) +- [Basic Markup](#basic-markup) + - [Lists](#lists) +- [Key Bindings](#key-bindings) +- [Commands](#commands) +- [Changing Wiki Syntax](#changing-wiki-syntax) +- [Getting Help](#getting-help) +- [Helping VimWiki](#helping-vimwiki) +- [Wiki](https://github.com/vimwiki/vimwiki/wiki) +- [License](#license) -Intro ------------------------------------------------------------------------------- +## Intro -Vimwiki is a personal wiki for Vim -- a number of linked text files that have +VimWiki is a personal wiki for Vim -- a number of linked text files that have their own syntax highlighting. -With Vimwiki you can: +With VimWiki you can: - * organize notes and ideas - * manage todo-lists - * write documentation - * maintain a diary - * export everything to HTML + * Organize notes and ideas + * Manage to-do lists + * Write documentation + * Maintain a diary + * Export everything to HTML -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`. +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 += 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`. +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. +``` + += My knowledge base = + * [[Tasks]] -- things to be done _yesterday_!!! + * [[Project Gutenberg]] -- good books are power. + * Scratchpad -- various temporary stuff. + +``` + +## Installation + +### Prerequisites + +Make sure you have these settings in your vimrc file: + +```vim + +set nocompatible +filetype plugin on +syntax on + +``` + +Without them VimWiki will not work properly. -Basic Markup ------------------------------------------------------------------------------- +#### Installation using [Vim packages](http://vimhelp.appspot.com/repeat.txt.html#packages) (since Vim 7.4.1528) - = Header1 = - == Header2 == - === Header3 === +```sh + +git clone https://github.com/vimwiki/vimwiki.git ~/.vim/pack/plugins/start/vimwiki + +``` + +#### Installation using [Pathogen](http://www.vim.org/scripts/script.php?script_id=2332) + +```sh + +cd ~/.vim +mkdir bundle +cd bundle +git clone https://github.com/vimwiki/vimwiki.git + +``` + +#### Installation using [Vim-Plug](https://github.com/junegunn/vim-plug) + +Add the following to the plugin-configuration in your vimrc: + +```vim + +Plug 'vimwiki/vimwiki' + +``` + +Then run `:PlugInstall`. + +#### Installation using [Vundle](https://github.com/VundleVim/Vundle.vim) + +Add `Plugin 'vimwiki/vimwiki'` to your vimrc file and run + +```sh + +vim +PluginInstall +qall + +``` + +Or download the [zip +archive](https://github.com/vimwiki/vimwiki/archive/master.zip) and extract it +in `~/.vim/bundle/` + +Then launch Vim, run `:Helptags` and then `:help vimwiki` to verify it was +installed. + +## Basic Markup + +``` += Header1 = +== Header2 == +=== Header3 === - *bold* -- bold text - _italic_ -- italic text +*bold* -- bold text +_italic_ -- italic text - [[wiki link]] -- wiki link - [[wiki link|description]] -- wiki link with description +[[wiki link]] -- wiki link +[[wiki link|description]] -- wiki link with description +``` +### Lists: -Lists: - - * bullet list item 1 - - bullet list item 2 - - bullet list item 3 - * bullet list item 4 - * bullet list item 5 - * bullet list item 6 - * bullet list item 7 - - bullet list item 8 - - bullet list item 9 - - 1. numbered list item 1 - 2. numbered list item 2 - a) numbered list item 3 - b) numbered list item 4 +``` +* bullet list item 1 + - bullet list item 2 + - bullet list item 3 + * bullet list item 4 + * bullet list item 5 +* bullet list item 6 +* bullet list item 7 + - bullet list item 8 + - bullet list item 9 +1. numbered list item 1 +2. numbered list item 2 + a) numbered list item 3 + b) numbered list item 4 +``` For other syntax elements, see `:h vimwiki-syntax` +## Key bindings -Key bindings ------------------------------------------------------------------------------- - -normal mode: +Normal mode: * `ww` -- Open default wiki index file. * `wt` -- Open default wiki index file in a new tab. @@ -100,89 +183,61 @@ normal mode: For more keys, see `:h vimwiki-mappings` +## Commands -Commands ------------------------------------------------------------------------------- - - * `:Vimwiki2HTML` -- Convert current wiki link to HTML - * `:VimwikiAll2HTML` -- Convert all your wiki links to HTML + * `:VimWiki2HTML` -- Convert current wiki link to HTML + * `:VimWikiAll2HTML` -- Convert all your wiki links to HTML * `:help vimwiki-commands` -- list all commands * `:help vimwiki` -- General vimwiki help docs +## Changing Wiki Syntax -Changing Wiki Syntax ------------------------------------------------------------------------------- +VimWiki currently ships with 3 syntaxes: VimWiki (default), Markdown +(markdown), and MediaWiki (media) - Vimwiki currently ships with 3 syntaxes: Vimwiki (default), Markdown (markdown), and MediaWiki (media) +If you would prefer to use either Markdown or MediaWiki syntaxes, set the +following option in your .vimrc: - If you would prefer to use either Markdown or MediaWiki syntaxes, set the following option in your .vimrc: - ``` - let g:vimwiki_list = [{'path': '~/vimwiki/', - \ 'syntax': 'markdown', 'ext': '.md'}] - ``` +```vim +let g:vimwiki_list = [{'path': '~/vimwiki/', + \ 'syntax': 'markdown', 'ext': '.md'}] -Installation -============================================================================== +``` -Prerequisites ------------------------------------------------------------------------------- +## Getting help -Make sure you have these settings in your vimrc file: +**Have a question?** +Visit the IRC channel [`#vimwiki`](https://webchat.freenode.net/?channels=#vimwiki) on Freenode ([webchat](https://webchat.freenode.net/?channels=#vimwiki), also synced to Matrix/Riot: `#freenode_#vimwiki:matrix.org`) or post to the [mailing list](https://groups.google.com/forum/#!forum/vimwiki). - set nocompatible - filetype plugin on - syntax on +## Helping VimWiki -Without them Vimwiki will not work properly. +VimWiki has a lot of users but only very few recurring developers or people +helping the community. Your help is therefore appreciated. Everyone can help! +See [#625](https://github.com/vimwiki/vimwiki/issues/625) for information on +how you can help. +## License -Installation using [Vim packages](http://vimhelp.appspot.com/repeat.txt.html#packages) (since Vim 7.4.1528) ------------------------------------------------------------------------------- +MIT License - git clone https://github.com/vimwiki/vimwiki.git ~/.vim/pack/plugins/start/vimwiki +Copyright (c) 2008-2010 Maxim Kim + 2013-2017 Daniel Schemala -Installation using [Pathogen](http://www.vim.org/scripts/script.php?script_id=2332) ------------------------------------------------------------------------------- +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: - cd ~/.vim - mkdir bundle - cd bundle - git clone https://github.com/vimwiki/vimwiki.git +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. -Installation using [Vim-Plug](https://github.com/junegunn/vim-plug) ------------------------------------------------------------------------------- - -Add the following to the plugin-configuration in your vimrc: - - Plug 'vimwiki/vimwiki' - -Then run `:PlugInstall`. - -Installation using [Vundle](https://github.com/VundleVim/Vundle.vim) ------------------------------------------------------------------------------- - -Add `Plugin 'vimwiki/vimwiki'` to your vimrc file and run - - vim +PluginInstall +qall - -Or download the [zip archive](https://github.com/vimwiki/vimwiki/archive/master.zip) and extract it in `~/.vim/bundle/` - -Then launch Vim, run `:Helptags` and then `:help vimwiki` to verify it was installed. - - -Getting help -============================================================================== - -Have a question? Visit the IRC channel `#vimwiki` on Freenode ([webchat](https://webchat.freenode.net/?channels=#vimwiki), also synced to Matrix/Riot: `#freenode_#vimwiki:matrix.org`) or post to the [mailing list](https://groups.google.com/forum/#!forum/vimwiki). - -Helping Vimwiki -============================================================================== - -Vimwiki has a lot of users but only very few recurring developers or people helping the community. Your help is therefore appreciated. Everyone can help! See [#625](https://github.com/vimwiki/vimwiki/issues/625) for information on how you can help. - - - ----- -\* Screenshots made with the [solarized colorscheme](https://github.com/altercation/vim-colors-solarized) -and [lightline](https://github.com/itchyny/lightline.vim) +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.