Update and format README.md

This commit is contained in:
Monkin 2019-04-01 16:13:40 +02:00 committed by Henry Qin
parent 4f5d4c9400
commit 308e2056f6
3 changed files with 180 additions and 125 deletions

View File

@ -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 # More info and advice for (aspiring) core developers
- Before implementing a non-trivial feature, think twice what it means for the user. We should - 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 - 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 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. that everybody has their own way to use Vimwiki.

View File

239
README.md
View File

@ -1,53 +1,137 @@
A Personal Wiki For Vim # VimWiki: A Personal Wiki For Vim
==============================================================================
[中文](README-cn.md) [中文](README-cn.md)
![screenshot1](doc/screenshot_1.png) - [Intro](#intro)
![screenshot2](doc/screenshot_2.png) * - [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. their own syntax highlighting.
With Vimwiki you can: With VimWiki you can:
* organize notes and ideas * Organize notes and ideas
* manage todo-lists * Manage to-do lists
* write documentation * Write documentation
* maintain a diary * Maintain a diary
* export everything to HTML * Export everything to HTML
To do a quick start press `<Leader>ww` (this is usually `\ww`) to go to your index To do a quick start press `<Leader>ww` (this is usually `\ww`) to go to your
wiki file. By default it is located in `~/vimwiki/index.wiki`. index wiki file. By default it is located in `~/vimwiki/index.wiki`.
Feed it with the following example: Feed it with the following example:
```
= My knowledge base = = My knowledge base =
* Tasks -- things to be done _yesterday_!!! * Tasks -- things to be done _yesterday_!!!
* Project Gutenberg -- good books are power. * Project Gutenberg -- good books are power.
* Scratchpad -- various temporary stuff. * Scratchpad -- various temporary stuff.
```
Place your cursor on `Tasks` and press Enter to create a link. Once pressed, 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 `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 open it. Edit the file, save it, and then press Backspace to jump back to your
index. index.
A Vimwiki link can be constructed from more than one word. Just visually 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`. select the words to be linked and press Enter. Try it with `Project Gutenberg`.
The result should look something like: The result should look something like:
```
= My knowledge base = = My knowledge base =
* [[Tasks]] -- things to be done _yesterday_!!! * [[Tasks]] -- things to be done _yesterday_!!!
* [[Project Gutenberg]] -- good books are power. * [[Project Gutenberg]] -- good books are power.
* Scratchpad -- various temporary stuff. * Scratchpad -- various temporary stuff.
```
Basic Markup ## 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.
#### Installation using [Vim packages](http://vimhelp.appspot.com/repeat.txt.html#packages) (since Vim 7.4.1528)
```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 = = Header1 =
== Header2 == == Header2 ==
=== Header3 === === Header3 ===
@ -58,10 +142,11 @@ Basic Markup
[[wiki link]] -- wiki link [[wiki link]] -- wiki link
[[wiki link|description]] -- wiki link with description [[wiki link|description]] -- wiki link with description
```
### Lists:
Lists: ```
* bullet list item 1 * bullet list item 1
- bullet list item 2 - bullet list item 2
- bullet list item 3 - bullet list item 3
@ -76,15 +161,13 @@ Lists:
2. numbered list item 2 2. numbered list item 2
a) numbered list item 3 a) numbered list item 3
b) numbered list item 4 b) numbered list item 4
```
For other syntax elements, see `:h vimwiki-syntax` For other syntax elements, see `:h vimwiki-syntax`
## Key bindings
Key bindings Normal mode:
------------------------------------------------------------------------------
normal mode:
* `<Leader>ww` -- Open default wiki index file. * `<Leader>ww` -- Open default wiki index file.
* `<Leader>wt` -- Open default wiki index file in a new tab. * `<Leader>wt` -- Open default wiki index file in a new tab.
@ -100,89 +183,61 @@ normal mode:
For more keys, see `:h vimwiki-mappings` 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-commands` -- list all commands
* `:help vimwiki` -- General vimwiki help docs * `: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:
```vim
If you would prefer to use either Markdown or MediaWiki syntaxes, set the following option in your .vimrc:
```
let g:vimwiki_list = [{'path': '~/vimwiki/', let g:vimwiki_list = [{'path': '~/vimwiki/',
\ 'syntax': 'markdown', 'ext': '.md'}] \ 'syntax': 'markdown', 'ext': '.md'}]
``` ```
## Getting help
Installation **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).
Prerequisites ## Helping VimWiki
------------------------------------------------------------------------------
Make sure you have these settings in your vimrc file: 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.
set nocompatible ## License
filetype plugin on
syntax on
Without them Vimwiki will not work properly. MIT License
Copyright (c) 2008-2010 Maxim Kim
2013-2017 Daniel Schemala
Installation using [Vim packages](http://vimhelp.appspot.com/repeat.txt.html#packages) (since Vim 7.4.1528) 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:
git clone https://github.com/vimwiki/vimwiki.git ~/.vim/pack/plugins/start/vimwiki The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
Installation using [Pathogen](http://www.vim.org/scripts/script.php?script_id=2332) 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
cd ~/.vim AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
mkdir bundle LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
cd bundle OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
git clone https://github.com/vimwiki/vimwiki.git 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)