1
0
mirror of https://github.com/SpaceVim/SpaceVim.git synced 2025-01-24 05:30:07 +08:00
SpaceVim/docs/documentation.md
2017-05-01 00:14:20 +08:00

34 KiB
Raw Blame History

title
Documentation

SpaceVim Documentation


Core Pillars

Four core pillars: Mnemonic, Discoverable, Consistent and “Crowd-Configured”.

If any of these core pillars is violated open an issue and well try our best to fix it.

Mnemonic

Key bindings are organized using mnemonic prefixes like b for buffer, p for project, s for search, h for help, etc…

Discoverable

Innovative real-time display of available key bindings. Simple query system to quickly find available layers, packages, and more.

Consistent

Similar functionalities have the same key binding everywhere thanks to a clearly defined set of conventions. Documentation is mandatory for any layer that ships with Spacemacs.

Crowd-Configured

Community-driven configuration provides curated packages tuned by power users and bugs are fixed quickly.

Highlighted features

  • Great documentation: access documentation in Vim with :h SpaceVim.
  • Beautiful GUI: you'll love the awesome UI and its useful features.
  • Mnemonic key bindings: commands have mnemonic prefixes like [Window] for all the window and buffer commands or Unite for the unite work flow commands.
  • Lazy load plugins: Lazy-load 90% of plugins with dein.vim
  • Batteries included: discover hundreds of ready-to-use packages nicely organised in configuration layers following a set of conventions.
  • Neovim centric: Dark powered mode of SpaceVim

Screenshots

welcome page

2017-04-29-20 54 49

working flow

screen shot 2017-04-26 at 4 28 07 pm

Neovim on iTerm2 using the SpaceVim color scheme base16-solarized-dark

Depicts a common frontend development scenario with JavaScript (jQuery), SASS, and PHP buffers.

Non-code buffers show a Neovim terminal, a TagBar window, a Vimfiler window and a TernJS definition window.

to get more screenshots, see: issue #415

Who can benefit from this?

  • the elementary vim users.
  • Vim users pursuing a beautiful appearance.
  • Vim users wanting to lower the risk of RSI.
  • Vim users wanting to learn a different way to edit files.
  • Vim users wanting a simple but deep configuration system.

Update and Rollback

Update SpaceVim itself

There are several methods of updating the core files of SpaceVim. It is recommended to update the packages first; see the next section.

Automatic Updates

NOTE: By default, this feature is disabled, It will slow down the startup of vim/neovim. If you like this feature, add let g:spacevim_automatic_update = 1 to your custom configuration file.

SpaceVim will automatically check for a new version every startup. You must restart Vim after updating.

Updating from the SpaceVim Buffer

Use :SPUpdate SpaceVim in SpaceVim buffer, This command will open a buffer to show the process of updating.

Updating Manually with git

To update manually close Vim and update the git repository:

git -C ~/.SpaceVim pull.

Update plugins

Use :SPUpdate command will update all the plugins and SpaceVim itself. after :SPUpdate, you can assign plugins need to be updated. Use Tab to complete plugin names after :SPUpdate.

Configuration layers

This section is an overview of layers. A more extensive introduction to writing configuration layers can be found in SpaceVim's layers page (recommended reading!).

Custom Configuration

User configuration can be stored in your ~/.SpaceVim.d directory.

Automatic Generation

The very first time SpaceVim starts up, it will ask you several questions and then create the SpaceVim.d/init.vim in your HOME directory.

Alternative directory

~/.SpaceVim.d/ will be added to &runtimepath of vim. read :h rtp.

It is also possible to override the location of ~/.SpaceVim.d/ using the environment variable SPACEVIMDIR. Of course you can also use symlinks to change the location of this directory.

SpaceVim also support local config file for project, the init file is .SpaceVim.d/init.vim in the root of your project. .SpaceVim.d/ will also be added into runtimepath.

here is an example config file for SpaceVim:

" Here are some basic customizations, please refer to the ~/.SpaceVim.d/init.vim
" file for all possible options:
let g:spacevim_default_indent = 3
let g:spacevim_max_column     = 80

" Change the default directory where all miscellaneous persistent files go.
" By default it is ~/.cache/vimfiles.
let g:spacevim_plugin_bundle_dir = '~/.cache/vimfiles'

" set SpaceVim colorscheme
let g:spacevim_colorscheme = 'jellybeans'

" Set plugin manager, you want to use, default is dein.vim
let g:spacevim_plugin_manager = 'dein'  " neobundle or dein or vim-plug

" use space as `<Leader>`
let mapleader = "\<space>"

" Set windows shortcut leader [Window], default is `s`
let g:spacevim_windows_leader = 's'

" Set unite work flow shortcut leader [Unite], default is `f`
let g:spacevim_unite_leader = 'f'

" By default, language specific plugins are not loaded. This can be changed
" with the following, then the plugins for go development will be loaded.
call SpaceVim#layers#load('lang#go')

" loaded ui layer
call SpaceVim#layers#load('ui')

" If there is a particular plugin you don't like, you can define this
" variable to disable them entirely:
let g:spacevim_disabled_plugins=[
    \ ['junegunn/fzf.vim'],
    \ ]

" If you want to add some custom plugins, use these options:
let g:spacevim_custom_plugins = [
    \ ['plasticboy/vim-markdown', {'on_ft' : 'markdown'}],
    \ ['wsdjeg/GitHub.vim'],
    \ ]

" set the guifont
let g:spacevim_guifont = 'DejaVu\ Sans\ Mono\ for\ Powerline\ 11'

Comprehensive documentation is available for each layer by :h SpaceVim.

Awesome ui

SpaceVim has a minimalistic and distraction free UI:

  • custom airline with color feedback according to current check status
  • custom icon in sign column and error feedbacks for checker.

Colorschemes

The default colorscheme of SpaceVim is gruvbox. There are two variants of this colorscheme, a dark one and a light one. Some aspects of these colorscheme can be customized in the custom configuration file, read :h gruvbox.

It is possible to define your default themes in your ~/.SpaceVim.d/init.vim with the variable colorschemes. For instance, to specify vim-one with dark colorscheme:

let g:spacevim_colorscheme = 'one'
let g:spacevim_colorscheme_bg = 'dark'
Mappings Description
SPC T n switch to next random colorscheme listed in colorscheme layer.
SPC T s select a theme using a unite buffer.

all the included colorscheme can be found in colorscheme layer.

NOTE:

SpaceVim use true colors by default, so you should make sure your terminal support true colors. for more information see: Colours in terminal

Font

The default font used by SpaceVim is DejaVu Sans Mono for Powerline. It is recommended to install it on your system if you wish to use it.

To change the default font set the variable g:spacevim_guifont in your ~/.SpaceVim.d/init.vim file. By default its value is:

let g:spacevim_guifont = 'DejaVu\ Sans\ Mono\ for\ Powerline\ 11'

If the specified font is not found, the fallback one will be used (depends on your system). Also note that changing this value has no effect if you are running Vim/Neovim in terminal.

UI Toggles

Some UI indicators can be toggled on and off (toggles start with t and T):

Key Binding Description
SPC t 8 highlight any character past the 80th column
SPC t f display the fill column (by default the fill column is set to 80)
SPC t h h toggle highlight of the current line
SPC t h i toggle highlight indentation levels
SPC t h c toggle highlight indentation current column
SPC t h s toggle syntax highlighting
SPC t i toggle indentation guide at point
SPC t l toggle truncate lines
SPC t L toggle visual lines
SPC t n toggle line numbers
SPC t v toggle smooth scrolling
SPC T ~ display ~ in the fringe on empty lines
SPC T F toggle frame fullscreen
SPC T f toggle display of the fringe
SPC T m toggle menu bar
SPC T M toggle frame maximize
SPC T t toggle tool bar
SPC T T toggle frame transparency and enter transparency transient state

Features

Awesome ui

  • outline + filemanager + checker 2017-02-01_1360x721

Mnemonic key bindings

Key bindings are organized using mnemonic prefixes like b for buffer, p for project, s for search, h for help, etc…

SPC mapping root : SPC means <Space> on the keyboard.

Key Description
SPC ! shell cmd
SPC a +applications
SPC b +buffers
SPC 1...9 windows 1...9

Language specific mode

Key Mapping

c/c++ support

  1. code completion: autocompletion and fuzzy match. 2017-02-01_1359x720
  2. syntax check: Asynchronous linting and make framework. 2017-02-01_1359x722

go support

  1. code completion: 2017-02-01_1360x721
  2. syntax check: 2017-02-01_1359x720

python support

  1. code completion: 2017-02-02_1360x724
  2. syntax check: 2017-02-02_1358x720

Neovim centric - Dark powered mode of SpaceVim.

By default, SpaceVim use these dark powered plugins:

  1. deoplete.nvim - Dark powered asynchronous completion framework for neovim
  2. dein.vim - Dark powered Vim/Neovim plugin manager

TODO:

  1. defx.nvim - Dark powered file explorer
  2. deoppet.nvim - Dark powered snippet plugin
  3. denite.nvim - Dark powered asynchronous unite all interfaces for Neovim/Vim8

Modular configuration

Multiple leader mode

Global origin vim leader, default : \

Vim's origin global leader can be used in all modes.

Local origin vim leader, default : ,

Vim's origin local leader can be used in all the mode.

Windows function leader, default : s

Windows function leader can only be used in normal mode. For the list of mappings see the link

Unite work flow leader, default : f

Unite work flow leader can only be used in normal mode. Unite leader need unite groups.

Unite centric work-flow

unite

  • List all the plugins has been installed, fuzzy find what you want, default action is open the github website of current plugin. default key is <leader>lp 2017-01-21_1358x725

  • List all the mappings and description: f<space> 2017-02-01_1359x723

  • List all the starred repos in github.com, fuzzy find and open the website of the repo. default key is <leader>ls 2017-02-01_1359x722

Plugin Highlights

  • Package management with caching enabled and lazy loading

  • Project-aware tabs and label

  • Vimfiler as file-manager + SSH connections

  • Go completion via vim-go and gocode

  • Javascript completion via Tern

  • PHP completion, indent, folds, syntax

  • Python jedi completion, pep8 convention

  • Languages: Ansible, css3, csv, json, less, markdown, mustache

  • Helpers: Undo tree, bookmarks, git, tmux navigation, hex editor, sessions, and much more.

    Note that 90% of the plugins are [lazy-loaded]. [lazy-loaded]: ./config/plugins.vim

Non Lazy-Loaded Plugins

Name Description
dein.vim Dark powered Vim/Neovim plugin manager
vimproc Interactive command execution
colorschemes Awesome color-schemes
file-line Allow opening a file in a given line
neomru MRU source for Unite
cursorword Underlines word under cursor
gitbranch Lightweight git branch detection
gitgutter Shows git diffs in the gutter
tinyline Tiny great looking statusline
tagabana Central location for all tags
bookmarks Bookmarks, works independently from vim marks
tmux-navigator Seamless navigation between tmux panes and vim splits

Lazy-Loaded Plugins

Language
Name Description
html5 HTML5 omnicomplete and syntax
mustache Mustache and handlebars syntax
markdown Markdown syntax highlighting
ansible-yaml Additional support for Ansible
jinja Jinja support in vim
less Syntax for LESS
css3-syntax CSS3 syntax support to vim's built-in syntax/css.vim
csv Handling column separated data
pep8-indent Nicer Python indentation
logstash Highlights logstash configuration files
tmux vim plugin for tmux.conf
json Better JSON support
toml Syntax for TOML
i3 i3 window manager config syntax
Dockerfile syntax and snippets for Dockerfile
go Go development
jedi-vim Python jedi autocompletion library
ruby Ruby configuration files
portfile Macports portfile configuration files
javascript Enhanced Javascript syntax
javascript-indent Javascript indent script
tern Provides Tern-based JavaScript editing support
php Up-to-date PHP syntax file
phpfold PHP folding
phpcomplete Improved PHP omnicompletion
phpindent PHP official indenting
phpspec PhpSpec integration
Commands
Name Description
vimfiler Powerful file explorer
[NERD Commenter] Comment tool - no comment necessary
vinarise Hex editor
syntastic Syntax checking hacks
gita An awesome git handling plugin
gista Manipulate gists in Vim
undotree Ultimate undo history visualizer
incsearch Improved incremental searching
expand-region Visually select increasingly larger regions of text
open-browser Open URI with your favorite browser
prettyprint Pretty-print vim variables
quickrun Run commands quickly
ref Integrated reference viewer
dictionary Dictionary.app interface
vimwiki Personal Wiki for Vim
thesaurus Look up words in an online thesaurus
Commands
Name Description
goyo Distraction-free writing
limelight Hyperfocus-writing
matchit Intelligent pair matching
indentline Display vertical indention lines
choosewin Choose window to use, like tmux's 'display-pane'
Completion
Name Description
delimitmate Insert mode auto-completion for quotes, parenthesis, brackets
echodoc Print objects' documentation in echo area
deoplete Neovim: Dark powered asynchronous completion framework
neocomplete Next generation completion framework
neosnippet Contains neocomplete snippets source
Unite
Name Description
unite Unite and create user interfaces
unite-colorscheme Browse colorschemes
unite-filetype Select file type
unite-history Browse history of command/search
unite-build Build with Unite interface
unite-outline File "outline" source for unite
unite-tag Tags source for Unite
unite-quickfix Quickfix source for Unite
neossh SSH interface for plugins
unite-pull-request GitHub pull-request source for Unite
junkfile Create temporary files for memo and testing
unite-issue Issue manager for JIRA and GitHub
Operators & Text Objects
Name Description
operator-user Define your own operator easily
operator-replace Operator to replace text with register content
operator-surround Operator to enclose text objects
textobj-user Create your own text objects
textobj-multiblock Handle multiple brackets objects

Custom Key bindings

Key Mode Action
<leader>+y visual Copy selection to X11 clipboard ("+y)
Ctrl+c Normal Copy full path of current buffer to X11 clipboard
<leader>+Ctrl+c Normal Copy github.com url of current buffer to X11 clipboard(if it is a github repo)
<leader>+Ctrl+l Normal/visual Copy github.com url of current lines to X11 clipboard(if it is a github repo)
<leader>+p Normal/visual Paste selection from X11 clipboard ("+p)
Ctrl+f Normal Smart page forward (C-f/C-d)
Ctrl+b Normal Smart page backwards (C-b/C-u)
Ctrl+e Normal Smart scroll down (3C-e/j)
Ctrl+y Normal Smart scroll up (3C-y/k)
Ctrl+q Normal Ctrl+w
Ctrl+x Normal Switch buffer and placement
Up,Down Normal Smart up and down
} Normal After paragraph motion go to first non-blank char (}^)
< Visual/Normal Indent to left and re-select
> Visual/Normal Indent to right and re-select
Tab Visual Indent to right and re-select
Shift+Tab Visual Indent to left and re-select
gp Normal Select last paste
Q/gQ Normal Disable EX-mode ()
Ctrl+a Command Navigation in command line
Ctrl+b Command Move cursor backward in command line
Ctrl+f Command Move cursor forward in command line
File Operations
Key Mode Action
<leader>+cd Normal Switch to the directory of the open buffer
<leader>+w Normal/visual Write (:w)
Ctrl+s Normal/visual/Command Write (:w)
:w!! Command Write as root (%!sudo tee > /dev/null %)
Editor UI
Key Mode Action
F2 All Toggle tagbar
F3 All Toggle Vimfiler
<leader> + num Normal Jump to the buffer whit the num index
<Alt> + num Normal Jump to the buffer whit the num index, this only works in neovim
<Alt> + h/<Left> Normal Jump to left buffer in the tabline, this only works in neovim
<Alt> + l/<Right> Normal Jump to Right buffer in the tabline, this only works in neovim
<leader>+ts Normal Toggle spell-checker (:setlocal spell!)
<leader>+tn Normal Toggle line numbers (:setlocal nonumber!)
<leader>+tl Normal Toggle hidden characters (:setlocal nolist!)
<leader>+th Normal Toggle highlighted search (:set hlsearch!)
<leader>+tw Normal Toggle wrap (:setlocal wrap! breakindent!)
g0 Normal Go to first tab (:tabfirst)
g$ Normal Go to last tab (:tablast)
gr Normal Go to previous tab (:tabprevious)
Ctrl+<Dow> Normal Move to split below (j)
Ctrl+<Up> Normal Move to upper split (k)
Ctrl+<Left> Normal Move to left split (h)
Ctrl+<Right> Normal Move to right split (l)
* Visual Search selection forwards
# Visual Search selection backwards
,+Space Normal Remove all spaces at EOL
Ctrl+r Visual Replace selection
<leader>+lj Normal Next on location list
<leader>+lk Normal Previous on location list
<leader>+S Normal/visual Source selection
Window Management
Key Mode Action
q Normal Smart buffer close
s+p Normal Split nicely
s+v Normal :split
s+g Normal :vsplit
s+t Normal Open new tab (:tabnew)
s+o Normal Close other windows (:only)
s+x Normal Remove buffer, leave blank window
s+q Normal Closes current buffer (:close)
s+Q Normal Removes current buffer, left buffer in the tabline will be displayed, if there is no buffer on the left, the right buffer will be displayed, if this is the last buffer in the tabline, then an empty buffer will be displayed.
Tab Normal Next window or tab
Shift+Tab Normal Previous window or tab
<leader>+sv Normal Split with previous buffer
<leader>+sg Normal Vertical split with previous buffer

SpaceVim has mapped normal q as smart buffer close, the normal func of q can be get by <leader> q r

Native functions
Key Mode Action
<leader> + qr Normal Same as native q
<leader> + qr/ Normal Same as native q/, open cmdwin
<leader> + qr? Normal Same as native q?, open cmdwin
<leader> + qr: Normal Same as native q:, open cmdwin
Plugin: Unite
Key Mode Action
[unite] Normal unite leader, default is f, :h g:spacevim_unite_leader
[unite]+r Normal Resumes Unite window
[unite]+f Normal Opens Unite file recursive search
[unite]+i Normal Opens Unite git file search
[unite]+g Normal Opens Unite grep with ag (the_silver_searcher)
[unite]+u Normal Opens Unite source
[unite]+t Normal Opens Unite tag
[unite]+T Normal Opens Unite tag/include
[unite]+l Normal Opens Unite location list
[unite]+q Normal Opens Unite quick fix
[unite]+e Normal Opens Unite register
[unite]+j Normal Opens Unite jump, change
[unite]+h Normal Opens Unite history/yank
[unite]+s Normal Opens Unite session
[unite]+n Normal Opens Unite session/new
[unite]+o Normal Opens Unite outline
[unite]+c Normal Opens Unite buffer bookmark file in current directory
[unite]+b Normal Opens Unite buffer bookmark file in buffer directory
[unite]+ma Normal Opens Unite mapping
[unite]+<space> Normal Opens Unite menu:CustomKeyMaps
[unite]+me Normal Opens Unite output messages
<leader>+bl Normal Opens Unite buffers, mru, bookmark
<leader>+ta Normal Opens Unite tab
<leader>+ugf Normal Opens Unite file with word at cursor
<leader>+ugt Normal/visual Opens Unite tag with word at cursor
Within Unite buffers
Ctrl+h/k/l/r Normal Un-map
Ctrl+r Normal Redraw
Ctrl+j Insert Select next line
Ctrl+k Insert Select previous line
' Normal Toggle mark current candidate, up
e Normal Run default action
Ctrl+v Normal Open in a split
Ctrl+s Normal Open in a vertical split
Ctrl+t Normal Open in a new tab
Tab Normal Ctrl+w+w
Escape Normal Exit unite
jj Insert Leave Insert mode
r Normal Replace ('search' profile) or rename
Tab Insert Unite autocompletion
Ctrl+z Normal/insert Toggle transpose window
Ctrl+w Insert Delete backward path
Plugin: VimFiler
Key Mode Action
<F3> Normal Toggle file explorer
Within VimFiler buffers
Ctrl+j Normal Un-map
Ctrl+l Normal Un-map
E Normal Un-map
sv Normal Split edit
sg Normal Vertical split edit
p Normal Preview
i Normal Switch to directory history
v Normal Quick look
gx Normal Execute with vimfiler associated
' Normal Toggle mark current line
V Normal Clear all marks
Ctrl+r Normal Redraw
Plugin: neocomplete
Key Mode Action
Enter Insert Smart snippet expansion
Ctrl+space Insert Autocomplete with Unite
Tab Insert/select Smart tab movement or completion
Ctrl+j/k/f/b Insert Movement in popup
Ctrl+g Insert Undo completion
Ctrl+l Insert Complete common string
Ctrl+o Insert Expand snippet
Ctrl+y Insert Close pop-up
Ctrl+e Insert Close pop-up
Ctrl+l Insert Complete common string
Ctrl+d Insert Scroll down
Ctrl+u Insert Scroll up
Plugin: NERD Commenter
Key Mode Action
<leader>+cc Normal/visual Comment out the current line or text selected in visual mode.
<leader>+cn Normal/visual Same as cc but forces nesting.
<leader>+cu Normal/visual Uncomments the selected line(s).
<leader>+cs Normal/visual Comments out the selected lines with a pretty block formatted layout.
<leader>+cy Normal/visual Same as cc except that the commented line(s) are yanked first.
Plugin: Goyo and Limelight
Key Mode Action
<leader>+G Normal Toggle distraction-free writing
Plugin: ChooseWin
Key Mode Action
- Normal Choose a window to edit
<leader>+- Normal Switch editing window with selected
Plugin: Bookmarks
Key Mode Action
m+a Normal Show list of all bookmarks
m+m Normal Toggle bookmark in current line
m+n Normal Jump to next bookmark
m+p Normal Jump to previous bookmark
m+i Normal Annotate bookmark

As SpaceVim use above bookmarks mappings, so you can not use a, m, n, p or i registers to mark current position, but other registers should works will. if you really need to use these registers, you can add nnoremap <leader>m m to your custom configuration, then you use use a registers via \ma

Plugin: Gita
Key Mode Action
<leader>+gs Normal Git status
<leader>+gd Normal Git diff
<leader>+gc Normal Git commit
<leader>+gb Normal Git blame
<leader>+gp Normal Git push
Plugin: vim-signify
Key Mode Action
<leader>+hj / ]c Normal Jump to next hunk
<leader>+hk / [c Normal Jump to previous hunk
<leader>+hJ / ]C Normal Jump to last hunk
<leader>+hK / [C Normal Jump to first hunk
Misc Plugins
Key Mode Action
<leader>+gu Normal Open undo tree
<leader>+i Normal Toggle indentation lines
<leader>+j Normal Start smalls
<leader>+r Normal Quickrun
<leader>+? Normal Dictionary
<leader>+W Normal Wiki
<leader>+K Normal Thesaurus