34 KiB
title |
---|
Documentation |
SpaceVim Documentation
-
Features
Core Pillars
Four core pillars: Mnemonic, Discoverable, Consistent and “Crowd-Configured”.
If any of these core pillars is violated open an issue and we’ll 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
working flow
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
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
- code completion: autocompletion and fuzzy match.
- syntax check: Asynchronous linting and make framework.
go support
python support
Neovim centric - Dark powered mode of SpaceVim.
By default, SpaceVim use these dark powered plugins:
- deoplete.nvim - Dark powered asynchronous completion framework for neovim
- dein.vim - Dark powered Vim/Neovim plugin manager
TODO:
- defx.nvim - Dark powered file explorer
- deoppet.nvim - Dark powered snippet plugin
- 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
-
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
-
List all the starred repos in github.com, fuzzy find and open the website of the repo. default key is
<leader>ls
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 |