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
- 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.

View File

303
README.md
View File

@ -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 `<Leader>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 `<Leader>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:
* `<Leader>ww` -- Open default wiki index file.
* `<Leader>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.