diff --git a/core/core-spacemacs-buffer.el b/core/core-spacemacs-buffer.el
index f0e46d0d4..dcc158cba 100644
--- a/core/core-spacemacs-buffer.el
+++ b/core/core-spacemacs-buffer.el
@@ -420,7 +420,7 @@ HPADDING is the horizontal spacing betwee the content line and the frame border.
:help-echo "Open the Spacemacs documentation in your browser."
:mouse-face 'highlight
:follow-link "\C-m"
- "https://github.com/syl20bnr/spacemacs/blob/master/doc/DOCUMENTATION.md")
+ "https://github.com/syl20bnr/spacemacs/blob/master/doc/DOCUMENTATION.org")
(insert " ")
(widget-create 'url-link
:tag (propertize "Gitter Chat" 'face 'font-lock-keyword-face)
diff --git a/doc/DOCUMENTATION.md b/doc/DOCUMENTATION.md
deleted file mode 100644
index af4d2a22b..000000000
--- a/doc/DOCUMENTATION.md
+++ /dev/null
@@ -1,2689 +0,0 @@
-
-**Table of Contents**
-
-- [Spacemacs Documentation](#spacemacs-documentation)
-- [Core Pillars](#core-pillars)
- - [Mnemonic](#mnemonic)
- - [Discoverability](#discoverability)
- - [Consistency](#consistency)
- - [Crowd-Configured](#crowd-configured)
-- [Goals](#goals)
-- [Screenshots](#screenshots)
-- [Who can benefit from this ?](#who-can-benefit-from-this-)
-- [Update and Rollback](#update-and-rollback)
- - [Update Spacemacs repository](#update-spacemacs-repository)
- - [Update packages](#update-packages)
-- [Configuration layers](#configuration-layers)
- - [Structure](#structure)
- - [Extensions and Packages](#extensions-and-packages)
- - [Within a layer](#within-a-layer)
- - [Declaration](#declaration)
- - [Initialization](#initialization)
- - [Exclusion](#exclusion)
- - [Without a layer](#without-a-layer)
- - [Packages synchronization (Vundle like feature)](#packages-synchronization-vundle-like-feature)
- - [Types of configuration layers](#types-of-configuration-layers)
- - [Submitting a configuration layer upstream](#submitting-a-configuration-layer-upstream)
- - [Example: Themes Megapack example](#example-themes-megapack-example)
- - [Managing private configuration layers](#managing-private-configuration-layers)
- - [Using the private directory](#using-the-private-directory)
- - [Using an external Git repository](#using-an-external-git-repository)
- - [Using a personal branch](#using-a-personal-branch)
-- [Dotfile Configuration](#dotfile-configuration)
- - [Installation](#installation)
- - [Synchronization of dotfile changes](#synchronization-of-dotfile-changes)
- - [Content](#content)
- - [Using configuration layers](#using-configuration-layers)
- - [Setting configuration layers variables](#setting-configuration-layers-variables)
- - [Excluding packages](#excluding-packages)
- - [Hooks](#hooks)
- - [Custom variables](#custom-variables)
-- [Main principles](#main-principles)
- - [Evil](#evil)
- - [Holy](#holy)
- - [States](#states)
- - [Evil leader](#evil-leader)
- - [Universal argument](#universal-argument)
- - [Micro-states](#micro-states)
-- [Differences between Vim, Evil and Spacemacs](#differences-between-vim-evil-and-spacemacs)
- - [The vim-surround case](#the-vim-surround-case)
-- [Evil plugins](#evil-plugins)
-- [Spacemacs UI](#spacemacs-ui)
- - [Graphical UI](#graphical-ui)
- - [Color themes](#color-themes)
- - [Font](#font)
- - [Graphical UI Toggles](#graphical-ui-toggles)
- - [Mouse usage](#mouse-usage)
- - [Mode-line](#mode-line)
- - [Flycheck integration](#flycheck-integration)
- - [Anzu integration](#anzu-integration)
- - [Battery status integration](#battery-status-integration)
- - [Powerline separators](#powerline-separators)
- - [Minor Modes](#minor-modes)
-- [Commands](#commands)
- - [Vim key bindings](#vim-key-bindings)
- - [Escaping](#escaping)
- - [Executing Vim and Emacs ex/M-x commands](#executing-vim-and-emacs-exm-x-commands)
- - [Leader key](#leader-key)
- - [Reserved prefix command for user](#reserved-prefix-command-for-user)
- - [Helm](#helm)
- - [C-z and Tab switch](#c-z-and-tab-switch)
- - [Helm micro-state](#helm-micro-state)
- - [Discovering](#discovering)
- - [Key bindings](#key-bindings)
- - [Guide-key](#guide-key)
- - [Helm describe key bindings](#helm-describe-key-bindings)
- - [Getting help](#getting-help)
- - [Available layers](#available-layers)
- - [Available packages in Spacemacs](#available-packages-in-spacemacs)
- - [New packages from ELPA repositories](#new-packages-from-elpa-repositories)
- - [Toggles](#toggles)
- - [Navigating](#navigating)
- - [Point/Cursor](#pointcursor)
- - [Smooth scrolling](#smooth-scrolling)
- - [Vim motions with ace-jump mode](#vim-motions-with-ace-jump-mode)
- - [ace-link mode](#ace-link-mode)
- - [Window manipulation](#window-manipulation)
- - [Window manipulation key bindings](#window-manipulation-key-bindings)
- - [Window manipulation micro-state](#window-manipulation-micro-state)
- - [Golden ratio](#golden-ratio)
- - [Buffers and Files](#buffers-and-files)
- - [Buffers manipulation key bindings](#buffers-manipulation-key-bindings)
- - [Buffers manipulation manipulation micro-state](#buffers-manipulation-manipulation-micro-state)
- - [Special Buffers](#special-buffers)
- - [Files manipulations key bindings](#files-manipulations-key-bindings)
- - [Emacs and Spacemacs files](#emacs-and-spacemacs-files)
- - [Ido](#ido)
- - [Ido micro-state](#ido-micro-state)
- - [NeoTree file tree](#neotree-file-tree)
- - [NeoTree navigation](#neotree-navigation)
- - [Opening files with NeoTree](#opening-files-with-neotree)
- - [Other NeoTree key bindings](#other-neotree-key-bindings)
- - [NeoTree mode-line](#neotree-mode-line)
- - [Bookmarks](#bookmarks)
- - [DocView mode](#docview-mode)
- - [Searching](#searching)
- - [With an external tool](#with-an-external-tool)
- - [Searching in an arbitrary directory](#searching-in-an-arbitrary-directory)
- - [Searching in a project](#searching-in-a-project)
- - [Searching the web](#searching-the-web)
- - [Persistent highlighting](#persistent-highlighting)
- - [Stacking highlights](#stacking-highlights)
- - [Highlight current symbol](#highlight-current-symbol)
- - [Visual Star](#visual-star)
- - [Listing symbols by semantic](#listing-symbols-by-semantic)
- - [Helm-swoop](#helm-swoop)
- - [Editing](#editing)
- - [Paste text](#paste-text)
- - [Paste Micro-state](#paste-micro-state)
- - [Auto-indent pasted text](#auto-indent-pasted-text)
- - [Text manipulation commands](#text-manipulation-commands)
- - [Smartparens Strict mode](#smartparens-strict-mode)
- - [Zooming](#zooming)
- - [Text](#text)
- - [Frame](#frame)
- - [Increase/Decrease numbers](#increasedecrease-numbers)
- - [Spell checking](#spell-checking)
- - [Region selection](#region-selection)
- - [Expand-region](#expand-region)
- - [Indent text object](#indent-text-object)
- - [Region narrowing](#region-narrowing)
- - [Line formatting](#line-formatting)
- - [Replacing text with iedit](#replacing-text-with-iedit)
- - [iedit states key bindings](#iedit-states-key-bindings)
- - [State transitions](#state-transitions)
- - [In iedit state](#in-iedit-state)
- - [In iedit-insert state](#in-iedit-insert-state)
- - [Examples](#examples)
- - [Replacing text in several files](#replacing-text-in-several-files)
- - [Commenting](#commenting)
- - [Deleting files](#deleting-files)
- - [Editing Lisp code](#editing-lisp-code)
- - [Lisp Key Bindings](#lisp-key-bindings)
- - [Lisp state key bindings](#lisp-state-key-bindings)
- - [Emacs lisp specific key bindings](#emacs-lisp-specific-key-bindings)
- - [Managing projects](#managing-projects)
- - [Registers](#registers)
- - [Errors handling](#errors-handling)
- - [Compiling](#compiling)
- - [Modes](#modes)
- - [Major Mode leader key](#major-mode-leader-key)
- - [Helm](#helm)
- - [Python](#python)
- - [JavaScript](#javascript)
- - [HTML and CSS](#html-and-css)
-- [Emacs Server](#emacs-server)
- - [Connecting to the Emacs server](#connecting-to-the-emacs-server)
- - [Keeping the server alive](#keeping-the-server-alive)
- - [Troubleshoot](#troubleshoot)
- - [Loading fails](#loading-fails)
- - [I have no file ~/.spacemacs](#i-have-no-file-spacemacs)
-- [Achievements](#achievements)
- - [Issues](#issues)
- - [Merged Pull Requests](#merged-pull-requests)
- - [Stars, forks and watchers](#stars-forks-and-watchers)
- - [Specials](#specials)
-- [Thank you](#thank-you)
-
-
-# Spacemacs Documentation
-
-
-# Core Pillars
-
-Four core pillars: Mnemonic, Discoverability, Consistency, "Crowd-Configured".
-
-If any of these core pillars is violated open an issue and we'll fix it.
-
-## Mnemonic
-
-`Spacemacs` organizes key bindings by mnemonic namespaces as much as possible.
-If you are looking for commands to operate on your buffer, they are right under
-SPC b, if you want to operate on your project, then it is
-SPC p, etc...
-
-## Discoverability
-
-`Spacemacs` comes with a dedicated major mode `spacemacs-mode`. Its goal is to
-give useful feedbacks and easily perform maintenance tasks.
-
-It also comes with dedicated [helm][helm-link] sources to quickly find layers, packages
-and more.
-
-[guide-key][] is enabled by default, it will display all the available key
-bindings in a dedicated popup buffer.
-
-## Consistency
-
-Similar functionalities should have the same key binding no matter which major
-is currently active. For instance if you are looking for the definition of a
-function, the binding is SPC m g g, `m` for `major mode` and `g g`
-for `go to thing at point`. No matter what is the major mode it is the same
-binding to perform this action.
-
-This is also true for the documentation, each configuration layer comes with
-an associated `README.md` file with the same base layout.
-
-The consistency core pillar is supported by a convention file:
-[CONVENTIONS.md][]
-
-## Crowd-Configured
-
-By defining an very light structure called `configuration layer` which is easy
-to understand, `Spacemacs` makes it easy to contribute additional support.
-
-The conventions in [CONVENTIONS.md][] make it easy to get the spacemacs way
-and keep consistency even if there are a lot of contributions.
-
-`Crowd-configuration` is the most powerful pillar of `Spacemacs`. Anybody can
-submit upstream improvements to configuration layers or a whole new one. Any
-user can easily and directly use this layer by adding it to a list in a
-dotfile. It is even possible to exclude _any_ unwanted packages.
-
-# Goals
-
-- **Bring the power of modal editing** to the powerful Emacs editing platform.
-
-- Integrate nicely with `Evil` states (`Vim` modes): `Spacemacs` tries to
-**keep your fingers on the home row** as much as possible, no matter the mode
-you are in.
-
-- **Crowd-configured**: Contribute easily your improvements and new
-configuration layers.
-
-- **Minimalistic and nice graphical UI**, keep your available screen space for
-what matters: your text files.
-
-- **Mnemonic and consistent key bindings** which should be easier to learn
-and remember and be the same in all major modes.
-
-- **Fast boot time**, everything is lazy-loaded.
-
-- **Lower the risk of RSI** by heavily using the space bar instead of modifiers.
-
-- Hopefully, if it's not already the case:
-
-Ɛ>Ɛ>Ɛ> **make you love modal editing!** <3<3<3
-
-# Screenshots
-
-_Startup_
-![spacemacs_startup](img/spacemacs-startup.png)
-
-_Python_
-![spacemacs_python](img/spacemacs-python.png)
-
-_Terminal (urxvt)_
-![spacemacs_urxvt](img/spacemacs-urxvt.png)
-
-*Note: Even though screenshots are updated frequently, `Spacemacs` is evolving
-quickly and the screenshots may not reflect exactly the current state of the
-project.*
-
-# Who can benefit from this ?
-
-`Spacemacs` is first intended to be used by **Vim users** who want to go to the
-next level by using Emacs. There is a [guide][vim-migration] for these users to
-supplement the documentation.
-
-It is also a good fit for people wanting to **lower the [risk of RSI][RSI]**
-induced by the default Emacs key bindings (this is an assumption, there is no
-official studies to prove this).
-
-Emacs users wanting to learn **a different way to edit files** or wanting to
-learn Vim key bindings.
-
-As a side note, if you are a programmer and you don't know Vim key bindings
-yet, I deeply recommend you to learn the basics as recommended in
-[Sacha Chua's one-page guide][sacha_guide] about how to learn Emacs.
-
-# Update and Rollback
-
-For now it is still needed to update the `Spacemacs` repository manually.
-
-## Update Spacemacs repository
-
-Close Emacs and update the git repository:
-
- ```sh
- git pull --rebase
- git submodule sync; git submodule update
- ```
-
-**Note** It is recommended to update the packages first, see next session.
-
-## Update packages
-
-To update `Spacemacs` press RET (enter) or click on the link
-`[Update]` in the startup page under the banner then restart Emacs.
-
-If anything goes wrong you should be able to rollback the update by pressing
-RET or clicking on the `[Rollback]` link next to the `[Update]`
-link and choose a rollback slot (sorted by date).
-
-# Configuration layers
-
-## Structure
-
-Configuration is organized in layers. Each layer has the following structure:
-
-```
-[layer_name]
- |__ [extensions]
- | |__ [mode 1]
- | | ...
- | |__ [mode n]
- |__ config.el
- |__ extensions.el
- |__ funcs.el
- |__ keybindings.el
- |__ packages.el
-
-[] = directory
-```
-
-Where:
-
- File | Usage
-------------------|-----------------------------------------------------------
-config.el | Emacs built-in configuration or mandatory configuration
-extensions.el | The list of extensions to load and the functions to initialize them
-funcs.el | Various functions and macros (often used in keybindings.el)
-keybindings.el | Emacs built-in key bindings or mandatory key bindings
-packages.el | The list of packages to install and the functions to initialize them
-
-`Packages` are `ELPA` packages which can be installed from an `ELPA` compliant
-repository, and `Extensions` are generally elisp code from git submodules.
-
-## Extensions and Packages
-
-### Within a layer
-
-#### Declaration
-
-`Extensions` and `Packages` are declared in variables `-pre-extensions`,
-`-post-extensions` and `-packages` where `` is the layer
-name. `Pre-Extensions` are loaded before `Packages` and `Post-Extensions` are
-loaded after `Packages`.
-
-They are processed in alphabetical order so sometimes you'll have to use
-some `eval-after-load` black magic.
-
-Example:
-
-```elisp
-(setq -packages
- '(
- package1
- package2
- ...
- )
-```
-
-#### Initialization
-
-To initialize an extension or a package `xxx`, define a function with this
-format in `extensions.el` or `packages.el`:
-
-```elisp
-(defun /init-xxx ()
- ...body
-)
-```
-
-It is common to define the body with the [use-package][use-package] macro.
-
-#### Exclusion
-
-It is possible to exclude some packages from `Spacemacs` in a per layer basis.
-This is useful when a configuration layer aims to replace a stock package
-declared in the `Spacemacs` layer.
-
-To do so add the package names to exclude to the variable
-`-excluded-packages`.
-
-Example:
-
-```elisp
-(setq -excluded-packages
- '(
- package1
- package2
- ...
- )
-```
-
-### Without a layer
-
-Sometimes a layer can be an unnecessary overhead, this is the case if you just
-want yo install a package without any configuration associated to it. A good
-example is some niche language where you are only interested syntax
-highlighting.
-
-You can install such packages by adding them to the variable
-`dotspacemacs-additional-packages` in your dotfile.
-
-If you want to add some configuration for them then consider to create a layer,
-or just put the configuration in the `dotspacemacs/config` function.
-
-Example to install `llvm-mode` and `dts-mode`:
-
-```elisp
-(setq dotspacemacs-additional-packages
- '(
- llvm-mode
- dts-mode
- )
-```
-
-## Packages synchronization (Vundle like feature)
-
-`Spacemacs` features a synchronization engine for the ELPA packages. It means
-that `Spacemacs` will auto-install the new packages in `-packages` lists
-_and_ auto-delete orphan packages in your `elpa` directory.
-
-It effectively makes `Spacemacs` behave like [Vundle][vundle].
-
-## Types of configuration layers
-
-There are three types of configuration layers:
-- core (this is the `Spacemacs` layer)
-- private (in the `private` directory, they are ignored by Git)
-- contrib (in the `contrib` directory, those layers are contributions shared by
-the community and merged upstream).
-
-## Submitting a configuration layer upstream
-
-If you decide to provide a `contrib` configuration layer, please check
-the contribution guidelines in [CONTRIBUTE.md][].
-
-## Example: Themes Megapack example
-
-This is a simple `contrib` configuration layer listing a bunch of themes,
-you can find it [here][themes-megapack].
-
-To install it, just add `themes-megapack` to your `~/.spacemacs` like so:
-
-```elisp
-(setq-default dotspacemacs-configuration-layers '(themes-megapack))
-```
-
-You have now installed around 100 themes you are free to try with SPC T h
-(helm-themes).
-
-## Managing private configuration layers
-
-`Spacemacs` configuration system is flexible enough to let you manage your
-private layers in different ways.
-
-### Using the private directory
-
-Everything in the private directory is ignored by Git so it is a good place
-to store private layers. There is a huge drawback to this approach though:
-_your layers are not source controlled_.
-
-### Using an external Git repository
-
-This is the recommended way to manage your private layers.
-
-The best approach is to store all your private layers into an external Git
-repository. It is especially a good practice to store them in your `dotfiles`
-repository if you have one. Put also your `~/.spacemacs` file in it.
-
-Then you are free to symlink your layers into `~/emacs.d/private` _or_ let
-them anywhere you want and reference the parent directory in the variable
-`dotspacemacs-configuration-layer-path` of your `~/.spacemacs`.
-
-Note that you could also have a dedicated repository for all your private
-layers and then directly clone this repository in `~/.emacs.d/private`.
-
-### Using a personal branch
-
-The final main way to manage your private layers is to push them in a personal
-branch that you keep up to date with upstream `master` or `develop`.
-
-# Dotfile Configuration
-
-User configuration can be stored in your `~/.spacemacs` file.
-
-## Installation
-
-`~/.spacemacs` is an optional file. If you want to use it you have to copy it
-manually from the template file `~/.emacs.d/core/templates/.spacemacs.template`
-
-```sh
-$ cp ~/.emacs.d/core/templates/.spacemacs.template ~/.spacemacs
-```
-
-## Synchronization of dotfile changes
-
-To apply the modifications made in `~/.spacemacs` press SPC f e R.
-It will re-execute the `Spacemacs` initialization process.
-
-**Note:** A synchronization re-execute the functions `dotspacemacs/init` and
-`dotspacemacs/config`. Depending on the content of this functions you may
-encounter some unwanted side effects. For instance if you use a toggle in
-`dotspacemac/config` to enable some behavior, this behavior will be turned off
-whenever the dotfile is re-synchronize. To avoid these side-effects it is
-recommended to use `setq` expressions instead of toggle functions.
-It is also possible to _skip_ the execution of `dotspacemacs/config` with the
-universal argument (SPC u SPC f e R).
-
-## Content
-
-### Using configuration layers
-
-To use a configuration layer, add it to the `dotspacemacs-configuration-layers`
-variable of your `~/.spacemacs`.
-
-For instance to add the configuration layer of [RMS](#thank-you):
-```elisp
-(setq-default dotspacemacs-configuration-layers '(rms))
-```
-If this layer does not exist you can still try another one in
-[the `contrib` directory](../contrib).
-
-Configuration layers are expected to be stored in `~/.emacs.d/private` or
-`~/.emacs.d/contrib`. But you are free to keep them somewhere else by declaring
-additional paths where `Spacemacs` can look for configuration layers.
-This is done by setting the list
-`dotspacemacs-configuration-layer-path` in your `~/.spacemacs`:
-
-```elisp
-(setq-default dotspacemacs-configuration-layer-path '("~/.myconfig/"))
-```
-
-### Setting configuration layers variables
-
-Some configuration layers have configuration variables to enable specific
-support. For instance the [git layer][] has several configuration variables,
-they can be set directly in the `dotspacemacs-configuration-layers` like this:
-
-```elisp
-;; List of configuration layers to load.
-dotspacemacs-configuration-layers '(auto-completion
- (git :variables
- git-magit-status-fullscreen t)
- smex)
-```
-
-### Excluding packages
-
-You can exclude packages you don't want to install with the variable
-`dotspacemacs-excluded-packages`, this variable can exclude both packages and
-extensions (see [Configuration layers](#configuration-layers) for more info
-on packages and extensions).
-
-For instance to disable the `rainbow-delimiters` package:
-```elisp
-(setq-default dotspacemacs-excluded-packages '(rainbow-delimiters))
-```
-
-When you exclude a package, `Spacemacs` will automatically delete it for you
-the next time you launch Emacs. All the orphan dependencies are as well
-delete automatically.
-
-### Hooks
-
-Two special functions of the `~/.spacemacs` file can be used to perform
-configuration at the beginning and end of `Spacemacs` loading process.
-
-- `dotspacemacs/init` is triggered at the very beginning of `Spacemacs`
-loading.
-- `dotspacemacs/config` is triggered at the very end of `Spacemacs` loading.
-
-### Custom variables
-
-Custom variables configuration from `M-x customize-group` which are
-automatically saved by Emacs are stored at the end of your `~/.spacemacs`
-file.
-
-# Main principles
-
-## Evil
-
-`Spacemacs` uses the [evil][evil] mode to emulate Vim key bindings. It is a
-very complete emulation, maybe the most advanced. In fact, Evil is much more
-than just a Vim emulation. It has more states than Vim for instance.
-
-## Holy
-
-Thanks to the new holy-mode Spacemacs can now be used by Vim users or Emacs
-users by setting the `dotspacemacs-editing-style` variable to `’vim` or `’emacs`
-in the dotfile. In Emacs style the leader is available as `M-m`. It is possible
-to dynamically switch between evil and holy modes using `SPC P tab`.
-
-### States
-
-`Spacemacs` has 9 states:
-
-State | Color | Description
--------------|-------------|--------------------------------------------------------
-normal | orange | like the `normal mode of Vim`, used to execute and combine commands
-insert | green | like the `insert mode of Vim`, used to actually insert text
-visual | gray | like the `visual mode of Vim`, used to make text selection
-motion | purple | exclusive to `Evil`, used to navigate read only buffers
-emacs | blue | exclusive to `Evil`, using this state is like using a regular Emacs without Vim
-evilified | light brown | exclusive to `Spacemacs`, this is an `emacs state` modified to bring Vim navigation, selection and search.
-lisp | pink | exclusive to `Spacemacs`, used to navigate Lisp code and modify it (more [info](#editing-lisp-code))
-iedit | red | exclusive to `Spacemacs`, used to navigate between multiple regions of text using `iedit` (more [info](#replacing-text-with-iedit))
-iedit-insert | red | exclusive to `Spacemacs`, used to replace multiple regions of text using `iedit` (more [info](#replacing-text-with-iedit))
-
-Note: Technically speaking there are also the `operator` and `replace` evil
-states.
-
-## Evil leader
-
-`Spacemacs` heavily uses the [evil-leader][evil-leader] mode which brings the
-Vim leader key to the Emacs world.
-
-This leader key is commonly set to `,` by Vim users, in `Spacemacs` the leader
-key is set on SPC (space bar, hence the name `spacemacs`).
-This key is the most accessible key on a keyboard and it is pressed with the
-thumb which is a good choice to lower the risk of [RSI][RSI].
-
-So with `Spacemacs` there is no need to remap your keyboard modifiers to
-attempt to reduce the risk of RSI, every command can be executed very easily
-while you are in `normal` mode by pressing the SPC leader key,
-here are a few examples:
-
-- Save a buffer: SPC f s
-- Save all opened buffers: SPC f S
-- Open (switch) to a buffer with `helm`: SPC b s
-
-## Universal argument
-
-The universal argument `C-u` is an important command in Emacs but it is also
-a very handy Vim key binding to scroll up.
-
-`Spacemacs` binds C-u to `scroll-up` and change the universal
-argument binding to SPC u.
-
-## Micro-states
-
-`Spacemacs` defines a wide variety of `micro-states` (temporary overlay maps)
-where it makes sense. This prevents one from doing repetitive and tedious presses on the
-SPC key.
-
-When a `micro-state` is active, a documentation is displayed in the minibuffer.
-Additional information may as well be displayed in the minibuffer.
-
-[Auto-highlight-symbol micro-state](#auto-highlight-and-edition-of-symbols):
-![spacemacs_ahs_micro_state](img/spacemacs-ahs-micro-state.png)
-
-[Text scale micro-state](#change-font-size):
-![spacemacs_scale_micro_state](img/spacemacs-scale-micro-state.png)
-
-# Differences between Vim, Evil and Spacemacs
-
-- The `,` key does "repeat last `f`, `t`, `F`, or `T` command in opposite
-direction in `Vim`, but in `Spacemacs` it is the major mode specific leader
-key by default (which can be set on another key binding in the dotfile).
-
-Send a PR to add the differences you found in this section.
-
-## The vim-surround case
-
-There is one obvious visible difference though. It is not between `Evil` and
-`Vim` but between `Spacemacs` and [vim-surround][]: the `surround` command is
-on S in `vim-surround` whereas it is on s in `Spacemacs`.
-
-This is something that can surprise some Vim users so let me explain why this is
-the case:
-- `s` and `c` do the same thing in `visual state`,
-- `s` is only useful to delete _one_ character and add more than one character
-which is a _very_ narrow use case,
-- `c` accept motions and can do everything `s` can do in `normal state`,
-- this is also true for `r` but `r` is more useful because it stays in
-`normal state`.
-- `surround` command is just a more powerful command than `s`
-
-If you are not convinced, then here is the snippet to revert back to the default
-`Vim + vim-surround` setup (add it to your `dotspacemacs/config` function or
-your `~/.spacemacs`):
-
-```elisp
-(evil-define-key 'visual evil-surround-mode-map "s" 'evil-substitute)
-(evil-define-key 'visual evil-surround-mode-map "S" 'evil-surround-region)
-```
-
-# Evil plugins
-
-`Spacemacs` ships with the following evil plugins:
-
- Mode | Description
-----------------------------------------|--------------------------------------
-[evil-leader][] | vim leader that bring a new layer of keys in normal mode
-[evil-indent-textobject][] | add text object based on indentation level
-[evil-visualstar][] | search for current selection with `*`
-[evil-exchange][] | port of [vim-exchange][]
-[evil-surround][] | port of [vim-surround][]
-[evil-matchit][] | port of [matchit.vim][]
-[evil-nerd-commenter][] | port of [nerdcommenter][]
-[evil-search-highlight-persist][] | emulation of hlsearch behavior
-[evil-numbers][] | like C-a/C-x in vim
-[evil-args][] | motions and text objects for arguments
-[evil-jumper][] | jump list emulation
-[NeoTree][neotree] | mimic [NERD Tree][nerdtree]
-
-# Spacemacs UI
-
- `Spacemacs` has unique UI elements to make the Emacs experience even
- more enjoyable:
- - dedicated startup page with a mode aimed at easily managing `Spacemacs`
- - dedicated helm source via `helm-spacemacs`
- - a [guide-key][] buffer
-
-## Graphical UI
-
-`Spacemacs` has a minimalistic and distraction free graphical UI:
-- custom [powerline][powerline] mode-line
-[with color feedback](#flycheck-integration) according to current
- [Flycheck][flycheck] status
- - unicode symbols for minor mode lighters which appear in the mode-line
- - [custom fringe bitmaps](#errors-handling) and error feedbacks for
- [Flycheck][flycheck]
- - [custom fringe bitmaps](../contrib/git/README.md#git-gutter-bitmaps) for
- git gutter (available in [git layer][])
-
-### Color themes
-
-By default, `Spacemacs` uses the theme [solarized-light][solarized-theme].
-
-It is possible to define your default themes in your `~/.spacemacs` with
-the variable `dotspacemacs-themes`. For instance, to specify `leuven` and
-`zenburn` (high contrast theme and low contrast theme):
-
-```elisp
-(setq-default dotspacemacs-themes '(leuven zenburn))
-```
-
- Key Binding | Description
----------------------|------------------------------------------------------------
-SPC T n | switch to next theme listed in `dotspacemacs-themes`.
-SPC T h | select a theme using a `helm` buffer.
-
-**Note:**
-- You don't need to explicitly list in a layer the theme packages you are
-defining in `dotspacemacs-themes`, Spacemacs is smart enough to remove those
-packages from the list of orphans.
-- Due to the inner working of themes in Emacs, switching theme during
-the same session may have some weird side effects. Although these side effects
-should be pretty rare.
-
-**Hint** If you are an `Org` user, [leuven-theme][] is amazing ;-)
-
-### Font
-
-The default font used by `Spacemacs` is [source code pro][] by Adobe. It is
-recommended to install it on your system.
-
-To change the default font set the variable `dotspacemacs-default-font` in
-your `.spacemacs` file.
-
-By default its value is:
-
-```elisp
-(setq-default dotspacemacs-default-font '("Source Code Pro"
- :size 13
- :weight normal
- :width normal
- :powerline-scale 1.1))
-```
-
-The properties should be pretty straightforward, it is possible to set any
-valid property of a [font-spec][]:
-- `:family` Font family or fontset (a string).
-- `:width` Relative character width. This should be one of the symbols:
- - ultra-condensed
- - extra-condensed
- - condensed
- - semi-condensed
- - normal
- - semi-expanded
- - expanded
- - extra-expanded
- - ultra-expanded
-- `:height` The height of the font. In the simplest case, this is an integer in
-units of 1/10 point.
-- `:weight` Font weight—one of the symbols (from densest to faintest):
- - ultra-bold
- - extra-bold
- - bold
- - semi-bold
- - normal
- - semi-light
- - light
- - extra-light
- - ultra-light
-- `:slant` Font slant—one of the symbols:
- - italic
- - oblique
- - normal
- - reverse-italic
- - reverse-oblique
-- `:size` The font size—either a non-negative integer that specifies the pixel
-size, or a floating-point number that specifies the point size.
-- `:adstyle` Additional typographic style information for the font, such as
-‘sans’. The value should be a string or a symbol.
-- `:registry` The charset registry and encoding of the font, such as
-‘iso8859-1’. The value should be a string or a symbol.
-- `:script` The script that the font must support (a symbol).
-
-The special property `:powerline-scale` is `Spacemacs` specific and it is for
-quick tweaking of the mode-line height in order to avoid crappy rendering of
-the separators like on the following screenshot (default value is 1.1).
-
-_Ugly separators_
-
-![ugly-separators](img/crappy-powerline-separators.png)
-
-### Graphical UI Toggles
-
-Some graphical UI indicators can be toggled on and off
-(toggles start with `t` and `T`):
-
- Key Binding | Description
-------------------------|------------------------------------------------------------
-SPC t ~ | display `~` in the fringe on empty lines
-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 i | toggle indentation guide at point
-SPC t l | toggle truncate lines
-SPC t L | toggle visual lines
-SPC t n | show the absolute line numbers
-
- Key Binding | Description
-------------------------|------------------------------------------------------------
-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
-
-**Note** These toggles are all available via the `helm-spacemacs` interface
-(press SPC f e h to display the `helm-spacemacs` buffer).
-
-### Mouse usage
-
-There are some added mouse features set for the line number margin (if shown):
-
-- single click in line number margin visually selects the entire line
-- drag across line number margin visually selects the region
-- double click in line number margin visually select the current code block
-
-### Mode-line
-
-The mode line is a heavily customized [powerline][powerline] with the
-following capabilities:
-- show the window number
-- color code for current state
-- show the number of search occurrences via anzu
-- toggle flycheck info
-- toggle battery info
-- toggle minor mode lighters
-
-Reminder of the color codes for the states:
-
- Evil State | Color
--------------------|------------------
-Normal | Orange
-Insert | Green
-Visual | Grey
-Emacs | Blue
-Motion | Purple
-Lisp | Pink
-Iedit/Iedit-Insert | Red
-
-Some elements can be dynamically toggled:
-
- Key Binding | Description
------------------------|------------------------------------------------------------
-SPC t m b | toggle the battery status
-SPC t m c | toggle the `org` task clock (available in `org` layer)
-SPC t m f | toggle the flycheck info (available in `syntax-checking` layer)
-SPC t m m | toggle the minor mode lighters
-SPC t m n | toggle the cat! (if `colors` layer is declared in your dotfile)
-SPC t m p | toggle the point character position
-SPC t m t | toggle the mode line itself
-SPC t m v | toggle the new version lighter
-
-#### Flycheck integration
-
-When [Flycheck][flycheck] minor mode is enabled, a new element appears showing
-the number of errors, warnings and info.
-
-![powerline-wave](img/powerline-wave.png)
-
-#### Anzu integration
-
-[Anzu][anzu] shows the number of occurrence when performing a search. `Spacemacs`
-integrates nicely the Anzu status by displaying it temporarily when `n` or `N` are
-being pressed. See the `5/6` segment on the screenshot below.
-
-![powerline-anzu](img/powerline-anzu.png)
-
-#### Battery status integration
-
-[fancy-battery][] displays the percentage of total charge of the battery as
-well as the time remaining to charge or discharge completely the battery.
-
-A color code is used for the battery status:
-
- Battery State | Color
-------------------|------------------
-Charging | Green
-Discharging | Orange
-Critical | Red
-
-Note the these colors may vary depending on your theme.
-
-#### Powerline separators
-
-It is possible to easily customize the `powerline separator` by setting the
-`powerline-default-separator` variable in your `~./spacemacs`. For instance
-if you want to set back the separator to the well-known `arrow` separator
-add the following snippet to your configuration file:
-
-```elisp
-(defun dotspacemacs/config ()
- "This is were you can ultimately override default Spacemacs configuration.
-This function is called at the very end of Spacemacs initialization."
- (setq powerline-default-separator 'arrow)
-)
-```
-
-To save you the time to try all the possible separators provided by the
-powerline, here is an exhaustive set of screenshots:
-
- Separator | Screenshot
-------------------|------------------------------------------------------------
-`alternate` | ![powerline-alternate](img/powerline-alternate.png)
-`arrow` | ![powerline-arrow](img/powerline-arrow.png)
-`arrow-fade` | ![powerline-arrow-fade](img/powerline-arrow-fade.png)
-`bar` | ![powerline-bar](img/powerline-bar.png)
-`box` | ![powerline-box](img/powerline-box.png)
-`brace` | ![powerline-brace](img/powerline-brace.png)
-`butt` | ![powerline-butt](img/powerline-butt.png)
-`chamfer` | ![powerline-chamfer](img/powerline-chamfer.png)
-`contour` | ![powerline-contour](img/powerline-contour.png)
-`curve` | ![powerline-curve](img/powerline-curve.png)
-`rounded` | ![powerline-rounded](img/powerline-rounded.png)
-`roundstub` | ![powerline-roundstub](img/powerline-roundstub.png)
-`slant` | ![powerline-slant](img/powerline-slant.png)
-`wave` | ![powerline-wave](img/powerline-wave.png)
-`zigzag` | ![powerline-zigzag](img/powerline-zigzag.png)
-`nil` | ![powerline-nil](img/powerline-nil.png)
-
-#### Minor Modes
-
-`Spacemacs` uses [diminish][diminish] mode to reduce the size of minor mode
-indicators:
-
-The minor mode area can be toggled on and off with:
-
- t m m
-
-Unicode symbols are displayed by default. Setting the variable
-`dotspacemacs-mode-line-unicode-symbols` to `nil` in your `~/.spacemacs` will
-display ASCII characters instead (may be useful in terminal if you
-cannot set an appropriate font).
-
-The letters displayed in the mode-line correspond to the key bindings used
-to toggle them.
-
-Some toggle have two flavors: local and glocal. The global version of the
-toggle can be reached using the `control` key.
-
-Key Binding | Unicode | ASCII | Mode
----------------------|:-----------:|:----------:|----------------------------------------------------
-SPC t - | `⊝` | - | [centered-cursor][] mode
-SPC t C-- | | | global centered cursor
-SPC t a | `ⓐ` | a | auto-completion
-SPC t c | `ⓒ` | c | camel case motion with subword mode
-`none` | `ⓔ` | e | [evil-org][evil-org-mode] mode
-SPC t c | | | fill-column-indicator mode
-SPC t F | `Ⓕ` | F | auto-fill mode
-SPC t g | `ⓖ` | g | [golden-ratio][] mode
-SPC t k | `Ⓖ` | G | guide-key mode
-SPC t i | `ⓘ` | i | indentation guide
-SPC t C-i | | | global indentation guide
-SPC t I | `Ⓘ` | I | aggressive indent mode
-SPC t p | `ⓟ` | p | [smartparens][sp] mode
-SPC t C-p | | | global smartparens
-SPC t s | `ⓢ` | s | syntax checking (flycheck)
-SPC t S | `Ⓢ` | S | spell checking (flyspell)
-SPC t w | `ⓦ` | w | whitespace mode
-SPC t C-w | | | global whitespace
-SPC t y | `ⓨ` | y | [yasnippet][yasnippet] mode
-
-# Commands
-
-## Vim key bindings
-
-`Spacemacs` is based on `Vim` modal user interface to navigate and edit text.
-If you are not familiar with the `Vim` way of editing text you can try the
- [evil tutor][] lessons by pressing SPC h T at any time.
-
-### Escaping
-
-`Spacemacs` uses [evil-escape][] to easily switch between `insert state` and
-`normal state` by quickly pressing the fd keys.
-
-The choice of `fd` was made to be able to use the same sequence to escape from
-"everything" in Emacs:
-- escape from all evil states to normal state
-- escape from evil-lisp-state to normal state
-- abort evil ex command
-- quit minibuffer
-- abort isearch
-- quit magit buffers
-- quit help buffers
-- quit apropos buffers
-- quit ert buffers
-- quit undo-tree buffer
-- quit paradox
-- quit gist-list menu
-- hide neotree buffer
-
-If you find yourself in a buffer where the `Spacemacs` (SPC) or Vim
-keybindings don't work you can use this to get back to `normal state` (for
-example in SPC : customize press fd to make
-SPC b s work again).
-
-This sequence can be customized in your `~/.spacemacs`. Example to set it
-to `jj` (it is important set the variable in `dotspacemacs/init`):
-
-```elisp
-(defun dotspacemacs/init ()
- (setq-default evil-escape-key-sequence "jj"))
-```
-
-**Note:** Although `jj` or `jk` are popular choices of vim users, these key
-sequences are not optimal for `Spacemacs`. Indeed it is very easy in
-`visual state` to press quickly `jj` and inadvertently escape to `normal state`.
-
-**Important Note** One caveat of `evil-escape` is that you must not use it
-while recording macros. Use `escape` key instead.
-
-### Executing Vim and Emacs ex/M-x commands
-
- Command | Key Binding
-:---------------:|------------------------------------------------------------------
-Vim (ex-command) | `:`
-Emacs (M-x) | SPC :
-
-The command key `:` can be easily changed with the variable
-`dotspacemacs-command-key` of your `~/.spacemacs`. Note that is will change both
-`:` and `SPC :` bindings to keep the symmetry between Vim and Emacs. A good
-key can be `,` for example.
-
-### Leader key
-
-On top of `Vim` modes (modes are called states in `Spacemacs`) there is a
-special key called the leader key which once pressed gives a whole new
-keyboard layer. The leader key is by default SPC (space).
-It is possible to change this key with the variable `dotspacemacs-leader-key`.
-
-## Reserved prefix command for user
-
-SPC o is reserved for the user. Setting key bindings behind
-` o` is **guaranteed** to never conflict with `Spacemacs` defaults key
-bindings.
-
-**Example:**
-Put `(evil-leader/set-key "oc" 'org-capture)` inside `dotspacemacs/config`
-in your `~/.spacemacs` file, to be able to use SPC o c to run
-org mode capture.
-
-## Helm
-
-`Spacemacs` is powered by [Helm][helm-link] which is an incremental completion
-and selection narrowing framework.
-
-`Helm` is the central control tower of `Spacemacs`, it is used to manage
-buffers, projects, search results, configuration layers, toggles and more...
-
-Mastering `Helm` will make you a `Spacemacs` power user. Do not hesitate
-to read the [Helm documentation wiki][helm-doc].
-
-### C-z and Tab switch
-
-The command bound to C-z is much more useful than the one bound to Tab, so it
-makes sense to swap them. It's also recommended [here][tuhdo-tuto].
-
-### Helm micro-state
-
-`Spacemacs` defines a [micro-state](#micro-states) for `Helm` to make it
-work like [Vim's Unite][] plugin.
-
-Initiate the micro-state with M-SPC or s-M-SPC
-while in a `Helm` buffer.
-
-Key Binding | Description
----------------------------------------|------------------------------------------------------------
-M-SPC or s-M-SPC | initiate or leave the micro-state
-TAB | switch to actions page and leave the micro-state
-1 | execute action 0
-2 | execute action 1
-3 | execute action 2
-4 | execute action 3
-5 | execute action 4
-6 | execute action 5
-7 | execute action 6
-8 | execute action 7
-9 | execute action 8
-0 | execute action 9
-a | switch to actions page
-g | go to first candidate
-G | go to last candidate
-h | go to previous source
-j | select next candidate
-k | select previous candidate
-l | go to next source
-q | quit micro-state
-t | mark current candidate
-T | mark all candidates
-v | execute persistent action
-
-## Discovering
-
-### Key bindings
-
-#### Guide-key
-
-An help buffer is displayed each time the SPC key is pressed in
-normal mode. It lists the available key bindings and their associated
-commands.
-
-By default the [guide-key][] buffer will be displayed quickly after the key
-has been pressed. You can change the delay by setting the variable
-`dotspacemacs-guide-key-delay` to your liking (the value is in second).
-
-#### Helm describe key bindings
-
-It is possible to search for specific key bindings by pressing
-SPC ?.
-
-To narrow the list to some key bindings using the leader key type a pattern
-like this regular expression:
-
- SPC\ b
-
-which would list all `buffer` related bindings.
-
-### Getting help
-
-`Describe functions` are powerful Emacs introspection commands to get
-information about functions, variables, modes etc. These commands are bound
-thusly:
-
-Key Binding | Description
----------------------|------------------------------------------------------------------
-SPC h d b | describe bindings in a `helm` buffer
-SPC h d c | describe current character under point
-SPC h d f | describe a function
-SPC h d k | describe a key
-SPC h d m | describe current modes
-SPC h d p | describe a package
-SPC h d t | describe a theme
-SPC h d v | describe a variable
-
-Other help key bindings
-
-Key Binding | Description
----------------------|------------------------------------------------------------------
-SPC h i | search in info pages with the symbol at point
-SPC h m | search available man pages
-
-### Available layers
-
-All layers can be easily discovered via `helm-spacemacs` accessible with
-SPC f e h.
-
-The following helm actions are available:
-- default: open the layer `README.md`
-- 2nd: open the layer `packages.el`
-- 3nd: open the layer `extensions.el`
-
-#### Available packages in Spacemacs
-
-`helm-spacemacs` also lists all the packages available in `Spacemacs`.
-The entry format is `(layer) packages`. If you type `flycheck` you'll
-be able to see all the layers where `flycheck` is used.
-
-The following helm actions are available on packages:
-- default: go the package init function
-
-#### New packages from ELPA repositories
-
-`package-list-packages` is where you can browse for all available packages
-in the different Elpa repositories. It is possible to upgrade packages
-from there but it is not recommended, use the `[Update]` link on the
-`Spacemacs` startup page instead.
-
-`Spacemacs` proposes to use [Paradox][] instead of `package-list-packages`
-to list available ELPA packages.
-Paradox enhances the package list buffer with better feedbacks, new
-filters and Github information like the number of stars. Optionally you
-can also star packages directly in the buffer.
-
-**Important Note 1** Installing a new package from `Paradox` won't make it
-persistent. To install a package persistently you have to add it explicitly
-to a configuration layer.
-
-**Important Note 2** Don't _update_ your packages from `Paradox` or
-`package-list-packages` because they don't support the rollback feature of
-Spacemacs.
-
- Key Binding | Description
----------------------|------------------------------------------------------------
-/ | evil-search
-f k | filter by keywords
-f r | filter by regexp
-f u | display only installed package with updates available
-h | go left
-H | show help (not accurate)
-j | go down
-k | go up
-l | go right
-L | show last commits
-n | next search occurrence
-N | previous search occurrence
-o | open package homepage
-r | refresh
-S P | sort by package name
-S S | sort by status (installed, available, etc...)
-S * | sort by Github stars
-v | `visual state`
-V | `visual-line state`
-x | execute (action flags)
-
-### Toggles
-
-`helm-spacemacs` is also a central place to discover the available toggles.
-To display only the toggles source press C-l (or in
-[Helm micro-state](#helm-micro-state) you can press just l).
-
-The following helm actions are available on packages:
-- default: toggle on/off
-
-**Tips** Use SPC h l to resume the last helm session. It is
-handy to quickly toggle on and off a toggle.
-
-## Navigating
-
-### Point/Cursor
-
-Navigation is performed using the Vi key bindings `hjkl`.
-
-Key Binding | Description
----------------------|------------------------------------------------------------------
-`h` | move cursor left
-`j` | move cursor down
-`k` | move cursor up
-`l` | move cursor right
-`H` | move quickly up (10 lines at a time)
-`L` | move quickly down (10 lines at a time)
-SPC j h | go to the beginning of line (and set a mark at the previous location in the line)
-SPC j l | go to the end of line (and set a mark at the previous location in the line)
-SPC z z | lock the cursor at the center of the screen
-
-#### Smooth scrolling
-
-[smooth-scrolling]() prevent the point to jump when it reaches the top or
-bottom of the screen. It is enabled by default.
-
-On Windows, you may want to disable it. To disable the smooth scrolling set
-the `dotspacemacs-smooth-scrolling` variable in your `~/.spacemacs` to `nil`:
-
-```elisp
-(setq-default dotspacemacs-smooth-scrolling t)
-```
-
-### Vim motions with ace-jump mode
-
-`Spacemacs` uses the `evil` integration of [ace-jump mode][ace-jump] which
-enables the invocation of `ace-jump-mode` during motions.
-
-It is useful for deleting visually a set of lines, try the following sequence
-in a buffer containing some text:
-
- d l
-
-Key Binding | Description
----------------------|------------------------------------------------------------------
-SPC SPC | initiate ace jump word mode
-SPC l | initiate ace jump line mode
-SPC ` | go back to the previous location (before the jump)
-
-Hint: you may change to char mode by `C-c C-c` in word mode.
-
-#### ace-link mode
-
-Similar to `ace-jump-mode`, [ace-link][ace-link] allows one to jump to any link in
-`help-mode` and `info-mode` with two key strokes.
-
-Key Binding | Description
----------------------|------------------------------------------------------------------
-o | initiate ace link mode in `help-mode` and `info-mode`
-
-### Window manipulation
-
-#### Window manipulation key bindings
-
-Every window has a number displayed at the start of the mode-line and can
-be quickly accessed using ` number`.
-
-Key Binding | Description
---------------------|----------------------------------------------------------------
-SPC 1 | go to window number 1
-SPC 2 | go to window number 2
-SPC 3 | go to window number 3
-SPC 4 | go to window number 4
-SPC 5 | go to window number 5
-SPC 6 | go to window number 6
-SPC 7 | go to window number 7
-SPC 8 | go to window number 8
-SPC 9 | go to window number 9
-SPC 0 | go to window number 0
-
-Windows manipulation commands (start with `w`):
-
-Key Binding | Description
-------------------------------------------|----------------------------------------------------------------
-SPC w = | balance split windows
-SPC w b | force the focus back to the minibuffer (usefull with `helm` popups)
-SPC w c | close a window
-SPC w C | delete another window using [ace-delete-window][ace-window]
-SPC w d | toggle window dedication (dedicated window cannot be reused by a mode)
-SPC w h | move to window on the left
-SPC w H | move window to the left
-SPC w j | move to window below
-SPC w J | move window to the bottom
-SPC w k | move to window above
-SPC w K | move window to the top
-SPC w l | move to window on the right
-SPC w L | move window to the right
-SPC w m | maximize/minimize a window (maximize is equivalent to delete other windows)
-SPC w M | maximize/minimize a window, when maximized the buffer is centered
-SPC w o | cycle and focus between frames
-SPC w p m | open messages buffer in a popup window
-SPC w p p | close the current sticky popup window
-SPC w R | rotate windows clockwise
-SPC w s or SPC w / | horizontal split
-SPC w S | horizontal split and focus new window
-SPC w u | undo window layout (used to effectively undo a closed window)
-SPC w U | redo window layout
-SPC w v or SPC w - | vertical split
-SPC w V | vertical split and focus new window
-SPC w w | cycle and focus between windows
-SPC w W | select window using [ace-window][ace-window]
-
-#### Window manipulation micro-state
-
-A convenient window manipulation micro-state allows to perform most of the
-actions listed above. The micro-state allows additional actions as well like
-window resizing.
-
-Key Binding | Description
---------------------|------------------------------------------------------------
-SPC w . | initiate micro-state
-? | display the full documentation in minibuffer
-0 | go to window number 0
-1 | go to window number 1
-2 | go to window number 2
-3 | go to window number 3
-4 | go to window number 4
-5 | go to window number 5
-6 | go to window number 6
-7 | go to window number 7
-8 | go to window number 8
-9 | go to window number 9
-- | vertical split
-/ | horizontal split
-[ | shrink window horizontally
-] | enlarge window horizontally
-{ | shrink window vertically
-} | enlarge window vertically
-c | close window
-C | close other windows
-g | toggle `golden-ratio` on and off
-h | go to window on the left
-j | go to window below
-k | go to window above
-l | go to window on the right
-H | move window to the left
-J | move window to the bottom
-K | move bottom to the top
-L | move window to the right
-o | focus other frame
-R | rotate windows
-s | horizontal split
-S | horizontal split and focus new window
-u | undo window layout (used to effectively undo a closed window)
-U | redo window layout
-v | vertical split
-V | horizontal split and focus new window
-w | focus other window
-Any other key | leave the micro-state
-
-#### Golden ratio
-
-If you resize windows like crazy you may want to give a try to [golden-ratio][].
-
-`golden-ratio` resizes windows dynamically depending on whether they are
-selected or not. By default `golden-ratio` is off.
-
-The mode can be toggled on and off with:
-
- t g
-
-### Buffers and Files
-
-Since `helm` is used everywhere, by default Spacemacs uses `helm` to open files.
-
-Some users prefer the `ido` way to navigate the file system because it can
-remember the last selected directories and buffers and return is
-used to open directories instead of TAB or C-z in `helm`.
-It is possible to use `ido` instead of `helm` by setting the variable
-`dotspacemacs-use-ido` to `t` in your dotfile.
-
-#### Buffers manipulation key bindings
-
-Buffer manipulation commands (start with `b`):
-
-Key Binding | Description
------------------------|----------------------------------------------------------------
-SPC TAB | switch to alternate buffer (switch back and forth)
-SPC b b | switch to a buffer using `helm`
-SPC b d | kill the current buffer (does not delete the visited file)
-SPC b e | erase the content of the buffer (ask for confirmation)
-SPC b h | open `*spacemacs*` home buffer
-SPC b k | kill the current buffer
-SPC b K | kill all buffers except the current one
-SPC b C-K | kill all buffers matching the regexp
-SPC b m h | move a buffer to the left
-SPC b m j | move a buffer to the bottom
-SPC b m k | move a buffer to the top
-SPC b m l | move a buffer to the right
-SPC b M | swap windows using [ace-swap-window][ace-window]
-SPC b n | switch to next buffer avoiding special buffers
-SPC b p | switch to previous buffer avoiding special buffers
-SPC b P | copy clipboard and replace buffer (useful when pasting from a browser)
-SPC b R | revert the current buffer (reload from disk)
-SPC b w | toggle read-only (writable state)
-SPC b Y | copy whole buffer to clipboard (useful when copying to a browser)
-z f | Make current function or comments visible in buffer as much as possible
-
-#### Buffers manipulation manipulation micro-state
-
-A convenient buffer manipulation micro-state allows to quickly cycles through
-the opened buffer and kill them.
-
-Key Binding | Description
---------------------|------------------------------------------------------------
-SPC b . | initiate micro-state
-K | kill current buffer
-n | go to next buffer (avoid special buffers)
-N | go to previous buffer (avoid special buffers)
-Any other key | leave the micro-state
-
-#### Special Buffers
-
-Unlike vim, emacs creates many buffers that most people do not need to see.
-Some examples are `*Messages*` and `*Compile-Log*`. Spacemacs tries to automatically
-ignore buffers that are not useful. However, you may want to change the way
-Spacemacs marks buffers as useful. For instructions, see the [special buffer howto][].
-
-#### Files manipulations key bindings
-
-Files manipulation commands (start with `f`):
-
-Key Binding | Description
-------------------------------------------|----------------------------------------------------------------
-SPC f D | delete a file and the associated buffer (ask for confirmation)
-SPC f f | open file with `helm` (or `ido`)
-SPC f F | try to open the file under point `helm`
-SPC f j | jump to the current buffer file in dired
-SPC f o | open a file using the default external program
-SPC f R | rename the current file
-SPC f s | save a file
-SPC f S | save all files
-SPC f r | open a recent file with `helm`
-SPC f t | toggle file tree side bar using [NeoTree][neotree]
-SPC f y | show current file absolute path in the minibuffer
-
-#### Emacs and Spacemacs files
-
-Convenient key bindings are located under the prefix SPC f e to
-quickly navigate between `Emacs` and `Spacemacs` specific files.
-
-Key Binding | Description
-------------------------------------------|----------------------------------------------------------------
-SPC f e c | open `ido` in the `contrib` folder
-SPC f e d | open the spacemacs dotfile (`~/.spacemacs`)
-SPC f e D | open `ediff` buffer of `~/.spacemacs` and `.spacemacs.template`
-SPC f e h | discover `Spacemacs` layers and packages using `helm`
-SPC f e i | open the all mighty `init.el`
-SPC f e R | resync the dotfile with spacemacs
-SPC f e s | open `ido` in the `spacemacs` layer folder
-SPC f e v | display and copy the spacemacs version
-
-### Ido
-
-`Spacemacs` displays the `ido` minibuffer vertically thanks to the
-[ido-vertical-mode][ido-vertical-mode].
-
-Basic `ido` operations can be done with `Ctrl` key:
-
-Key Binding | Description
-------------------------|----------------------------------------------------------------
-C-\ | open a `dired buffer`
-M-\ | open a `dired buffer` in terminal
-C-d | delete selected file (ask for confirmation)
-C-h | go to parent directory
-C-j | select next file or directory
-C-k | select previous file or directory
-C-l | open the selected file
-C-n | select next file or directory
-C-o | open selected file in other window
-C-p | select previous file or directory
-C-s | open selected file in a vertically split window
-C-t | open selected file in a new frame
-C-v | open selected file in a horizontally split window
-C-S-h | go to previous directory
-C-S-j | next history element
-C-S-k | previous history element
-C-S-l | go to next directory
-C-S-nC-S-pM-SPC or s-M-SPC
-while in a `ido` buffer.
-
-Key Binding | Description
----------------------------------------|------------------------------------------------------------
-M-SPC or s-M-SPC | initiate or leave the micro-state
-? | display help
-e | open dired
-h | delete backward or parent directory
-j | next match
-J | sub directory
-k | previous match
-K | parent directory
-l | select match
-n | next directory in history
-o | open in other window
-p | previous directory in history
-q | quit micro-state
-s | open in a new horizontal split
-t | open in other frame
-v | open in a new vertical split
-
-### NeoTree file tree
-
-`Spacemacs` provides a quick and simple way to navigate in an unknown project
-file tree with [NeoTree][neotree].
-
-To toggle the `NeoTree` buffer press SPC f t or SPC p t
-(the latter open NeoTree with the root set to the projectile project root).
-
-The NeoTree window always has the number `0` so it does not shift the current
-number of the other windows. To select the NeoTree window you then use
-SPC 0.
-
-#### NeoTree navigation
-
-Navigation is centered on the `hjkl` with the hope to provide a fast navigation
-experience like in [ranger][]:
-
-Key Binding | Description
----------------------------------|----------------------------------------------------------------
-h | collapse expanded directory or go to parent node
-H | previous sibling
-j | next file or directory
-J | next expanded directory on level down
-k | previous file or directory
-K | parent directory, when reaching the root change it to parent directory
-l or RET | expand directory
-L | next sibling
-R | make a directory the root directory
-
-**Note:** The point is automatically set to the first letter of a node for a
-smoother experience.
-
-#### Opening files with NeoTree
-
-By default a file is opened in the last active window. It is possible to choose
-window number where to open a file by using a numeric argument, for instance
-2 l or 2 RET will open the current file in the windows 2.
-It is also possible to open the file in a split window with | and
--:
-
-Key Binding | Description
-----------------------------------|----------------------------------------------------------------
-l or RET | open file in last active window
-# l or 2 RET| open file in window number `#`
-\| | open file in an vertically split window
-- | open file in an horizontally split window
-
-#### Other NeoTree key bindings
-
-Key Binding | Description
----------------------------------|----------------------------------------------------------------
-TAB | toggle stretching of the buffer
-c | create a node
-d | delete a node
-g | refresh
-s | toggle showing of hidden files
-q or fd | hide `NeoTree` buffer
-r | rename a node
-
-#### NeoTree mode-line
-
-The mode-line has the following format `[x/y] d (D:a, F:b)` where:
-- `x` is the index of the current selected file or directory
-- `y` the total number of items (file and directory) in the current directory
-- `d` the name of the current directory
-- `a` the number of directories in the current directory
-- `b` the number of files in the current directory
-
-### Bookmarks
-
-Bookmarks can be set anywhere in a file. Bookmarks are persistent. They are very
-useful to jump to/open a known project. `Spacemacs` used `helm-bookmarks` to
-manage them.
-
-Open an `helm` window with the current bookmarks by pressing:
-
- h b
-
-Then in the `helm-bookmarks` buffer:
-
-Key Binding | Description
--------------------|----------------------------------------------------------------
-CTRL+d | delete the selected bookmark
-CTRL+e | edit the selected bookmark
-CTRL+f | toggle filename location
-CTRL+o | open the selected bookmark in another window
-
-To save a new bookmark, just type the name of the bookmark and press `RET`.
-
-### DocView mode
-
-`doc-view-mode` is a built-in major mode to view DVI, PostScript (PS), PDF,
-OpenDocument, and Microsoft Office documents.
-
-Key Binding | Description
--------------------|----------------------------------------------------------------
-/ | search forward
-? | search backward
-+ | enlarge
-- | shrink
-gg | go to first page
-G | go to last page
-gt | go to page number
-h | previous page
-H | adjust to height
-j | next line
-k | previous line
-K | kill proc and buffer
-l | next page
-n | go to next search occurrence
-N | go to previous search occurrence
-P | fit page to window
-r | revert
-W | adjust to width
-C-d | scroll down
-C-k | kill proc
-C-u | scroll up
-C-c C-c | toggle display text and image display
-C-c C-t | open new buffer with doc's text contents
-
-## Searching
-
-
-### With an external tool
-
-`Spacemacs` can be interfaced with different search utilities:
-- ack
-- grep
-- [ag][]
-- [pt][]
-
-**Note** `ag` and `pt` are optimized to be used in a source control repository
-but they can be used in an arbitrary directory as well.
-
-By default Spacemacs will look for the first installed tool in the list
-`("ag", "pt", "ack", "grep")`. This list can be changed in the dotfile with
-the variable `dotspacemacs-search-tools`.
-
-**Beware** if you use `pt`, [TCL parser tools][tcl] also install a command line
-tool called `pt`.
-
-#### Searching in an arbitrary directory
-
-To use these utilities in one or several arbitrary directories:
-
-Key Binding | Description
---------------------------|---------------------------------------------
-SPC s / | execute the first found utility (by default `ag`, `pt`, `ack` and `grep`)
-SPC s a | `ag`
-SPC s g | `grep`
-SPC s G | `grep` defaults to symbol at point
-SPC s k | `ack`
-SPC s p | `pt`
-SPC s L | open stored search buffer (stored with F3 in helm search buffer)
-
-**Note** Use the universal argument to change the search list of
-SPC s / to `ack` and `grep` (does not look for `ag` or `pt`).
-
-**Note** It is also possible to search in several directories at once by
-marking them in the helm buffer.
-
-**Pro Tip** Use F3 in the helm search buffer to save the list of
- results to a buffer.
-
-#### Searching in a project
-
-To use these utilities in a project using `projectile`:
-
-Key Binding | Description
---------------------------|---------------------------------------------
-SPC / | execute the first found utility (by default `ag`, `pt`, `ack` and `grep`)
-SPC p s a | `ag`
-SPC p s A | `ag` with symbol at point as default text
-SPC p s g | `grep` defaults to current region then symbol at point
-SPC p s k | `ack`
-SPC p s K | `ack` with symbol at point as default text
-SPC p s p | `pt`
-SPC p s P | `pt` with symbol at point as default text
-
-**Pro Tip** Use SPC h l to bring back the last helm session.
-
-
-#### Searching the web
-
-Key Binding | Description
---------------------------|---------------------------------------------
-SPC s w g | Get Google suggestions in emacs. Opens Google results in Browser.
-SPC s w w | Get Wikipedia suggestions in emacs. Opens Wikipedia page in Browser.
-
-### Persistent highlighting
-
-`Spacemacs` uses `evil-search-highlight-persist` to keep the searched expression
-highlighted until the next search. It is also possible to clear the
-highlighting by pressing SPC s c or executing the ex command `:noh`.
-
-### Stacking highlights
-
-With [hl-anything][] it is possible to highlight all occurrences of the word
-under point. The highlights can be stacked.
-
-Key Binding | Description
------------------------|----------------------------------------------------------------
-SPC h c | clear the highlightings
-SPC h g c | clear the highlightings globally (all opened buffers)
-SPC h h | highlight all occurrence of the word at point
-SPC h g h | highlight all occurrence of the word at point globally (all opened buffers)
-SPC h n | next highlighted occurrence
-SPC h N | previous highlighted occurrence
-SPC h p | toggle auto-highlight of the enclosing parenthesis
-SPC h r | restore saved highlights in the current buffer
-SPC h s | save current highlights
-
-### Highlight current symbol
-
-`Spacemacs` supports highlighting of the current symbol on demand (provided by
-the [auto-highlight-symbol][auto-highlight] mode) and adds a micro-state to
-easily navigate and rename this symbol.
-
-It is also possible to change the range of the navigation on the fly to:
-- buffer
-- function
-- visible area
-
-To initiate the highlighting of the current symbol under point press
-SPC s h.
-
-Navigation between the highlighted symbols can be done with the commands:
-
-Key Binding | Description
------------------------|------------------------------------------------------------
-* | initiate navigation micro-state on current symbol and jump forwards
-# | initiate navigation micro-state on current symbol and jump backwards
-SPC s b | go to the last searched occurrence of the last highlighted symbol
-SPC s e | edit all occurrences of the current symbol(*)
-SPC s h | highlight the current symbol and all its occurrence within the current range
-SPC s R | change range to default (`whole buffer`)
-
-In 'Spacemacs' highlight symbol micro-state:
-
-Key Binding | Description
---------------|------------------------------------------------------------
-e | edit occurrences (*)
-n | go to next occurrence
-N | go to previous occurrence
-d | go to next definition occurrence
-D | go to previous definition occurrence
-r | change range (`function`, `display area`, `whole buffer`)
-R | go to home occurrence (reset position to starting occurrence)
-Any other key | leave the navigation micro-state
-
-(*) using [iedit][] or the default implementation of `auto-highlight-symbol`
-
-The micro-state text in minibuffer display the following information:
-
- [6/11]* press (n/N) to navigate, (e) to edit, (r) to change range or (R) for reset
-
-Where ` [x/y]*` is:
-- M: the current range mode
- - ``: whole buffer range
- - ``: current display range
- - ``: current function range
-- `x`: the index of the current highlighted occurrence
-- `y`: the total number of occurrences
-- `*`: appears if there is at least one occurrence which is not currently
-visible.
-
-### Visual Star
-
-With [evil-visualstar][] you can search for the next occurrence of the current
-selection.
-
-It is pretty useful combined with the [expand-region](#region-selection)
-bindings.
-
-_Note:_ If the current state is not the `visual state` then pressing `*` uses
-[auto-highlight-symbol](#auto-highlight-symbols) and its micro-state.
-
-### Listing symbols by semantic
-
-Use `helm-semantic-or-imenu` command from `Helm` to quickly navigate between
-the symbols in a buffer.
-
-To list all the symbols of a buffer press:
-
- s l
-
-### Helm-swoop
-
-This is very similar to `moccur`, it displays a `helm` buffer with all the
-occurrences of the word under point. You can then change the search query
-in real-time and navigate between them easily.
-
-You can even edit the occurrences directly in the `helm` buffer and apply
-the modifications to the buffer.
-
-Key Binding | Description
------------------------|----------------------------------------------------------------
-SPC s s | execute `helm-swoop`
-SPC s S | execute `helm-multi-swoop`
-SPC s C-s | execute `helm-multi-swoop-all`
-
-## Editing
-
-### Paste text
-
-#### Paste Micro-state
-
-The paste micro-state can be enabled by settings the variable
-`dotspacemacs-enable-paste-micro-state` to `t`. By default it is disabled.
-
-When the micro-state is enabled, pressing p again will replace the
-pasted text with the previous yanked (copied) text on the kill ring.
-
-For example if you copy `foo` and `bar` then press p the text `bar`
-will be pasted, pressing p again will replace `bar` with `foo`.
-
-Key Binding | Description
-------------------------------|----------------------------------------------------------------
-p or P | paste the text before or after point and initiate the `paste` micro-state
-p | in micro-state: replace paste text with the previously copied one
-P | in micro-state: replace paste text with the next copied one
-. | paste the same text and leave the micro-state
-Any other key | leave the micro-state
-
-#### Auto-indent pasted text
-
-By default any pasted text will be auto-indented. To paste text un-indented
-use the universal argument.
-
-It is possible to disable the auto-indentation for specific major-modes by
-adding a major-mode to the variable `spacemacs-indent-sensitive-modes` in
-your `dotspacemacs/config` function.
-
-### Text manipulation commands
-
-Text related commands (start with `x`):
-
- Key Binding | Description
------------------------|------------------------------------------------------------
-SPC x u | set the selected text to lower case
-SPC x U | set the selected text to upper case
-SPC x a a | align region (or guessed section) using default rules
-SPC x a r | align region using user-specified regexp
-SPC x a m | align region at arithmetic operators (+-*/)
-SPC x a . | align region at . (for numeric tables)
-SPC x a , | align region at ,
-SPC x a ; | align region at ;
-SPC x a = | align region at =
-SPC x a & | align region at &
-SPC x a | | align region at |
-SPC x d w | delete trailing whitespaces
-SPC x g l | set languages used by translate commands
-SPC x g t | translate current word using Google Translate
-SPC x g T | reverse source and target languages
-SPC x J | move down a line of text (enter micro-state)
-SPC x K | move up a line of text (enter micro-state)
-SPC x t c | swap (transpose) the current character with the previous one
-SPC x t w | swap (transpose) the current word with the previous one
-SPC x t l | swap (transpose) the current line with the previous one
-SPC x w c | count the number of words in the selection region
-SPC x w C | count the number of occurrences per word in the select region
-
-### Smartparens Strict mode
-
-[Smartparens][sp] comes with a strict mode which prevents deletion of
-parenthesis if the result is unbalanced.
-
-This mode can be frustrating for novices, this is why it is not enabled by
-default.
-
-It is possible to enable it easily for _all programming modes_ with the
-variable `dotspacemacs-smartparens-strict-mode` of you `~/.spacemacs`.
-
-```elisp
-(setq-default dotspacemacs-smartparens-strict-mode t)
-```
-
-### Zooming
-
-#### Text
-
-The font size of the current buffer can be adjusted with the commands:
-
-Key Binding | Description
------------------------|------------------------------------------------------------
-SPC z x + | scale up the font and initiate the font scaling micro-state
-SPC z x - | scale down the font and initiate the font scaling micro-state
-SPC z x = | reset the font size (no scaling) and initiate the font scaling micro-state
-+ | increase the font size
-- | decrease the font size
-= | reset the font size
-Any other key | leave the font scaling micro-state
-
-Note that _only_ the text of the current buffer is scaled, the other buffers,
-the mode-line and the minibuffer are not affected. To zoom the whole content of
-a frame use the `zoom frame` bindings (see next section).
-
-#### Frame
-
-You can zoom in and out the whole content of the frame with the commands:
-
-Key Binding | Description
------------------------|------------------------------------------------------------
-SPC z f + | zoom in the frame content
-SPC z f - | zoom out the frame content
-SPC z f = | reset the frame content size
-+ | zoom in
-- | zoom out
-= | reset zoom
-Any other key | leave the zoom frame micro-state
-
-### Increase/Decrease numbers
-
-`Spacemacs` uses [evil-numbers][] to easily increase or increase numbers.
-
-Key Binding | Description
------------------------|------------------------------------------------------------
-SPC n + | increase the number under point by one and initiate micro-state
-SPC n - | decrease the number under point by one and initiate micro-state
-
-In micro-state:
-
-Key Binding | Description
---------------|------------------------------------------------------------
-+ | increase the number under point by one
-- | decrease the number under point by one
-Any other key | leave the micro-state
-
-**Tips:** you can increase or decrease a value by more that once by using a
-prefix argument (ie. `10 SPC n +` will add 10 to the number under point).
-
-### Spell checking
-
-Spell checking commands start with `S`:
-
- Key Binding | Description
----------------------|------------------------------------------------------------
-SPC S c | list of corrections in a `helm` buffer
-SPC S d | change dictionary language
-SPC S n | go to the next spell check error
-
-
-### Region selection
-
-Vi `Visual` modes are all supported by `evil`.
-
-#### Expand-region
-
-`Spacemacs` adds another `Visual` mode via the [expand-region][] mode.
-
-Key Binding | Description
--------------------|----------------------------------------------------------------
-SPC v | initiate expand-region mode then...
-v | expand the region by one semantic unit
-V | contract the region by one semantic unit
-r | reset the region to initial selection
-ESC | leave expand-region mode
-
-#### Indent text object
-
-With [evil-indent-textobject] the following action can be performed in
-`normal state`:
-- ii - Inner Indentation: the surrounding textblock with the same
-indentation
-- ai - Above and Indentation: ii + the line above with a different
-indentation
-- aI - Above and Indentation+: ai + the line below with a different
-indentation
-
-Example (`|` is the point):
-
-```elisp
-(while (not done)
- (messa|ge "All work and no play makes Jack a dull boy."))
-(1+ 41)
-```
-
-- vii will select the line with message
-- vai will select the whole while loop
-- vaI will select the whole fragment
-
-### Region narrowing
-
-The displayed text of a buffer can be narrowed with the commands
-(start with `n`):
-
-Key Binding | Description
------------------------|----------------------------------------------------------------
-SPC n f | narrow the buffer to the current function
-SPC n p | narrow the buffer to the visible page
-SPC n r | narrow the buffer to the selected text
-SPC n w | widen, i.e show the whole buffer again
-
-### Line formatting
-
-`Spacemacs` performs `go to the line below point and indent it` with
-SPC j k.
-You may repeat this operation with `evil-repeat` if you need to indent many lines.
-
-Line formatting commands start with `j`:
-
- Key Binding | Description
----------------------------|------------------------------------------------------------
-J | join the current line with the next line
-SPC j j | same as SPC j k but will split the current line at point
-SPC J | split a quoted string or s-expression in place
-SPC j J | split a quoted string or s-expression and auto-indent
-SPC j k | go to next line and indent it using auto-indent rules
-
-Used together these key bindings are very powerful to quickly reformat the code.
-
-### Replacing text with iedit
-
-`Spacemacs` uses the powerful [iedit][] mode through [evil-iedit-state][] to
-quickly edit multiple occurrences of a symbol or selection.
-
-`evil-iedit-state` defines two new evil states:
-- `iedit state`
-- `iedit-insert state`
-
-The color code for these states is `red`.
-
-`evil-iedit-state` has also a nice integration with [expand-region][] for quick
-edition of the current selected text by pressing e.
-
-#### iedit states key bindings
-
-##### State transitions
-
- Key Binding | From | To
--------------------|:------------------:|:-------------------------:
-SPC s e | normal or visual | iedit
-e | expand-region | iedit
-ESC | iedit | normal
-C-g | iedit | normal
-fd | iedit | normal
-ESC | iedit-insert | iedit
-C-g | iedit-insert | normal
-fd | iedit-insert | normal
-
-To sum-up, in `iedit-insert state` you have to press ESC twice to
-go back to the `normal state`. You can also at any time press C-g
-or fd to return to `normal state`.
-
-**Note:** evil commands which switch to `insert state` will switch in
-`iedit-insert state`.
-
-##### In iedit state
-
-`iedit state` inherits from `normal state`, the following key bindings are
-specific to `iedit state`.
-
- Key Binding | Description
-------------------|------------------------------------------------------------
-ESC | go back to `normal state`
-TAB | toggle current occurrence
-0 | go to the beginning of the current occurrence
-$ | go to the end of the current occurrence
-# | prefix all occurrences with an increasing number (SPC u to choose the starting number).
-A | go to the end of the current occurrence and switch to `iedit-insert state`
-D | delete the occurrences
-F | restrict the scope to the function
-gg | go to first occurrence
-G | go to last occurrence
-I | go to the beginning of the current occurrence and switch to `iedit-insert state`
-J | increase the edition scope by one line below
-K | increase the edition scope by one line above
-L | restrict the scope to the current line
-n | go to next occurrence
-N | go to previous occurrence
-p | replace occurrences with last yanked (copied) text
-S | (substitute) delete the occurrences and switch to `iedit-insert state`
-V | toggle visibility of lines with no occurrence
-U | Up-case the occurrences
-C-U | down-case the occurrences
-
-**Note:** 0, $, A and I have the
-default Vim behavior when used outside of an occurrence.
-
-##### In iedit-insert state
-
- Key Binding | Description
----------------------------|------------------------------------------------------------
-ESC | go back to `iedit state`
-C-g | go back to `normal state`
-
-#### Examples
-
-- manual selection of several words then replace: v w w SPC s e S "toto" ESC ESC
-- append text to a word on two lines: v i w SPC s e J i "toto" ESC ESC
-- substitute symbol _with expand-region_: SPC v v e S "toto" ESC ESC
-- replace symbol with yanked (copied) text _with expand region_: SPC v e p ESC ESC
-
-### Replacing text in several files
-
-Replacing an occurrence of text in several files can be performed via
-[helm-ag][].
-
-Say you want to replace all `foo` occurrences by `bar` in your current project:
-- initiate a search with SPC /
-- enter in edit mode with C-c C-e
-- go to the occurrence and enter in `iedit state` with SPC s e
-- edit the occurrences then leave the `iedit state`
-- press C-c C-c
-
-**Note** in Spacemacs, `helm-ag` despite its name works with `ack` and `pt` as
-well.
-
-### Commenting
-
-Comments are handled by [evil-nerd-commenter][], it's bound to the following keys.
-
- Key Binding | Description
----------------------|------------------------------------------------------------
-SPC ; | comment operator
-SPC c i | comment invert
-SPC c l | comment lines
-SPC c p | comment paragraphs
-SPC c r | comment region
-SPC c t | comment to line
-SPC c y | comment and yank
-
-**Tips:** To comment efficiently a block of line use the combo:
-
- ; l
-
-### Deleting files
-
-Deletion is configured to send deleted files to system trash.
-
-On OS X the `trash` program is required. It can be installed with
-[homebrew][] with the following command:
-
-```sh
-$ brew install trash
-```
-
-To disable the trash you can set the variable `delete-by-moving-to-trash`
-to `nil` in your `~/.spacemacs`.
-
-### Editing Lisp code
-
-Edition of lisp code is provided by [evil-lisp-state][].
-
-Commands will set the current state to `lisp state` where
-different commands combo can be repeated without pressing on
-SPC m.
-
-When in `lisp state` the color of the mode-line changes to pink.
-
-Examples:
-- to slurp three times while in normal state: SPC k 3 n
-- to wrap a symbol in parenthesis then slurping two times: SPC k w 2 n
-
-**Note** The `lisp state` commands are available in _any_ modes! Try it out.
-
-#### Lisp Key Bindings
-
-##### Lisp state key bindings
-
-These commands automatically switch to `lisp state`.
-
-Key Binding | Function
----------------------|------------------------------------------------------------
-SPC k % | evil jump item
-SPC k : | ex command
-SPC k ( | insert expression before (same level as current one)
-SPC k ) | insert expression after (same level as current one)
-SPC k $ | go to the end of current sexp
-SPC k ` k | hybrid version of kill sexp (can be used in non lisp dialects)
-SPC k ` p | hybrid version of push sexp (can be used in non lisp dialects)
-SPC k ` s | hybrid version of slurp sexp (can be used in non lisp dialects)
-SPC k ` t | hybrid version of transpose sexp (can be used in non lisp dialects)
-SPC k 0 | go to the beginning of current sexp
-SPC k a | absorb expression
-SPC k b | forward barf expression
-SPC k B | backward barf expression
-SPC k c | convolute expression
-SPC k ds | delete symbol
-SPC k Ds | backward delete symbol
-SPC k dw | delete word
-SPC k Dw | backward delete word
-SPC k dx | delete expression
-SPC k Dx | backward delete expression
-SPC k e | unwrap current expression and kill all symbols after point
-SPC k E | unwrap current expression and kill all symbols before point
-SPC k h | previous symbol
-SPC k H | go to previous sexp
-SPC k i | switch to `insert state`
-SPC k I | go to beginning of current expression and switch to `insert state`
-SPC k j | next closing parenthesis
-SPC k J | join expression
-SPC k k | previous opening parenthesis
-SPC k l | next symbol
-SPC k L | go to next sexp
-SPC k p | paste after
-SPC k P | paste before
-SPC k r | raise expression (replace parent expression by current one)
-SPC k s | forwared slurp expression
-SPC k S | backward slurp expression
-SPC k t | transpose expression
-SPC k u | undo
-SPC k U | got to parent sexp backward
-SPC k C-r | redo
-SPC k v | switch to `visual state`
-SPC k V | switch to `visual line state`
-SPC k C-v | switch to `visual block state`
-SPC k w | wrap expression with parenthesis
-SPC k W | unwrap expression
-SPC k y | copy expression
-
-##### Emacs lisp specific key bindings
-
-Key Binding | Function
----------------------|------------------------------------------------------------
-SPC m e $ | go to end of line and evaluate last sexp
-SPC m e b | evaluate buffer
-SPC m e c | evaluate current form (a `def` or a `set`)
-SPC m e e | evaluate last sexp
-SPC m e f | evaluate current defun
-SPC m e l | go to end of line and evaluate last sexp
-SPC m e r | evaluate region
-
-Key Binding | Function
----------------------|------------------------------------------------------------
-SPC m g g | go to definition
-SPC m h h | describe elisp thing at point (show documentation)
-SPC m t b | execute buffer tests
-SPC m t q | ask for test function to execute
-
-## Managing projects
-
-Projects in `Spacemacs` are managed with [projectile][projectile]. In
-`projectile` projects are defined implicitly, for instance the root of a
-project is found when a `.git` repository or `.projectile` file is
-encountered in the file tree.
-
-`Helm` is used whenever it is possible.
-
-To search in a project see [project searching](#searching-in-a-project).
-
-`projectile` commands start with p:
-
- Key Binding | Description
----------------------|------------------------------------------------------------
-SPC / | search in project with the best search tool available
-SPC p ! | run shell command in root
-SPC p & | run async shell command in root
-SPC p s a | run `ag`
-SPC p s k | run `ack`
-SPC p b | switch to project buffer
-SPC p c | compile project using `projectile`
-SPC p d | find directory
-SPC p D | open project root in `dired`
-SPC p f | find file
-SPC p s g | run `grep`
-SPC p h | find file using `helm`
-SPC p I | invalidate the projectile cache
-SPC p k | kill all project buffers
-SPC p o | run `multi-occur`
-SPC p p | switch project
-SPC p R | regenerate the project's [e|g]tags
-SPC p r | replace a string
-SPC p s | see [search in project](#searching-in-a-project)
-SPC p t | open `NeoTree` in `projectile` root
-SPC p T | find test files
-SPC p v | open project root in `vc-dir` or `magit`
-SPC p y | find tags
-
-## Registers
-
-Access commands to the various registers start with `r`:
-
- Key Binding | Description
----------------------|------------------------------------------------------------
-SPC r e | show evil yank and named registers
-SPC r m | show marks register
-SPC r r | show helm register
-SPC r y | show kill ring
-
-## Errors handling
-
-`Spacemacs` uses [Flycheck][flycheck] to gives error feedback on the fly.
-The checks are only performed at save time by default.
-
-Errors management commands (star with `e`):
-
- Key Binding | Description
----------------------|------------------------------------------------------------
-SPC e c | clear all errors
-SPC e f | toggle flycheck
-SPC e l | display the `flycheck` list of errors/warnings
-SPC e n | go to the next error
-SPC e p | go to the previous error
-
-Custom fringe bitmaps:
-
- Symbol | Description
-:----------------------------------:|------------
-![dot-error](img/dot-error.png) | Error
-![dot-warning](img/dot-warning.png) | warning
-![dot-info](img/dot-info.png) | Info
-
-## Compiling
-
-`Spacemacs` binds a few commands to support compiling a project.
-
- Key Binding | Description
----------------------|------------------------------------------------------------
-SPC c c | use `helm-make` via projectile
-SPC c C | compile
-SPC c r | recompile
-
-## Modes
-
-### Major Mode leader key
-
-Key bindings specific to the current `major mode` start with SPC m.
-For convenience a shortcut key called the major mode leader key is set by
-default on , which saves one precious keystroke.
-
-It is possible to change the major mode leader key by defining the variable
-`dotspacemacs-major-mode-leader-key` in your `~/.spacemacs`. For example to
-setup the key on tabulation:
-
-```elisp
-(setq-default dotspacemacs-major-mode-leader-key "")
-```
-
-### Helm
-
-`Spacemacs` add `hjkl` navigation to `helm` buffers:
-
- Key Binding | Description
-------------------|------------------------------------------------------------
-CTRL+h | go to previous page
-CTRL+j | go to previous item
-CTRL+k | go to next item
-CTRL+l | go to next page
-
-### Python
-
-Writing python code with spacemacs is supported by python contribution. Please
-see [python contribution][python-contrib] documentation for detail.
-
-### JavaScript
-
-More featured JavaScript support is provided by the javascript
-contribution. Please see [javascript contribution][javascript-contrib]
-documentation for detail.
-
-### HTML and CSS
-
-HTML contribution provides support for editing HTML, CSS, Scss and Less
-files. Please see [html contribution][html-contrib] documentation for detail.
-
-# Emacs Server
-
-`Spacemacs` starts a server at launch. This server is killed whenever you close
-your Emacs windows.
-
-## Connecting to the Emacs server
-
-You can open a file in Emacs from the terminal using `emacsclient`. Use
-`emacsclient -c` to open the file in Emacs GUI. Use `emacsclient -t` to open
-the file in Emacs within the terminal.
-
-If you want your Linux/OS X system to use Emacs by default for any prompt, use
-`export EDITOR="emacsclient -c"` in your shell configuration.
-
-Note that if you're on OS X, you may have to refer to the emacsclient that comes
-with your GUI Emacs, e.g. `export
-EDITOR="/Applications/Emacs.app/Contents/MacOS/bin/emacsclient -c"`.
-
-Tip: Remember to use `:wq` or `C-x #` after you are done editing the file
-in Emacs.
-
-See [Emacs as a Server][] in the official Emacs manual for more details.
-
-## Keeping the server alive
-
-It is possible to keep the server alive when you close Emacs by setting the
-variable `dotspacemacs-persistent-server` to `t` in your `~./spacemacs`.
-
-```elisp
-(setq-default dotspacemacs-persistent-server t)
-```
-
-When this variable is set to `t`, the only way to quit Emacs _and_ kill the
-server is to use the following bindings:
-
- Key Binding | Description
--------------------|------------------------------------------------------------
-SPC q q | Quit Emacs and kill the server, prompt for changed buffers to save
-SPC q Q | Quit Emacs and kill the server, lose all unsaved changes.
-SPC q s | Save the buffers, quit Emacs and kill the server
-SPC q z | Kill the current frame
-
-## Troubleshoot
-
-### Loading fails
-
-If any errors happen during the loading the mode-line will turn red and the
-errors should appear inline in the startup buffer. Spacemacs should still be
-usable, if it is not the case then restart Emacs with `emacs --debug-init` and
-open a [Github issue][issues] with the backtrace.
-
-### I have no file ~/.spacemacs
-
-You have to manually copy the `~/.emacs.d/core/templates/.spacemacs.template`
-file to `~/.spacemacs`
-
-# Achievements
-
-## Issues
-
-Achievements | Account
------------------------------------------------------|------------------------
-[100th issue (PR)][100th-issue] | [danielwuz][]
-[200th issue (question)][200th-issue] | [justrajdeep][]
-[300th issue (PR)][300th-issue] | [danielwuz][]
-[400th issue (PR)][400th-issue] | [CestDiego][]
-[500th issue (PR)][500th-issue] | [bjarkevad][]
-[600th issue (PR)][600th-issue] | [bjarkevad][]
-[700th issue (enhancement)][700th-issue] | [jcpetkovich][]
-[800th issue (PR)][800th-issue] | [ryansroberts][]
-[900th issue (PR)][900th-issue] | [jcpetkovich][]
-[1000th issue (PR)][1000th-issue] | [tuhdo][]
-
-## Merged Pull Requests
-
-Achievements | Account
------------------------------------------------------|------------------------
-[100th pull request][100th-PR] | [bru][]
-[200th pull request][200th-PR] | [smt][]
-[300th pull request][300th-PR] | [BrianHicks][]
-[400th pull request][400th-PR] | [cpaulik][]
-[500th pull request][500th-PR] | [tuhdo][]
-[600th pull request][600th-PR] | [trishume][]
-
-## Stars, forks and watchers
-
-Achievements | Account
------------------------------------------------------|------------------------
-100th watcher | [adouzzy][]
-100th fork | [balajisivaraman][]
-200th fork | [alcol80][]
-300th fork | [mlopes][]
-100th star | [Jackneill][]
-200th star | [jb55][]
-400th star | [dbohdan][]
-600th star | [laat][]
-700th star | [kendall][]
-800th star | [urso][]
-900th star | [luisgerhorst][]
-1000th star! | [rashly][]
-
-## Specials
-
-Achievements | Account
------------------------------------------------------|------------------------
-[First contribution][1st-contrib] | [trishume][]
-[First contribution layer][1st-clayer] | [trishume][]
-[First blog article on Spacemacs][1st-article] | [Wolfy87][]
-[First contributed banner][1st-cbanner] | [chrisbarrett][]
-The Gunner (made 18 PRs in a row) | [ralesi][]
-The Saint (unlocked the holy-mode) | [trishume][]
-The Artist (made the spacemacs logo) | [nashamri][]
-The Meme Master (made the doge banner) | [chrisbarrett][]
-The Helm captain (see [here][tuhdo-tuto]) | [tuhdo][]
-
-# Thank you
-
-[Jokes aside](#using-configuration-layers), thank you Richard for this great
-piece of software.
-
-Thank you to all the contributors and the whole Emacs community from core
-developers to elisp hackers!
-
-[CONVENTIONS.md]: ./CONVENTIONS.md
-[evil]: https://gitorious.org/evil/pages/Home
-[evil-leader]: https://github.com/cofi/evil-leader
-[RSI]: http://en.wikipedia.org/wiki/Repetitive_strain_injury
-[vim-migration]: ./VIMUSERS.org
-[sacha_guide]: http://sachachua.com/blog/2013/05/how-to-learn-emacs-a-hand-drawn-one-pager-for-beginners/
-[use-package]: https://github.com/jwiegley/use-package
-[keychords]: http://www.emacswiki.org/emacs/KeyChord
-[centered-cursor]: http://www.emacswiki.org/emacs/centered-cursor-mode.el
-[ace-jump]: https://github.com/winterTTr/ace-jump-mode
-[ace-link]: https://github.com/abo-abo/ace-link
-[ace-window]: https://github.com/abo-abo/ace-window
-[helm-link]: https://github.com/emacs-helm/helm
-[helm-doc]: https://github.com/emacs-helm/helm/wiki
-[helm-ag]: https://github.com/syohex/emacs-helm-ag
-[popwin]: http://www.emacswiki.org/emacs/PopWin
-[golden-ratio]: https://github.com/roman/golden-ratio.el
-[solarized-theme]: https://github.com/bbatsov/solarized-emacs
-[powerline]: https://github.com/milkypostman/powerline
-[font-spec]: http://www.gnu.org/software/emacs/manual/html_node/elisp/Low_002dLevel-Font.html
-[diminish]: http://www.emacswiki.org/emacs/DiminishedModes
-[auto-complete]: https://github.com/auto-complete
-[auto-highlight]: https://github.com/emacsmirror/auto-highlight-symbol
-[e-project]: https://github.com/jrockway/eproject
-[projectile]: https://github.com/bbatsov/projectile
-[sp]: https://github.com/Fuco1/smartparens
-[ag]: https://github.com/ggreer/the_silver_searcher
-[pt]: https://github.com/monochromegane/the_platinum_searcher
-[tcl]: https://core.tcl.tk/tcllib/doc/trunk/embedded/www/tcllib/files/apps/pt.html
-[flycheck]: https://github.com/flycheck
-[yasnippet]: https://github.com/capitaomorte/yasnippet
-[expand-region]: https://github.com/magnars/expand-region.el
-[multiple-cursors]: https://github.com/magnars/multiple-cursors.el
-[hswoop]: https://github.com/ShingoFukuyama/helm-swoop
-[hcss]: https://github.com/ShingoFukuyama/helm-css-scss
-[hyas]: https://github.com/emacs-helm/helm-c-yasnippet
-[hthemes]: https://github.com/syohex/emacs-helm-themes
-[projectile]: https://github.com/bbatsov/projectile
-[hdescbinds]: https://github.com/emacs-helm/helm-descbinds
-[iedit]: https://github.com/tsdh/iedit
-[evil-iedit-state]: https://github.com/syl20bnr/evil-iedit-state
-[evil-indent-textobject]: https://github.com/cofi/evil-indent-textobject
-[evil-visualstar]: https://github.com/bling/evil-visualstar
-[evil-exchange]: https://github.com/Dewdrops/evil-exchange
-[evil-surround]: https://github.com/timcharper/evil-surround
-[camelcasemotion.vim]: http://www.vim.org/scripts/script.php?script_id=1905
-[vim-exchange]: https://github.com/tommcdo/vim-exchange
-[vim-surround]: https://github.com/tpope/vim-surround
-[evil-nerd-commenter]: https://github.com/redguardtoo/evil-nerd-commenter
-[nerdcommenter]: https://github.com/scrooloose/nerdcommenter
-[evil-matchit]: https://github.com/redguardtoo/evil-matchit
-[matchit.vim]: http://www.vim.org/scripts/script.php?script_id=39
-[source code pro]: https://github.com/adobe-fonts/source-code-pro
-[evil-escape]: https://github.com/syl20bnr/evil-escape
-[evil-args]: https://github.com/wcsmith/evil-args
-[evil-jumper]: https://github.com/bling/evil-jumper
-[evil-numbers]: https://github.com/cofi/evil-numbers
-[evil-lisp-state]: https://github.com/syl20bnr/evil-lisp-state
-[Vim's Unite]: https://github.com/Shougo/unite.vim
-[git-gutter]: https://github.com/syohex/emacs-git-gutter-fringe
-[nose]: https://github.com/nose-devs/nose/
-[nose.el]: https://github.com/syl20bnr/nose.el
-[pylookup]: https://github.com/tsgates/pylookup
-[jedi]: https://github.com/tkf/emacs-jedi
-[ess-R-object-popup]: https://github.com/myuhe/ess-R-object-popup.el
-[ess-R-data-view]: https://github.com/myuhe/ess-R-data-view.el
-[leuven-theme]: https://github.com/fniessen/emacs-leuven-theme
-[monokai-theme]: https://github.com/oneKelvinSmith/monokai-emacs
-[zenburn-theme]: https://github.com/bbatsov/zenburn-emacs
-[ido-vertical-mode]: https://github.com/gempesaw/ido-vertical-mode.el
-[issues]: https://github.com/syl20bnr/spacemacs/issues
-[vundle]: https://github.com/gmarik/Vundle.vim
-[anzu]: https://github.com/syohex/emacs-anzu
-[javascript-contrib]: ../contrib/!lang/javascript
-[themes-megapack]: ../contrib/themes-megapack
-[git layer]: ../contrib/!tools/git
-[python-contrib]: ../contrib/!lang/python
-[html-contrib]: ../contrib/lang/html
-[guide-key]: https://github.com/kai2nenobu/guide-key
-[guide-key-tip]: https://github.com/aki2o/guide-key-tip
-[gitter]: https://gitter.im/syl20bnr/spacemacs
-[CONTRIBUTE.md]: ./CONTRIBUTE.md
-[special buffer howto]: ./HOWTOs.md#change-special-buffer-rules
-[neotree]: https://github.com/jaypei/emacs-neotree
-[nerdtree]: https://github.com/scrooloose/nerdtree
-[anaconda-mode]: https://github.com/proofit404/anaconda-mode
-[1st-contrib]: https://github.com/syl20bnr/spacemacs/pull/19
-[1st-clayer]: https://github.com/syl20bnr/spacemacs/commit/e802027d75d0c0aed55539b0da2dfa0df94dfd39
-[1st-article]: http://oli.me.uk/2014/11/06/spacemacs-emacs-vim/
-[1st-cbanner]: https://github.com/syl20bnr/spacemacs/commit/7b44a56263049482ed540ed6815a295633ffe9d1
-[100th-issue]: https://github.com/syl20bnr/spacemacs/pull/100
-[200th-issue]: https://github.com/syl20bnr/spacemacs/issues/200
-[300th-issue]: https://github.com/syl20bnr/spacemacs/pull/300
-[400th-issue]: https://github.com/syl20bnr/spacemacs/pull/400
-[500th-issue]: https://github.com/syl20bnr/spacemacs/pull/500
-[600th-issue]: https://github.com/syl20bnr/spacemacs/pull/600
-[700th-issue]: https://github.com/syl20bnr/spacemacs/pull/700
-[800th-issue]: https://github.com/syl20bnr/spacemacs/pull/800
-[900th-issue]: https://github.com/syl20bnr/spacemacs/pull/900
-[1000th-issue]: https://github.com/syl20bnr/spacemacs/pull/1000
-[100th-PR]: https://github.com/syl20bnr/spacemacs/pull/228
-[200th-PR]: https://github.com/syl20bnr/spacemacs/pull/418
-[300th-PR]: https://github.com/syl20bnr/spacemacs/pull/617
-[400th-PR]: https://github.com/syl20bnr/spacemacs/pull/806
-[500th-PR]: https://github.com/syl20bnr/spacemacs/pull/993
-[600th-PR]: https://github.com/syl20bnr/spacemacs/pull/1205
-[trishume]:https://github.com/trishume
-[nashamri]: https://github.com/nashamri
-[Wolfy87]:https://github.com/Wolfy87
-[danielwuz]:https://github.com/danielwuz
-[CestDiego]:https://github.com/CestDiego
-[bjarkevad]:https://github.com/bjarkevad
-[jcpetkovich]:https://github.com/jcpetkovich
-[tuhdo]:https://github.com/tuhdo
-[tuhdo-tuto]:http://tuhdo.github.io/helm-intro.html
-[BrianHicks]:https://github.com/BrianHicks
-[cpaulik]: https://github.com/cpaulik
-[chrisbarrett]:https://github.com/chrisbarrett
-[justrajdeep]:https://github.com/justrajdeep
-[dbohdan]:https://github.com/dbohdan
-[laat]:https://github.com/laat
-[ryansroberts]:https://github.com/laat
-[kendall]:https://github.com/kendall
-[urso]:https://github.com/urso
-[luisgerhorst]:https://github.com/luisgerhorst
-[rashly]:https://github.com/rashly
-[bru]:https://github.com/bru
-[smt]:https://github.com/smt
-[ralesi]:https://github.com/ralesi
-[alcol80]:https://github.com/alcol80
-[adouzzy]:https://github.com/adouzzy
-[mlopes]:https://github.com/mlopes
-[balajisivaraman]:https://github.com/balajisivaraman
-[Jackneill]:https://github.com/Jackneill
-[jb55]:https://github.com/jb55
-[use-package]: https://github.com/jwiegley/use-package
-[Paradox]: https://github.com/Bruce-Connor/paradox
-[fancy-battery]: https://github.com/lunaryorn/fancy-battery.el
-[MacType]: https://code.google.com/p/mactype/
-[Emacs as a Server]: https://www.gnu.org/software/emacs/manual/html_node/emacs/Emacs-Server.html
diff --git a/doc/DOCUMENTATION.org b/doc/DOCUMENTATION.org
new file mode 100644
index 000000000..de34097e9
--- /dev/null
+++ b/doc/DOCUMENTATION.org
@@ -0,0 +1,2481 @@
+* Table of Contents :TOC@4:
+ - [[#spacemacs-documentation][Spacemacs Documentation]]
+ - [[#core-pillars][Core Pillars]]
+ - [[#mnemonic][Mnemonic]]
+ - [[#discoverability][Discoverability]]
+ - [[#consistency][Consistency]]
+ - [[#crowd-configured][Crowd-Configured]]
+ - [[#goals][Goals]]
+ - [[#screenshots][Screenshots]]
+ - [[#who-can-benefit-from-this][Who can benefit from this?]]
+ - [[#update-and-rollback][Update and Rollback]]
+ - [[#update-spacemacs-repository][Update Spacemacs repository]]
+ - [[#update-packages][Update packages]]
+ - [[#configuration-layers][Configuration layers]]
+ - [[#structure][Structure]]
+ - [[#extensions-and-packages][Extensions and Packages]]
+ - [[#within-a-layer][Within a layer]]
+ - [[#declaration][Declaration]]
+ - [[#initialization][Initialization]]
+ - [[#exclusion][Exclusion]]
+ - [[#without-a-layer][Without a layer]]
+ - [[#packages-synchronization-vundle-like-feature][Packages synchronization (Vundle like feature)]]
+ - [[#types-of-configuration-layers][Types of configuration layers]]
+ - [[#submitting-a-configuration-layer-upstream][Submitting a configuration layer upstream]]
+ - [[#example-themes-megapack-example][Example: Themes Megapack example]]
+ - [[#managing-private-configuration-layers][Managing private configuration layers]]
+ - [[#using-the-private-directory][Using the private directory]]
+ - [[#using-an-external-git-repository][Using an external Git repository]]
+ - [[#using-a-personal-branch][Using a personal branch]]
+ - [[#dotfile-configuration][Dotfile Configuration]]
+ - [[#installation][Installation]]
+ - [[#synchronization-of-dotfile-changes][Synchronization of dotfile changes]]
+ - [[#content][Content]]
+ - [[#using-configuration-layers][Using configuration layers]]
+ - [[#setting-configuration-layers-variables][Setting configuration layers variables]]
+ - [[#excluding-packages][Excluding packages]]
+ - [[#hooks][Hooks]]
+ - [[#custom-variables][Custom variables]]
+ - [[#main-principles][Main principles]]
+ - [[#evil][Evil]]
+ - [[#holy][Holy]]
+ - [[#states][States]]
+ - [[#evil-leader][Evil leader]]
+ - [[#universal-argument][Universal argument]]
+ - [[#micro-states][Micro-states]]
+ - [[#differences-between-vim-evil-and-spacemacs][Differences between Vim, Evil and Spacemacs]]
+ - [[#the-vim-surround-case][The vim-surround case]]
+ - [[#evil-plugins][Evil plugins]]
+ - [[#spacemacs-ui][Spacemacs UI]]
+ - [[#graphical-ui][Graphical UI]]
+ - [[#color-themes][Color themes]]
+ - [[#font][Font]]
+ - [[#graphical-ui-toggles][Graphical UI Toggles]]
+ - [[#mouse-usage][Mouse usage]]
+ - [[#mode-line][Mode-line]]
+ - [[#flycheck-integration][Flycheck integration]]
+ - [[#anzu-integration][Anzu integration]]
+ - [[#battery-status-integration][Battery status integration]]
+ - [[#powerline-separators][Powerline separators]]
+ - [[#minor-modes][Minor Modes]]
+ - [[#commands][Commands]]
+ - [[#vim-key-bindings][Vim key bindings]]
+ - [[#escaping][Escaping]]
+ - [[#executing-vim-and-emacs-exm-x-commands][Executing Vim and Emacs ex/M-x commands]]
+ - [[#leader-key][Leader key]]
+ - [[#reserved-prefix-command-for-user][Reserved prefix command for user]]
+ - [[#helm][Helm]]
+ - [[#c-z-and-tab-switch][C-z and Tab switch]]
+ - [[#helm-micro-state][Helm micro-state]]
+ - [[#discovering][Discovering]]
+ - [[#key-bindings][Key bindings]]
+ - [[#guide-key][Guide-key]]
+ - [[#helm-describe-key-bindings][Helm describe key bindings]]
+ - [[#getting-help][Getting help]]
+ - [[#available-layers][Available layers]]
+ - [[#available-packages-in-spacemacs][Available packages in Spacemacs]]
+ - [[#new-packages-from-elpa-repositories][New packages from ELPA repositories]]
+ - [[#toggles][Toggles]]
+ - [[#navigating][Navigating]]
+ - [[#pointcursor][Point/Cursor]]
+ - [[#smooth-scrolling][Smooth scrolling]]
+ - [[#vim-motions-with-ace-jump-mode][Vim motions with ace-jump mode]]
+ - [[#ace-link-mode][ace-link mode]]
+ - [[#window-manipulation][Window manipulation]]
+ - [[#window-manipulation-key-bindings][Window manipulation key bindings]]
+ - [[#window-manipulation-micro-state][Window manipulation micro-state]]
+ - [[#golden-ratio][Golden ratio]]
+ - [[#buffers-and-files][Buffers and Files]]
+ - [[#buffers-manipulation-key-bindings][Buffers manipulation key bindings]]
+ - [[#buffers-manipulation-manipulation-micro-state][Buffers manipulation manipulation micro-state]]
+ - [[#special-buffers][Special Buffers]]
+ - [[#files-manipulations-key-bindings][Files manipulations key bindings]]
+ - [[#emacs-and-spacemacs-files][Emacs and Spacemacs files]]
+ - [[#ido][Ido]]
+ - [[#ido-micro-state][Ido micro-state]]
+ - [[#neotree-file-tree][NeoTree file tree]]
+ - [[#neotree-navigation][NeoTree navigation]]
+ - [[#opening-files-with-neotree][Opening files with NeoTree]]
+ - [[#other-neotree-key-bindings][Other NeoTree key bindings]]
+ - [[#neotree-mode-line][NeoTree mode-line]]
+ - [[#bookmarks][Bookmarks]]
+ - [[#docview-mode][DocView mode]]
+ - [[#searching][Searching]]
+ - [[#with-an-external-tool][With an external tool]]
+ - [[#searching-in-an-arbitrary-directory][Searching in an arbitrary directory]]
+ - [[#searching-in-a-project][Searching in a project]]
+ - [[#searching-the-web][Searching the web]]
+ - [[#persistent-highlighting][Persistent highlighting]]
+ - [[#stacking-highlights][Stacking highlights]]
+ - [[#highlight-current-symbol][Highlight current symbol]]
+ - [[#visual-star][Visual Star]]
+ - [[#listing-symbols-by-semantic][Listing symbols by semantic]]
+ - [[#helm-swoop][Helm-swoop]]
+ - [[#editing][Editing]]
+ - [[#paste-text][Paste text]]
+ - [[#paste-micro-state][Paste Micro-state]]
+ - [[#auto-indent-pasted-text][Auto-indent pasted text]]
+ - [[#text-manipulation-commands][Text manipulation commands]]
+ - [[#smartparens-strict-mode][Smartparens Strict mode]]
+ - [[#zooming][Zooming]]
+ - [[#text][Text]]
+ - [[#frame][Frame]]
+ - [[#increasedecrease-numbers][Increase/Decrease numbers]]
+ - [[#spell-checking][Spell checking]]
+ - [[#region-selection][Region selection]]
+ - [[#expand-region][Expand-region]]
+ - [[#indent-text-object][Indent text object]]
+ - [[#region-narrowing][Region narrowing]]
+ - [[#line-formatting][Line formatting]]
+ - [[#replacing-text-with-iedit][Replacing text with iedit]]
+ - [[#iedit-states-key-bindings][iedit states key bindings]]
+ - [[#examples][Examples]]
+ - [[#replacing-text-in-several-files][Replacing text in several files]]
+ - [[#commenting][Commenting]]
+ - [[#deleting-files][Deleting files]]
+ - [[#editing-lisp-code][Editing Lisp code]]
+ - [[#lisp-key-bindings][Lisp Key Bindings]]
+ - [[#managing-projects][Managing projects]]
+ - [[#registers][Registers]]
+ - [[#errors-handling][Errors handling]]
+ - [[#compiling][Compiling]]
+ - [[#modes][Modes]]
+ - [[#major-mode-leader-key][Major Mode leader key]]
+ - [[#helm][Helm]]
+ - [[#python][Python]]
+ - [[#javascript][JavaScript]]
+ - [[#html-and-css][HTML and CSS]]
+ - [[#emacs-server][Emacs Server]]
+ - [[#connecting-to-the-emacs-server][Connecting to the Emacs server]]
+ - [[#keeping-the-server-alive][Keeping the server alive]]
+ - [[#troubleshoot][Troubleshoot]]
+ - [[#loading-fails][Loading fails]]
+ - [[#i-have-no-file-spacemacs][I have no file ~/.spacemacs]]
+ - [[#achievements][Achievements]]
+ - [[#issues][Issues]]
+ - [[#merged-pull-requests][Merged Pull Requests]]
+ - [[#stars-forks-and-watchers][Stars, forks and watchers]]
+ - [[#specials][Specials]]
+ - [[#thank-you][Thank you]]
+
+* Spacemacs Documentation
+
+* Core Pillars
+
+Four core pillars: Mnemonic, Discoverability, Consistency, "Crowd-Configured".
+
+If any of these core pillars is violated open an issue and we'll fix it.
+
+** Mnemonic
+
+=Spacemacs= organizes key bindings by mnemonic namespaces as much as possible. If
+you are looking for commands to operate on your buffer, they are right under ~SPC
+b~, if you want to operate on your project, then it is ~SPC p~, etc...
+
+** Discoverability
+
+=Spacemacs= comes with a dedicated major mode =spacemacs-mode=. Its goal is to give
+useful feedbacks and easily perform maintenance tasks.
+
+It also comes with dedicated [[https://github.com/emacs-helm/helm][helm]] sources to quickly find layers, packages and
+more.
+
+[[https://github.com/kai2nenobu/guide-key][guide-key]] is enabled by default, it will display all the available key bindings
+in a dedicated popup buffer.
+
+** Consistency
+
+Similar functionalities should have the same key binding no matter which major
+is currently active. For instance if you are looking for the definition of a
+function, the binding is ~SPC m g g~, =m= for =major mode= and =g g= for =go to thing at
+point=. No matter what is the major mode it is the same binding to perform this
+action.
+
+This is also true for the documentation, each configuration layer comes with an
+associated =README.org= file with the same base layout.
+
+The consistency core pillar is supported by a convention file: [[file:CONVENTIONS.org][CONVENTIONS.org]]
+
+** Crowd-Configured
+
+By defining an very light structure called =configuration layer= which is easy to
+understand, =Spacemacs= makes it easy to contribute additional support.
+
+The conventions in [[file:CONVENTIONS.org][CONVENTIONS.org]] make it easy to get the spacemacs way and
+keep consistency even if there are a lot of contributions.
+
+=Crowd-configuration= is the most powerful pillar of =Spacemacs=. Anybody can submit
+upstream improvements to configuration layers or a whole new one. Any user can
+easily and directly use this layer by adding it to a list in a dotfile. It is
+even possible to exclude /any/ unwanted packages.
+
+
+* Goals
+
+- *Bring the power of modal editing* to the powerful Emacs editing platform.
+
+- Integrate nicely with =Evil= states (=Vim= modes): =Spacemacs= tries to *keep
+ your fingers on the home row* as much as possible, no matter the mode you are
+ in.
+
+- *Crowd-configured*: Contribute easily your improvements and new configuration
+ layers.
+
+- *Minimalistic and nice graphical UI*, keep your available screen space for
+ what matters: your text files.
+
+- *Mnemonic and consistent key bindings* which should be easier to learn and
+ remember and be the same in all major modes.
+
+- *Fast boot time*, everything is lazy-loaded.
+
+- *Lower the risk of RSI* by heavily using the space bar instead of modifiers.
+
+- Hopefully, if it's not already the case:
+
+ Ɛ>Ɛ>Ɛ> *make you love modal editing!* <3<3<3
+
+* Screenshots
+
+/Startup/ [[file:img/spacemacs-startup.png]]
+
+/Python/ [[file:img/spacemacs-python.png]]
+
+/Terminal (urxvt)/ [[file:img/spacemacs-urxvt.png]]
+
+/Note: Even though screenshots are updated frequently, =Spacemacs= is evolving
+quickly and the screenshots may not reflect exactly the current state of the
+project./
+
+* Who can benefit from this?
+
+=Spacemacs= is first intended to be used by *Vim users* who want to go to the
+next level by using Emacs. There is a [[./VIMUSERS.org][guide]] for these users to supplement the
+documentation.
+
+It is also a good fit for people wanting to *lower the [[http://en.wikipedia.org/wiki/Repetitive_strain_injury][risk of RSI]]* induced by
+the default Emacs key bindings (this is an assumption, there is no official
+studies to prove this).
+
+Emacs users wanting to learn *a different way to edit files* or wanting to learn
+Vim key bindings.
+
+As a side note, if you are a programmer and you don't know Vim key bindings yet,
+I deeply recommend you to learn the basics as recommended in [[http://sachachua.com/blog/2013/05/how-to-learn-emacs-a-hand-drawn-one-pager-for-beginners/][Sacha Chua's
+one-page guide]] about how to learn Emacs.
+
+* Update and Rollback
+
+For now it is still needed to update the =Spacemacs= repository manually.
+
+** Update Spacemacs repository
+
+Close Emacs and update the git repository:
+
+#+begin_src sh
+ $ git pull --rebase git submodule sync; git submodule update
+#+end_src
+
+*Note* It is recommended to update the packages first, see next session.
+
+** Update packages
+
+To update =Spacemacs= press RET (enter) or click on the link =[Update]= in the
+startup page under the banner then restart Emacs.
+
+If anything goes wrong you should be able to rollback the update by pressing
+~RET~ or clicking on the =[Rollback]= link next to the =[Update]= link and
+choose a rollback slot (sorted by date).
+
+* Configuration layers
+
+** Structure
+
+Configuration is organized in layers. Each layer has the following structure:
+
+#+BEGIN_EXAMPLE
+ [layer_name]
+ |__ [extensions]
+ | |__ [mode 1]
+ | | ...
+ | |__ [mode n]
+ |__ config.el
+ |__ extensions.el
+ |__ funcs.el
+ |__ keybindings.el
+ |__ packages.el
+
+ [] = directory
+#+END_EXAMPLE
+
+Where:
+
+ | File | Usage |
+ |----------------+----------------------------------------------------------------------|
+ | config.el | Emacs built-in configuration or mandatory configuration |
+ | extensions.el | The list of extensions to load and the functions to initialize them |
+ | funcs.el | Various functions and macros (often used in keybindings.el) |
+ | keybindings.el | Emacs built-in key bindings or mandatory key bindings |
+ | packages.el | The list of packages to install and the functions to initialize them |
+
+=Packages= are =ELPA= packages which can be installed from an =ELPA= compliant
+repository, and =Extensions= are generally elisp code from git submodules.
+
+** Extensions and Packages
+
+*** Within a layer
+
+**** Declaration
+
+=Extensions= and =Packages= are declared in variables =-pre-extensions=,
+=-post-extensions= and =-packages= where == is the layer
+name. =Pre-Extensions= are loaded before =Packages= and =Post-Extensions= are
+loaded after =Packages=.
+
+They are processed in alphabetical order so sometimes you'll have to use some
+=eval-after-load= black magic.
+
+Example:
+
+#+begin_src emacs-lisp
+ (setq -packages '(package1 package2 ...)
+#+end_src
+
+**** Initialization
+
+To initialize an extension or a package =xxx=, define a function with this
+format in =extensions.el= or =packages.el=:
+
+#+begin_src emacs-lisp
+ (defun /init-xxx () ...body )
+#+end_src
+
+It is common to define the body with the [[https://github.com/jwiegley/use-package][use-package]] macro.
+
+**** Exclusion
+
+It is possible to exclude some packages from =Spacemacs= in a per layer basis.
+This is useful when a configuration layer aims to replace a stock package
+declared in the =Spacemacs= layer.
+
+To do so add the package names to exclude to the variable
+=-excluded-packages=.
+
+Example:
+
+#+begin_src emacs-lisp
+ (setq -excluded-packages '(package1 package2 ...)
+#+end_src
+
+*** Without a layer
+
+Sometimes a layer can be an unnecessary overhead, this is the case if you just
+want to install a package without any configuration associated to it. A good
+example is some niche language where you are only interested syntax
+highlighting.
+
+You can install such packages by adding them to the variable
+=dotspacemacs-additional-packages= in your dotfile.
+
+If you want to add some configuration for them then consider to create a layer,
+or just put the configuration in the =dotspacemacs/config= function.
+
+Example to install =llvm-mode= and =dts-mode=:
+
+#+begin_src emacs-lisp
+ (setq dotspacemacs-additional-packages '(llvm-mode dts-mode)
+#+end_src
+
+** Packages synchronization (Vundle like feature)
+
+=Spacemacs= features a synchronization engine for the ELPA packages. It means
+that =Spacemacs= will auto-install the new packages in =-packages= lists
+/and/ auto-delete orphan packages in your =elpa= directory.
+
+It effectively makes =Spacemacs= behave like [[https://github.com/gmarik/Vundle.vim][Vundle]].
+
+** Types of configuration layers
+
+There are three types of configuration layers:
+ - core (this is the =Spacemacs= layer)
+ - private (in the =private= directory, they are ignored by Git)
+ - contrib (in the =contrib= directory, those layers are contributions shared
+ by the community and merged upstream).
+
+** Submitting a configuration layer upstream
+
+If you decide to provide a =contrib= configuration layer, please check the
+contribution guidelines in [[./CONTRIBUTE.org][CONTRIBUTE.org]].
+
+** Example: Themes Megapack example
+
+This is a simple =contrib= configuration layer listing a bunch of themes, you
+can find it [[../contrib/themes-megapack][here]].
+
+To install it, just add =themes-megapack= to your =~/.spacemacs= like so:
+
+#+begin_src emacs-lisp
+ (setq-default dotspacemacs-configuration-layers '(themes-megapack))
+#+end_src
+
+You have now installed around 100 themes you are free to try with ~SPC T h~
+(helm-themes).
+
+** Managing private configuration layers
+
+=Spacemacs= configuration system is flexible enough to let you manage your
+private layers in different ways.
+
+*** Using the private directory
+
+Everything in the private directory is ignored by Git so it is a good place to
+store private layers. There is a huge drawback to this approach though: /your
+layers are not source controlled/.
+
+*** Using an external Git repository
+
+This is the recommended way to manage your private layers.
+
+The best approach is to store all your private layers into an external Git
+repository. It is especially a good practice to store them in your =dotfiles=
+repository if you have one. Put also your =~/.spacemacs= file in it.
+
+Then you are free to symlink your layers into =~/emacs.d/private= /or/ let them
+anywhere you want and reference the parent directory in the variable
+=dotspacemacs-configuration-layer-path= of your =~/.spacemacs=.
+
+Note that you could also have a dedicated repository for all your private layers
+and then directly clone this repository in =~/.emacs.d/private=.
+
+*** Using a personal branch
+
+The final main way to manage your private layers is to push them in a personal
+branch that you keep up to date with upstream =master= or =develop=.
+
+* Dotfile Configuration
+
+User configuration can be stored in your =~/.spacemacs= file.
+
+** Installation
+
+=~/.spacemacs= is an optional file. If you want to use it you have to copy it
+manually from the template file =~/.emacs.d/core/templates/.spacemacs.template=
+
+#+begin_src sh
+ $ cp ~/.emacs.d/core/templates/.spacemacs.template ~/.spacemacs
+#+end_src
+
+** Synchronization of dotfile changes
+
+To apply the modifications made in =~/.spacemacs= press ~SPC f e R~. It will
+re-execute the =Spacemacs= initialization process.
+
+*Note:* A synchronization re-execute the functions =dotspacemacs/init= and
+=dotspacemacs/config=. Depending on the content of this functions you may
+encounter some unwanted side effects. For instance if you use a toggle in
+=dotspacemac/config= to enable some behavior, this behavior will be turned off
+whenever the dotfile is re-synchronize. To avoid these side-effects it is
+recommended to use =setq= expressions instead of toggle functions. It is also
+possible to /skip/ the execution of =dotspacemacs/config= with the universal
+argument (~SPC u SPC f e R~).
+
+** Content
+
+*** Using configuration layers
+
+To use a configuration layer, add it to the =dotspacemacs-configuration-layers=
+variable of your =~/.spacemacs=.
+
+For instance to add the configuration layer of [[#thank-you][RMS]]:
+
+#+begin_src emacs-lisp
+ (setq-default dotspacemacs-configuration-layers '(rms))
+#+end_src
+
+If this layer does not exist you can still try another one in [[../contrib][the =contrib=
+directory]].
+
+Configuration layers are expected to be stored in =~/.emacs.d/private= or
+=~/.emacs.d/contrib=. But you are free to keep them somewhere else by declaring
+additional paths where =Spacemacs= can look for configuration layers. This is
+done by setting the list =dotspacemacs-configuration-layer-path= in your
+=~/.spacemacs=:
+
+#+begin_src emacs-lisp
+ (setq-default dotspacemacs-configuration-layer-path '("~/.myconfig/"))
+#+end_src
+
+*** Setting configuration layers variables
+
+Some configuration layers have configuration variables to enable specific
+support. For instance the [[../contrib/!tools/git][git layer]] has several configuration variables, they
+can be set directly in the =dotspacemacs-configuration-layers= like this:
+
+#+begin_src emacs-lisp
+ (defun dotspacemacs/layers ()
+ ;; List of configuration layers to load.
+ (setq-default dotspacemacs-configuration-layers '(auto-completion
+ (git :variables
+ git-magit-status-fullscreen t)
+ smex)))
+#+end_src
+
+*** Excluding packages
+
+You can exclude packages you don't want to install with the variable
+=dotspacemacs-excluded-packages=, this variable can exclude both packages and
+extensions (see [[#configuration-layers][Configuration layers]] for more info on packages and extensions).
+
+For instance to disable the =rainbow-delimiters= package:
+
+#+begin_src emacs-lisp
+ (setq-default dotspacemacs-excluded-packages '(rainbow-delimiters))
+#+end_src
+
+When you exclude a package, =Spacemacs= will automatically delete it for you the
+next time you launch Emacs. All the orphan dependencies are as well delete
+automatically.
+
+*** Hooks
+
+Two special functions of the =~/.spacemacs= file can be used to perform
+configuration at the beginning and end of =Spacemacs= loading process.
+
+ - =dotspacemacs/init= is triggered at the very beginning of =Spacemacs=
+ loading.
+ - =dotspacemacs/config= is triggered at the very end of =Spacemacs= loading.
+
+*** Custom variables
+
+Custom variables configuration from =M-x customize-group= which are
+automatically saved by Emacs are stored at the end of your =~/.spacemacs= file.
+
+* Main principles
+
+** Evil
+
+=Spacemacs= uses the [[https://gitorious.org/evil/pages/Home][evil]] mode package to emulate Vim key bindings. It is a very
+complete emulation, maybe the most advanced. In fact, Evil is much more than
+just a Vim emulation. It has more states than Vim for instance.
+
+** Holy
+
+Thanks to the new holy-mode Spacemacs can now be used by Vim users or Emacs
+users by setting the =dotspacemacs-editing-style= variable to ='vim= or ='emacs=
+in the dotfile. In Emacs style the leader is available as ~M-m~. It is possible
+to dynamically switch between evil and holy modes using ~SPC P tab~.
+
+*** States
+
+=Spacemacs= has 9 states:
+
+| State | Color | Description |
+|--------------+-------------+------------------------------------------------------------------------------------------------------------|
+| normal | orange | like the =normal mode of Vim=, used to execute and combine commands |
+| insert | green | like the =insert mode of Vim=, used to actually insert text |
+| visual | gray | like the =visual mode of Vim=, used to make text selection |
+| motion | purple | exclusive to =Evil=, used to navigate read only buffers |
+| emacs | blue | exclusive to =Evil=, using this state is like using a regular Emacs without Vim |
+| evilified | light brown | exclusive to =Spacemacs=, this is an =emacs state= modified to bring Vim navigation, selection and search. |
+| lisp | pink | exclusive to =Spacemacs=, used to navigate Lisp code and modify it (more [[#editing-lisp-code][info]]) |
+| iedit | red | exclusive to =Spacemacs=, used to navigate between multiple regions of text using =iedit= (more [[#replacing-text-with-iedit][info]]) |
+| iedit-insert | red | exclusive to =Spacemacs=, used to replace multiple regions of text using =iedit= (more [[#replacing-text-with-iedit][info]]) |
+
+Note: Technically speaking there are also the =operator= and =replace= evil
+states.
+
+** Evil leader
+
+=Spacemacs= heavily uses the [[https://github.com/cofi/evil-leader][evil-leader]] mode which brings the Vim leader key to
+the Emacs world.
+
+This leader key is commonly set to ~,~ by Vim users, in =Spacemacs= the leader
+key is set on ~SPC~ (space bar, hence the name =spacemacs=). This key is the
+most accessible key on a keyboard and it is pressed with the thumb which is a
+good choice to lower the risk of [[http://en.wikipedia.org/wiki/Repetitive_strain_injury][RSI]].
+
+So with =Spacemacs= there is no need to remap your keyboard modifiers to attempt
+to reduce the risk of RSI, every command can be executed very easily while you
+are in =normal= mode by pressing the ~SPC~ leader key, here are a few examples:
+
+- Save a buffer: ~SPC f s~
+- Save all opened buffers: ~SPC f S~
+- Open (switch) to a buffer with =helm=: ~SPC b b~
+
+** Universal argument
+
+The universal argument ~C-u~ is an important command in Emacs but it is also a
+very handy Vim key binding to scroll up.
+
+=Spacemacs= binds ~C-u~ to =scroll-up= and change the universal argument binding
+to ~SPC u~.
+
+** Micro-states
+
+=Spacemacs= defines a wide variety of =micro-states= (temporary overlay maps)
+where it makes sense. This prevents one from doing repetitive and tedious
+presses on the ~SPC~ key.
+
+When a =micro-state= is active, a documentation is displayed in the minibuffer.
+Additional information may as well be displayed in the minibuffer.
+
+[[#auto-highlight-and-edition-of-symbols][Auto-highlight-symbol micro-state]]:
+[[file:img/spacemacs-ahs-micro-state.png]]
+
+[[#change-font-size][Text scale micro-state]]:
+[[file:img/spacemacs-scale-micro-state.png]]
+
+* Differences between Vim, Evil and Spacemacs
+
+- The ~,~ key does "repeat last ~f~, ~t~, ~F~, or ~T~ command in
+ opposite direction in =Vim=, but in =Spacemacs= it is the major mode specific
+ leader key by default (which can be set on another key binding in the
+ dotfile).
+
+Send a PR to add the differences you found in this section.
+
+** The vim-surround case
+
+There is one obvious visible difference though. It is not between =Evil= and
+=Vim= but between =Spacemacs= and [[https://github.com/tpope/vim-surround][vim-surround]]: the =surround= command is on ~S~
+in =vim-surround= whereas it is on ~s~ in =Spacemacs=.
+
+This is something that can surprise some Vim users so let me explain why this is
+the case:
+ - ~s~ and ~c~ do the same thing in =visual state=,
+ - ~s~ is only useful to delete /one/ character and add more than one character
+ which is a /very/ narrow use case
+ - ~c~ accept motions and can do everything ~s~ can do in =normal state=
+ - this is also true for ~r~ but ~r~ is more useful because it stays in =normal state=
+ - =surround= command is just a more powerful command than ~s~.
+
+If you are not convinced, then here is the snippet to revert back to the default
+=Vim + vim-surround= setup (add it to your =dotspacemacs/config= function or
+your =~/.spacemacs=):
+
+#+begin_src emacs-lisp
+ (evil-define-key 'visual evil-surround-mode-map "s" 'evil-substitute)
+ (evil-define-key 'visual evil-surround-mode-map "S" 'evil-surround-region)
+#+end_src
+
+* Evil plugins
+
+=Spacemacs= ships with the following evil plugins:
+
+ | Mode | Description |
+ |-------------------------------+----------------------------------------------------------|
+ | [[https://github.com/cofi/evil-leader][evil-leader]] | vim leader that bring a new layer of keys in normal mode |
+ | [[https://github.com/cofi/evil-indent-textobject][evil-indent-textobject]] | add text object based on indentation level |
+ | [[https://github.com/bling/evil-visualstar][evil-visualstar]] | search for current selection with ~*~ |
+ | [[https://github.com/Dewdrops/evil-exchange][evil-exchange]] | port of [[https://github.com/tommcdo/vim-exchange][vim-exchange]] |
+ | [[https://github.com/timcharper/evil-surround][evil-surround]] | port of [[https://github.com/tpope/vim-surround][vim-surround]] |
+ | [[https://github.com/redguardtoo/evil-matchit][evil-matchit]] | port of [[http://www.vim.org/scripts/script.php?script_id=39][matchit.vim]] |
+ | [[https://github.com/redguardtoo/evil-nerd-commenter][evil-nerd-commenter]] | port of [[https://github.com/scrooloose/nerdcommenter][nerdcommenter]] |
+ | [[https://github.com/juanjux/evil-search-highlight-persist][evil-search-highlight-persist]] | emulation of hlsearch behavior |
+ | [[https://github.com/cofi/evil-numbers][evil-numbers]] | like ~C-a~ and ~C-x~ in vim |
+ | [[https://github.com/wcsmith/evil-args][evil-args]] | motions and text objects for arguments |
+ | [[https://github.com/bling/evil-jumper][evil-jumper]] | jump list emulation |
+ | [[https://github.com/jaypei/emacs-neotree][NeoTree]] | mimic [[https://github.com/scrooloose/nerdtree][NERD Tree]] |
+* Spacemacs UI
+
+=Spacemacs= has unique UI elements to make the Emacs experience even more
+enjoyable:
+ - dedicated startup page with a mode aimed at easily managing =Spacemacs=
+ - dedicated helm source via =helm-spacemacs=
+ - a [[https://github.com/kai2nenobu/guide-key][guide-key]] buffer
+
+** Graphical UI
+
+=Spacemacs= has a minimalistic and distraction free graphical UI:
+ - custom [[https://github.com/milkypostman/powerline][powerline]] mode-line [[#flycheck-integration][with color feedback]] according to current [[https://github.com/flycheck/flycheck][Flycheck]] status
+ - unicode symbols for minor mode lighters which appear in the mode-line
+ - [[#errors-handling][custom fringe bitmaps]] and error feedbacks for [[https://github.com/flycheck/flycheck][Flycheck]]
+
+*** Color themes
+
+By default, =Spacemacs= uses the theme [[https://github.com/bbatsov/solarized-emacs][solarized-light]].
+
+It is possible to define your default themes in your =~/.spacemacs= with the
+variable =dotspacemacs-themes=. For instance, to specify =leuven= and =zenburn=
+(high contrast theme and low contrast theme):
+
+#+begin_src emacs-lisp
+ (setq-default dotspacemacs-themes '(leuven zenburn))
+#+end_src
+
+| Key Binding | Description |
+|-------------+-------------------------------------------------------|
+| ~SPC T n~ | switch to next theme listed in =dotspacemacs-themes=. |
+| ~SPC T h~ | select a theme using a =helm= buffer. |
+
+*Note:*
+ - You don't need to explicitly list in a layer the theme packages you are
+ defining in =dotspacemacs-themes=, Spacemacs is smart enough to remove those
+ packages from the list of orphans.
+ - Due to the inner working of themes in Emacs, switching theme during the same
+ session may have some weird side effects. Although these side effects should
+ be pretty rare.
+
+*Hint* If you are an =Org= user, [[https://github.com/fniessen/emacs-leuven-theme][leuven-theme]] is amazing ;-)
+
+*** Font
+
+The default font used by =Spacemacs= is [[https://github.com/adobe-fonts/source-code-pro][source code pro]] by Adobe. It is
+recommended to install it on your system.
+
+To change the default font set the variable =dotspacemacs-default-font= in your
+=.spacemacs= file.
+
+By default its value is:
+
+#+begin_src emacs-lisp
+ (setq-default dotspacemacs-default-font '("Source Code Pro"
+ :size 13
+ :weight normal
+ :width normal
+ :powerline-scale 1.1))
+#+end_src
+
+The properties should be pretty straightforward, it is possible to set any valid
+property of a [[http://www.gnu.org/software/emacs/manual/html_node/elisp/Low_002dLevel-Font.html][font-spec]]:
+ - =:family= Font family or fontset (a string).
+ - =:width= Relative character width. This should be one of the symbols:
+ - ultra-condensed
+ - extra-condensed
+ - condensed
+ - semi-condensed
+ - normal
+ - semi-expanded
+ - expanded
+ - extra-expanded
+ - ultra-expanded
+ - =:height= The height of the font. In the simplest case, this is an integer
+ in units of 1/10 point.
+ - =:weight= Font weight- one of the symbols (from densest to faintest):
+ - ultra-bold
+ - extra-bold
+ - bold
+ - semi-bold
+ - normal
+ - semi-light
+ - light
+ - extra-light
+ - ultra-light
+ - =:slant= Font slant- one of the symbols:
+ - italic
+ - oblique
+ - normal
+ - reverse-italic
+ - reverse-oblique
+ - =:size= The font size- either a non-negative integer that specifies the
+ pixel size, or a floating-point number that specifies the point size.
+ - =:adstyle= Additional typographic style information for the font, such as
+ 'sans'. The value should be a string or a symbol.
+ - =:registry= The charset registry and encoding of the font, such as
+ 'iso8859-1'. The value should be a string or a symbol.
+ - =:script= The script that the font must support (a symbol).
+
+The special property =:powerline-scale= is =Spacemacs= specific and it is for
+quick tweaking of the mode-line height in order to avoid crappy rendering of the
+separators like on the following screenshot (default value is 1.1).
+
+/Ugly separators/
+
+#+CAPTION: ugly-separators
+
+[[file:img/crappy-powerline-separators.png]]
+
+*** Graphical UI Toggles
+
+Some graphical UI indicators can be toggled on and off (toggles start with ~t~
+and ~T~):
+
+| Key Binding | Description |
+|-------------+-------------------------------------------------------------------|
+| ~SPC t~~ | display =~= in the fringe on empty lines |
+| ~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 i~ | toggle indentation guide at point |
+| ~SPC t l~ | toggle truncate lines |
+| ~SPC t L~ | toggle visual lines |
+| ~SPC t n~ | show the absolute line numbers |
+
+ | Key Binding | Description |
+ |-------------+------------------------------|
+ | ~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 |
+
+*Note* These toggles are all available via the =helm-spacemacs= interface (press
+~SPC f e h~ to display the =helm-spacemacs= buffer).
+
+*** Mouse usage
+
+There are some added mouse features set for the line number margin (if shown):
+
+- single click in line number margin visually selects the entire line
+- drag across line number margin visually selects the region
+- double click in line number margin visually select the current code block
+
+*** Mode-line
+
+The mode line is a heavily customized [[https://github.com/milkypostman/powerline][powerline]] with the following capabilities:
+ - show the window number
+ - color code for current state
+ - show the number of search occurrences via anzu
+ - toggle flycheck info
+ - toggle battery info
+ - toggle minor mode lighters
+
+Reminder of the color codes for the states:
+
+| Evil State | Color |
+|----------------------+----------|
+| Normal | Orange |
+| Insert | Green |
+| Visual | Grey |
+| Emacs | Blue |
+| Motion | Purple |
+| Lisp | Pink |
+| Iedit/Iedit-Insert | Red |
+
+Some elements can be dynamically toggled:
+
+| Key Binding | Description |
+|-------------+-----------------------------------------------------------------|
+| ~SPC t m b~ | toggle the battery status |
+| ~SPC t m c~ | toggle the =org= task clock (available in =org= layer) |
+| ~SPC t m f~ | toggle the flycheck info (available in =syntax-checking= layer) |
+| ~SPC t m m~ | toggle the minor mode lighters |
+| ~SPC t m n~ | toggle the cat! (if =colors= layer is declared in your dotfile) |
+| ~SPC t m p~ | toggle the point character position |
+| ~SPC t m t~ | toggle the mode line itself |
+| ~SPC t m v~ | toggle the new version lighter |
+
+**** Flycheck integration
+
+When [[https://github.com/flycheck/flycheck][Flycheck]] minor mode is enabled, a new element appears showing the number of
+errors, warnings and info.
+
+#+CAPTION: powerline-wave
+
+[[file:img/powerline-wave.png]]
+
+**** Anzu integration
+
+[[https://github.com/syohex/emacs-anzu][Anzu]] shows the number of occurrence when performing a search. =Spacemacs=
+integrates nicely the Anzu status by displaying it temporarily when ~n~ or ~N~
+are being pressed. See the =5/6= segment on the screenshot below.
+
+#+CAPTION: powerline-anzu
+
+[[file:img/powerline-anzu.png]]
+
+**** Battery status integration
+
+[[https://github.com/lunaryorn/fancy-battery.el][fancy-battery]] displays the percentage of total charge of the battery as well as
+the time remaining to charge or discharge completely the battery.
+
+A color code is used for the battery status:
+
+| Battery State | Color |
+|-----------------+----------|
+| Charging | Green |
+| Discharging | Orange |
+| Critical | Red |
+
+Note the these colors may vary depending on your theme.
+
+**** Powerline separators
+
+It is possible to easily customize the =powerline separator= by setting the
+=powerline-default-separator= variable in your =~./spacemacs=. For instance if
+you want to set back the separator to the well-known =arrow= separator add the
+following snippet to your configuration file:
+
+#+begin_src emacs-lisp
+ (defun dotspacemacs/config ()
+ "This is were you can ultimately override default Spacemacs configuration.
+ This function is called at the very end of Spacemacs initialization."
+ (setq powerline-default-separator 'arrow))
+#+end_src
+
+To save you the time to try all the possible separators provided by the
+powerline, here is an exhaustive set of screenshots:
+
+| Separator | Screenshot |
+|--------------+-----------------------------------|
+| =alternate= | [[file:img/powerline-alternate.png]] |
+| =arrow= | [[file:img/powerline-arrow.png]] |
+| =arrow-fade= | [[file:img/powerline-arrow-fade.png]] |
+| =bar= | [[file:img/powerline-bar.png]] |
+| =box= | [[file:img/powerline-box.png]] |
+| =brace= | [[file:img/powerline-brace.png]] |
+| =butt= | [[file:img/powerline-butt.png]] |
+| =chamfer= | [[file:img/powerline-chamfer.png]] |
+| =contour= | [[file:img/powerline-contour.png]] |
+| =curve= | [[file:img/powerline-curve.png]] |
+| =rounded= | [[file:img/powerline-rounded.png]] |
+| =roundstub= | [[file:img/powerline-roundstub.png]] |
+| =slant= | [[file:img/powerline-slant.png]] |
+| =wave= | [[file:img/powerline-wave.png]] |
+| =zigzag= | [[file:img/powerline-zigzag.png]] |
+| =nil= | [[file:img/powerline-nil.png]] |
+
+**** Minor Modes
+
+=Spacemacs= uses [[http://www.emacswiki.org/emacs/DiminishedModes][diminish]] mode to reduce the size of minor mode indicators:
+
+The minor mode area can be toggled on and off with ~SPC t m m~
+
+Unicode symbols are displayed by default. Setting the variable
+=dotspacemacs-mode-line-unicode-symbols= to =nil= in your =~/.spacemacs= will
+display ASCII characters instead (may be useful in terminal if you cannot set an
+appropriate font).
+
+The letters displayed in the mode-line correspond to the key bindings used to
+toggle them.
+
+Some toggle have two flavors: local and glocal. The global version of the toggle
+can be reached using the =control= key.
+
+| Key Binding | Unicode | ASCII | Mode |
+|-------------+---------+-------+-------------------------------------|
+| ~SPC t -~ | =⊝= | - | [[http://emacswiki.org/emacs/centered-cursor-mode.el][centered-cursor]] mode |
+| ~SPC t C--~ | | | global centered cursor |
+| ~SPC t a~ | =ⓐ= | a | auto-completion |
+| ~SPC t c~ | =ⓒ= | c | camel case motion with subword mode |
+| =none= | =ⓔ= | e | [[https://github.com/edwtjo/evil-org-mode][evil-org]] mode |
+| ~SPC t c~ | =none= | | fill-column-indicator mode |
+| ~SPC t F~ | =Ⓕ= | F | auto-fill mode |
+| ~SPC t g~ | =ⓖ= | g | [[https://github.com/roman/golden-ratio.el][golden-ratio]] mode |
+| ~SPC t k~ | =Ⓖ= | G | guide-key mode |
+| ~SPC t i~ | =ⓘ= | i | indentation guide |
+| ~SPC t C-i~ | =ⓘ= | i | global indentation guide |
+| ~SPC t I~ | =Ⓘ= | I | aggressive indent mode |
+| ~SPC t p~ | =ⓟ= | p | [[https://github.com/Fuco1/smartparens][smartparens]] mode |
+| ~SPC t C-p~ | | | global smartparens |
+| ~SPC t s~ | =ⓢ= | s | syntax checking (flycheck) |
+| ~SPC t S~ | =Ⓢ= | S | spell checking (flyspell) |
+| ~SPC t w~ | =ⓦ= | w | whitespace mode |
+| ~SPC t C-w~ | =Ⓦ= | W | global whitespace |
+| ~SPC t y~ | =ⓨ= | y | [[https://github.com/capitaomorte/yasnippet][yasnippet]] mode |
+
+* Commands
+
+** Vim key bindings
+
+=Spacemacs= is based on =Vim= modal user interface to navigate and edit text. If
+you are not familiar with the =Vim= way of editing text you can try the
+[[https://github.com/syl20bnr/evil-tutor][evil-tutor]] lessons by pressing ~SPC h T~ at any time.
+
+*** Escaping
+
+=Spacemacs= uses [[https://github.com/syl20bnr/evil-escape][evil-escape]] to easily switch between =insert state= and =normal
+state= by quickly pressing the ~fd~ keys.
+
+The choice of ~fd~ was made to be able to use the same sequence to escape from
+"everything" in Emacs:
+ - escape from all evil states to normal state
+ - escape from evil-lisp-state to normal state
+ - abort evil ex command
+ - quit minibuffer
+ - abort isearch
+ - quit magit buffers
+ - quit help buffers
+ - quit apropos buffers
+ - quit ert buffers
+ - quit undo-tree buffer
+ - quit paradox
+ - quit gist-list menu
+ - hide neotree buffer
+
+If you find yourself in a buffer where the =Spacemacs= (~SPC~) or Vim
+keybindings don't work you can use this to get back to =normal state= (for
+example in ~SPC : customize~ press ~fd~ to make ~SPC b s~ work again).
+
+This sequence can be customized in your =~/.spacemacs=. Example to set it to
+~jj~ (it is important set the variable in =dotspacemacs/init=):
+
+#+begin_src emacs-lisp
+ (defun dotspacemacs/init ()
+ (setq-default evil-escape-key-sequence "jj"))
+#+end_src
+
+*Note:* Although ~jj~ or ~jk~ are popular choices of vim users, these key
+sequences are not optimal for =Spacemacs=. Indeed it is very easy in =visual
+state= to press quickly ~jj~ and inadvertently escape to =normal state=.
+
+*Important Note* One caveat of =evil-escape= is that you must not use it while
+recording macros. Use =escape= key instead.
+
+*** Executing Vim and Emacs ex/M-x commands
+
+ | Command | Key Binding |
+ |------------------+-------------|
+ | Vim (ex-command) | ~:~ |
+ | Emacs (M-x) | ~SPC :~ |
+
+The command key ~:~ can be easily changed with the variable
+=dotspacemacs-command-key= of your =~/.spacemacs=. Note that is will change both
+~:~ and ~SPC :~ bindings to keep the symmetry between Vim and Emacs. A good key
+can be ~,~ for example.
+
+*** Leader key
+
+On top of =Vim= modes (modes are called states in =Spacemacs=) there is a
+special key called the leader key which once pressed gives a whole new keyboard
+layer. The leader key is by default ~SPC~ (space). It is possible to change this
+key with the variable =dotspacemacs-leader-key=.
+
+** Reserved prefix command for user
+
+~SPC o~ is reserved for the user. Setting key bindings behind ~SPC o~ is
+*guaranteed* to never conflict with =Spacemacs= defaults key bindings.
+
+*Example:* Put =(evil-leader/set-key "oc" 'org-capture)= inside
+=dotspacemacs/config= in your =~/.spacemacs= file, to be able to use ~SPC o c~
+to run org mode capture.
+
+** Helm
+
+=Spacemacs= is powered by [[https://github.com/emacs-helm/helm][Helm]] which is an incremental completion and selection
+narrowing framework.
+
+=Helm= is the central control tower of =Spacemacs=, it is used to manage
+buffers, projects, search results, configuration layers, toggles and more...
+
+Mastering =Helm= will make you a =Spacemacs= power user. Do not hesitate to read
+the [[https://github.com/emacs-helm/helm/wiki][Helm documentation wiki]].
+
+*** C-z and Tab switch
+
+The command bound to ~C-z~ is much more useful than the one bound to Tab, so it
+makes sense to swap them. It's also recommended [[http://tuhdo.github.io/helm-intro.html][here]].
+
+*** Helm micro-state
+
+=Spacemacs= defines a [[#micro-states][micro-state]] for =Helm= to make it work like [[https://github.com/Shougo/unite.vim][Vim's Unite]]
+plugin.
+
+Initiate the micro-state with ~M-SPC~ or ~s-M-SPC~ while in a =Helm= buffer.
+
+| Key Binding | Description |
+|----------------------+--------------------------------------------------|
+| ~M-SPC~ or ~s-M-SPC~ | initiate or leave the micro-state |
+| ~TAB~ | switch to actions page and leave the micro-state |
+| ~1~ | execute action 0 |
+| ~2~ | execute action 1 |
+| ~3~ | execute action 2 |
+| ~4~ | execute action 3 |
+| ~5~ | execute action 4 |
+| ~6~ | execute action 5 |
+| ~7~ | execute action 6 |
+| ~8~ | execute action 7 |
+| ~9~ | execute action 8 |
+| ~0~ | execute action 9 |
+| ~a~ | switch to actions page |
+| ~g~ | go to first candidate |
+| ~G~ | go to last candidate |
+| ~h~ | go to previous source |
+| ~j~ | select next candidate |
+| ~k~ | select previous candidate |
+| ~l~ | go to next source |
+| ~q~ | quit micro-state |
+| ~t~ | mark current candidate |
+| ~T~ | mark all candidates |
+| ~v~ | execute persistent action |
+
+** Discovering
+
+*** Key bindings
+
+**** Guide-key
+
+An help buffer is displayed each time the ~SPC~ key is pressed in normal mode.
+It lists the available key bindings and their associated commands.
+
+By default the [[https://github.com/kai2nenobu/guide-key][guide-key]] buffer will be displayed quickly after the key has been
+pressed. You can change the delay by setting the variable
+=dotspacemacs-guide-key-delay= to your liking (the value is in second).
+
+**** Helm describe key bindings
+
+It is possible to search for specific key bindings by pressing ~SPC ?~.
+
+To narrow the list to some key bindings using the leader key type a pattern like
+this regular expression: ~SPC\ b~ which would list all =buffer= related
+bindings.
+
+*** Getting help
+
+=Describe functions= are powerful Emacs introspection commands to get
+information about functions, variables, modes etc. These commands are bound
+thusly:
+
+| Key Binding | Description |
+|-------------+----------------------------------------|
+| ~SPC h d b~ | describe bindings in a =helm= buffer |
+| ~SPC h d c~ | describe current character under point |
+| ~SPC h d f~ | describe a function |
+| ~SPC h d k~ | describe a key |
+| ~SPC h d m~ | describe current modes |
+| ~SPC h d p~ | describe a package |
+| ~SPC h d t~ | describe a theme |
+| ~SPC h d v~ | describe a variable |
+
+Other help key bindings:
+
+| Key Binding | Description |
+|-------------+-----------------------------------------------|
+| ~SPC h i~ | search in info pages with the symbol at point |
+| ~SPC h m~ | search available man pages |
+
+*** Available layers
+
+All layers can be easily discovered via =helm-spacemacs= accessible with ~SPC f
+e h~.
+
+The following helm actions are available:
+ - default: open the layer =README.md=
+ - 2nd: open the layer =packages.el=
+ - 3nd: open the layer =extensions.el=
+
+**** Available packages in Spacemacs
+
+=helm-spacemacs= also lists all the packages available in =Spacemacs=. The entry
+format is =(layer) packages=. If you type =flycheck= you'll be able to see all
+the layers where =flycheck= is used.
+
+The following helm actions are available on packages:
+ - default: go the package init function
+
+**** New packages from ELPA repositories
+
+=package-list-packages= is where you can browse for all available packages in
+the different Elpa repositories. It is possible to upgrade packages from there
+but it is not recommended, use the =[Update]= link on the =Spacemacs= startup
+page instead.
+
+=Spacemacs= proposes to use [[https://github.com/Bruce-Connor/paradox][Paradox]] instead of =package-list-packages= to list
+available ELPA packages. Paradox enhances the package list buffer with better
+feedbacks, new filters and Github information like the number of stars.
+Optionally you can also star packages directly in the buffer.
+
+*Important Note 1* Installing a new package from =Paradox= won't make it
+persistent. To install a package persistently you have to add it explicitly to a
+configuration layer.
+
+*Important Note 2* Don't /update/ your packages from =Paradox= or
+=package-list-packages= because they don't support the rollback feature of
+Spacemacs.
+
+| Key Binding | Description |
+|-------------+-------------------------------------------------------|
+| ~/~ | evil-search |
+| ~f k~ | filter by keywords |
+| ~f r~ | filter by regexp |
+| ~f u~ | display only installed package with updates available |
+| ~h~ | go left |
+| ~H~ | show help (not accurate) |
+| ~j~ | go down |
+| ~k~ | go up |
+| ~l~ | go right |
+| ~L~ | show last commits |
+| ~n~ | next search occurrence |
+| ~N~ | previous search occurrence |
+| ~o~ | open package homepage |
+| ~r~ | refresh |
+| ~S P~ | sort by package name |
+| ~S S~ | sort by status (installed, available, etc...) |
+| ~S *~ | sort by Github stars |
+| ~v~ | =visual state= |
+| ~V~ | =visual-line state= |
+| ~x~ | execute (action flags) |
+
+*** Toggles
+
+=helm-spacemacs= is also a central place to discover the available toggles. To
+display only the toggles source press ~C-l~ (or in [[#helm-micro-state][Helm micro-state]] you can
+press just ~l~).
+
+The following helm actions are available on packages:
+ - default: toggle on/off
+
+*Tips* Use ~SPC h l~ to resume the last helm session. It is handy to quickly
+toggle on and off a toggle.
+
+** Navigating
+
+*** Point/Cursor
+
+Navigation is performed using the Vi key bindings ~hjkl~.
+
+| Key Binding | Description |
+|-------------+-----------------------------------------------------------------------------------|
+| ~h~ | move cursor left |
+| ~j~ | move cursor down |
+| ~k~ | move cursor up |
+| ~l~ | move cursor right |
+| ~H~ | move quickly up (10 lines at a time) |
+| ~L~ | move quickly down (10 lines at a time) |
+| ~SPC j h~ | go to the beginning of line (and set a mark at the previous location in the line) |
+| ~SPC j l~ | go to the end of line (and set a mark at the previous location in the line) |
+| ~SPC z z~ | lock the cursor at the center of the screen |
+
+**** Smooth scrolling
+
+[[https://github.com/aspiers/smooth-scrolling][smooth-scrolling]] prevent the point to jump when it reaches the top or
+bottom of the screen. It is enabled by default.
+
+On Windows, you may want to disable it. To disable the smooth scrolling set the
+=dotspacemacs-smooth-scrolling= variable in your =~/.spacemacs= to =nil=:
+
+#+begin_src emacs-lisp
+ (setq-default dotspacemacs-smooth-scrolling t)
+#+end_src
+
+*** Vim motions with ace-jump mode
+
+=Spacemacs= uses the =evil= integration of [[https://github.com/winterTTr/ace-jump-mode][ace-jump mode]] which enables the
+invocation of =ace-jump-mode= during motions.
+
+It is useful for deleting visually a set of lines, try the following sequence in
+a buffer containing some text: ~d SPC l~
+
+| Key Binding | Description |
+|-------------+----------------------------------------------------|
+| ~SPC SPC~ | initiate ace jump word mode |
+| ~SPC l~ | initiate ace jump line mode |
+| ~SPC `~ | go back to the previous location (before the jump) |
+
+Hint: you may change to char mode by ~C-c C-c~ in word mode.
+
+**** ace-link mode
+
+Similar to =ace-jump-mode=, [[https://github.com/abo-abo/ace-link][ace-link]] allows one to jump to any link in
+=help-mode= and =info-mode= with two key strokes.
+
+| Key Binding | Description |
+|-------------+-------------------------------------------------------|
+| ~o~ | initiate ace link mode in =help-mode= and =info-mode= |
+
+*** Window manipulation
+
+**** Window manipulation key bindings
+
+Every window has a number displayed at the start of the mode-line and
+can be quickly accessed using =SPC number=.
+
+| Key Binding | Description |
+|-------------+-----------------------|
+| ~SPC 1~ | go to window number 1 |
+| ~SPC 2~ | go to window number 2 |
+| ~SPC 3~ | go to window number 3 |
+| ~SPC 4~ | go to window number 4 |
+| ~SPC 5~ | go to window number 5 |
+| ~SPC 6~ | go to window number 6 |
+| ~SPC 7~ | go to window number 7 |
+| ~SPC 8~ | go to window number 8 |
+| ~SPC 9~ | go to window number 9 |
+| ~SPC 0~ | go to window number 0 |
+
+Windows manipulation commands (start with ~w~):
+
+| Key Binding | Description |
+|------------------------+-----------------------------------------------------------------------------|
+| ~SPC w =~ | balance split windows |
+| ~SPC w b~ | force the focus back to the minibuffer (usefull with =helm= popups) |
+| ~SPC w c~ | close a window |
+| ~SPC w C~ | delete another window using [[https://github.com/abo-abo/ace-window][ace-delete-window]] |
+| ~SPC w d~ | toggle window dedication (dedicated window cannot be reused by a mode) |
+| ~SPC w h~ | move to window on the left |
+| ~SPC w H~ | move window to the left |
+| ~SPC w j~ | move to window below |
+| ~SPC w J~ | move window to the bottom |
+| ~SPC w k~ | move to window above |
+| ~SPC w K~ | move window to the top |
+| ~SPC w l~ | move to window on the right |
+| ~SPC w L~ | move window to the right |
+| ~SPC w m~ | maximize/minimize a window (maximize is equivalent to delete other windows) |
+| ~SPC w M~ | maximize/minimize a window, when maximized the buffer is centered |
+| ~SPC w o~ | cycle and focus between frames |
+| ~SPC w p m~ | open messages buffer in a popup window |
+| ~SPC w p p~ | close the current sticky popup window |
+| ~SPC w R~ | rotate windows clockwise |
+| ~SPC w s~ or ~SPC w /~ | horizontal split |
+| ~SPC w S~ | horizontal split and focus new window |
+| ~SPC w u~ | undo window layout (used to effectively undo a closed window) |
+| ~SPC w U~ | redo window layout |
+| ~SPC w v~ or ~SPC w -~ | vertical split |
+| ~SPC w V~ | vertical split and focus new window |
+| ~SPC w w~ | cycle and focus between windows |
+| ~SPC w W~ | select window using [[https://github.com/abo-abo/ace-window][ace-window]] |
+
+**** Window manipulation micro-state
+
+A convenient window manipulation micro-state allows to perform most of the
+actions listed above. The micro-state allows additional actions as well like
+window resizing.
+
+| Key Binding | Description |
+|---------------+---------------------------------------------------------------|
+| ~SPC w .~ | initiate micro-state |
+| ~?~ | display the full documentation in minibuffer |
+| ~0~ | go to window number 0 |
+| ~1~ | go to window number 1 |
+| ~2~ | go to window number 2 |
+| ~3~ | go to window number 3 |
+| ~4~ | go to window number 4 |
+| ~5~ | go to window number 5 |
+| ~6~ | go to window number 6 |
+| ~7~ | go to window number 7 |
+| ~8~ | go to window number 8 |
+| ~9~ | go to window number 9 |
+| ~-~ | vertical split |
+| ~/~ | horizontal split |
+| ~[~ | shrink window horizontally |
+| ~]~ | enlarge window horizontally |
+| ~{~ | shrink window vertically |
+| ~}~ | enlarge window vertically |
+| ~c~ | close window |
+| ~C~ | close other windows |
+| ~g~ | toggle =golden-ratio= on and off |
+| ~h~ | go to window on the left |
+| ~j~ | go to window below |
+| ~k~ | go to window above |
+| ~l~ | go to window on the right |
+| ~H~ | move window to the left |
+| ~J~ | move window to the bottom |
+| ~K~ | move bottom to the top |
+| ~L~ | move window to the right |
+| ~o~ | focus other frame |
+| ~R~ | rotate windows |
+| ~s~ | horizontal split |
+| ~S~ | horizontal split and focus new window |
+| ~u~ | undo window layout (used to effectively undo a closed window) |
+| ~U~ | redo window layout |
+| ~v~ | vertical split |
+| ~V~ | horizontal split and focus new window |
+| ~w~ | focus other window |
+| Any other key | leave the micro-state |
+
+**** Golden ratio
+
+If you resize windows like crazy you may want to give a try to [[https://github.com/roman/golden-ratio.el][golden-ratio]].
+
+=golden-ratio= resizes windows dynamically depending on whether they are
+selected or not. By default =golden-ratio= is off.
+
+The mode can be toggled on and off with ~SPC t g~.
+
+*** Buffers and Files
+
+Since =helm= is used everywhere, by default Spacemacs uses =helm= to open files.
+
+Some users prefer the =ido= way to navigate the file system because it can
+remember the last selected directories and buffers and return is used to open
+directories instead of ~TAB~ or ~C-z~ in =helm=. It is possible to use =ido=
+instead of =helm= by setting the variable =dotspacemacs-use-ido= to =t= in your
+dotfile.
+
+**** Buffers manipulation key bindings
+
+Buffer manipulation commands (start with ~b~):
+
+| Key Binding | Description |
+|-------------+-------------------------------------------------------------------------|
+| ~SPC TAB~ | switch to alternate buffer (switch back and forth) |
+| ~SPC b b~ | switch to a buffer using =helm= |
+| ~SPC b d~ | kill the current buffer (does not delete the visited file) |
+| ~SPC b e~ | erase the content of the buffer (ask for confirmation) |
+| ~SPC b h~ | open =*spacemacs*= home buffer |
+| ~SPC b k~ | kill a buffer |
+| ~SPC b K~ | kill all buffers except the current one |
+| ~SPC b C-K~ | kill all buffers matching the regexp |
+| ~SPC b m h~ | move a buffer to the left |
+| ~SPC b m j~ | move a buffer to the bottom |
+| ~SPC b m k~ | move a buffer to the top |
+| ~SPC b m l~ | move a buffer to the right |
+| ~SPC b M~ | swap windows using [[https://github.com/abo-abo/ace-window][ace-swap-window]] |
+| ~SPC b n~ | switch to next buffer avoiding special buffers |
+| ~SPC b p~ | switch to previous buffer avoiding special buffers |
+| ~SPC b P~ | copy clipboard and replace buffer (useful when pasting from a browser) |
+| ~SPC b R~ | revert the current buffer (reload from disk) |
+| ~SPC b w~ | toggle read-only (writable state) |
+| ~SPC b Y~ | copy whole buffer to clipboard (useful when copying to a browser) |
+| ~z f~ | Make current function or comments visible in buffer as much as possible |
+
+**** Buffers manipulation manipulation micro-state
+
+A convenient buffer manipulation micro-state allows to quickly cycles through
+the opened buffer and kill them.
+
+| Key Binding | Description |
+|---------------+-----------------------------------------------|
+| ~SPC b .~ | initiate micro-state |
+| ~K~ | kill current buffer |
+| ~n~ | go to next buffer (avoid special buffers) |
+| ~N~ | go to previous buffer (avoid special buffers) |
+| Any other key | leave the micro-state |
+
+**** Special Buffers
+
+Unlike vim, emacs creates many buffers that most people do not need to see. Some
+examples are =*Messages*= and =*Compile-Log*=. Spacemacs tries to automatically
+ignore buffers that are not useful. However, you may want to change the way
+Spacemacs marks buffers as useful. For instructions, see the [[./HOWTOs.org#change-special-buffer-rules][special buffer
+howto]].
+
+**** Files manipulations key bindings
+
+Files manipulation commands (start with ~f~):
+
+| Key Binding | Description |
+|-------------+----------------------------------------------------------------|
+| ~SPC f D~ | delete a file and the associated buffer (ask for confirmation) |
+| ~SPC f f~ | open file with =helm= (or =ido=) |
+| ~SPC f F~ | try to open the file under point =helm= |
+| ~SPC f j~ | jump to the current buffer file in dired |
+| ~SPC f o~ | open a file using the default external program |
+| ~SPC f R~ | rename the current file |
+| ~SPC f s~ | save a file |
+| ~SPC f S~ | save all files |
+| ~SPC f r~ | open a recent file with =helm= |
+| ~SPC f t~ | toggle file tree side bar using [[https://github.com/jaypei/emacs-neotree][NeoTree]] |
+| ~SPC f y~ | show current file absolute path in the minibuffer |
+
+**** Emacs and Spacemacs files
+
+Convenient key bindings are located under the prefix ~SPC f e~ to quickly
+navigate between =Emacs= and =Spacemacs= specific files.
+
+| Key Binding | Description |
+|-------------+----------------------------------------------------------------------|
+| ~SPC f e c~ | open =ido= in the =contrib= folder |
+| ~SPC f e d~ | open the spacemacs dotfile (=~/.spacemacs=) |
+| ~SPC f e D~ | open =ediff= buffer of =~/.spacemacs= and =.spacemacs.template= |
+| ~SPC f e h~ | discover =Spacemacs= documentation, layers and packages using =helm= |
+| ~SPC f e i~ | open the all mighty =init.el= |
+| ~SPC f e R~ | resync the dotfile with spacemacs |
+| ~SPC f e s~ | open =ido= in the =spacemacs= layer folder |
+| ~SPC f e v~ | display and copy the spacemacs version |
+
+*** Ido
+
+=Spacemacs= displays the =ido= minibuffer vertically thanks to the
+[[https://github.com/gempesaw/ido-vertical-mode.el][ido-vertical-mode]].
+
+Basic =ido= operations can be done with ~Ctrl~ key:
+
+| Key Binding | Description |
+|--------------------+---------------------------------------------------|
+| ~C-~ | open a =dired buffer= |
+| ~M-~ | open a =dired buffer= in terminal |
+| ~C-d~ | delete selected file (ask for confirmation) |
+| ~C-h~ | go to parent directory |
+| ~C-j~ | select next file or directory |
+| ~C-k~ | select previous file or directory |
+| ~C-l~ | open the selected file |
+| ~C-n~ | select next file or directory |
+| ~C-o~ | open selected file in other window |
+| ~C-p~ | select previous file or directory |
+| ~C-s~ | open selected file in a vertically split window |
+| ~C-t~ | open selected file in a new frame |
+| ~C-v~ | open selected file in a horizontally split window |
+| ~C-S-h~ | go to previous directory |
+| ~C-S-j~ or ~C-S-n~ | next history element |
+| ~C-S-k~ or ~C-S-p~ | previous history element |
+| ~C-S-l~ | go to next directory |
+
+*** Ido micro-state
+=Spacemacs= defines a [[#micro-states][micro-state]] for =ido=.
+
+Initiate the micro-state with ~M-SPC~ or ~s-M-SPC~ while in an =ido= buffer.
+
+| Key Binding | Description |
+|----------------------+-------------------------------------|
+| ~M-SPC~ or ~s-M-SPC~ | initiate or leave the micro-state |
+| ~?~ | display help |
+| ~e~ | open dired |
+| ~h~ | delete backward or parent directory |
+| ~j~ | next match |
+| ~J~ | sub directory |
+| ~k~ | previous match |
+| ~K~ | parent directory |
+| ~l~ | select match |
+| ~n~ | next directory in history |
+| ~o~ | open in other window |
+| ~p~ | previous directory in history |
+| ~q~ | quit micro-state |
+| ~s~ | open in a new horizontal split |
+| ~t~ | open in other frame |
+| ~v~ | open in a new vertical split |
+
+*** NeoTree file tree
+
+=Spacemacs= provides a quick and simple way to navigate in an unknown project
+file tree with [[https://github.com/jaypei/emacs-neotree][NeoTree]].
+
+To toggle the =NeoTree= buffer press ~SPC f t~ or ~SPC p t~ (the latter open
+NeoTree with the root set to the projectile project root).
+
+The NeoTree window always has the number =0= so it does not shift the current
+number of the other windows. To select the NeoTree window you then use ~SPC 0~.
+
+**** NeoTree navigation
+
+Navigation is centered on the ~hjkl~ with the hope to provide a fast navigation
+experience like in [[http://ranger.nongnu.org/][ranger]]:
+
+| Key Binding | Description |
+|---------------+--------------------------------------------------------------------------|
+| h | collapse expanded directory or go to parent node |
+| H | previous sibling |
+| j | next file or directory |
+| J | next expanded directory on level down |
+| k | previous file or directory |
+| K | parent directory, when reaching the root change it to parent directory |
+| l or RET | expand directory |
+| L | next sibling |
+| R | make a directory the root directory |
+
+*Note:* The point is automatically set to the first letter of a node for a
+smoother experience.
+
+**** Opening files with NeoTree
+
+By default a file is opened in the last active window. It is possible to choose
+window number where to open a file by using a numeric argument, for instance ~2
+l~ or ~2 RET~ will open the current file in window 2. It is also possible to
+open the file in a split window with ~|~ and ~-~:
+
+| Key Binding | Description |
+|------------------+-------------------------------------------|
+| ~l~ or ~RET~ | open file in last active window |
+| ~# l~ or ~# RET~ | open file in window number =#= |
+| ~¦~ | open file in an vertically split window |
+| ~-~ | open file in an horizontally split window |
+
+**** Other NeoTree key bindings
+
+| Key Binding | Description |
+|-------------+---------------------------------|
+| ~TAB~ | toggle stretching of the buffer |
+| ~c~ | create a node |
+| ~d~ | delete a node |
+| ~g~ | refresh |
+| ~s~ | toggle showing of hidden files |
+| ~q~ or ~fd~ | hide =NeoTree= buffer |
+| ~r~ | rename a node |
+
+**** NeoTree mode-line
+
+The mode-line has the following format =[x/y] d (D:a, F:b)= where:
+ - =x= is the index of the current selected file or directory
+ - =y= the total number of items (file and directory) in the current directory
+ - =d= the name of the current directory
+ - =a= the number of directories in the current directory
+ - =b= the number of files in the current directory
+
+*** Bookmarks
+
+Bookmarks can be set anywhere in a file. Bookmarks are persistent. They are very
+useful to jump to/open a known project. =Spacemacs= used =helm-bookmarks= to
+manage them.
+
+Open an =helm= window with the current bookmarks by pressing: ~SPC h b~
+
+Then in the =helm-bookmarks= buffer:
+
+| Key Binding | Description |
+|-------------+----------------------------------------------|
+| ~C-d~ | delete the selected bookmark |
+| ~C-e~ | edit the selected bookmark |
+| ~C-f~ | toggle filename location |
+| ~C-o~ | open the selected bookmark in another window |
+
+To save a new bookmark, just type the name of the bookmark and press ~RET~.
+
+*** DocView mode
+
+=doc-view-mode= is a built-in major mode to view DVI, PostScript (PS), PDF,
+OpenDocument, and Microsoft Office documents.
+
+| Key Binding | Description |
+|-------------+------------------------------------------|
+| ~/~ | search forward |
+| ~?~ | search backward |
+| ~+~ | enlarge |
+| ~-~ | shrink |
+| ~gg~ | go to first page |
+| ~G~ | go to last page |
+| ~gt~ | go to page number |
+| ~h~ | previous page |
+| ~H~ | adjust to height |
+| ~j~ | next line |
+| ~k~ | previous line |
+| ~K~ | kill proc and buffer |
+| ~l~ | next page |
+| ~n~ | go to next search occurrence |
+| ~N~ | go to previous search occurrence |
+| ~P~ | fit page to window |
+| ~r~ | revert |
+| ~W~ | adjust to width |
+| ~C-d~ | scroll down |
+| ~C-k~ | kill proc |
+| ~C-u~ | scroll up |
+| ~C-c C-c~ | toggle display text and image display |
+| ~C-c C-t~ | open new buffer with doc's text contents |
+
+** Searching
+
+*** With an external tool
+
+=Spacemacs= can be interfaced with different search utilities:
+ - ack
+ - grep
+ - [[https://github.com/ggreer/the_silver_searcher][ag]]
+ - [[https://github.com/monochromegane/the_platinum_searcher][pt]]
+
+*Note* =ag= and =pt= are optimized to be used in a source control repository but
+they can be used in an arbitrary directory as well.
+
+By default Spacemacs will look for the first installed tool in the list =("ag",
+"pt", "ack", "grep")=. This list can be changed in the dotfile with the variable
+=dotspacemacs-search-tools=.
+
+*Beware* if you use =pt=, [[https://core.tcl.tk/tcllib/doc/trunk/embedded/www/tcllib/files/apps/pt.html][TCL parser tools]] also install a command line tool
+called =pt=.
+
+**** Searching in an arbitrary directory
+
+To use these utilities in one or several arbitrary directories:
+
+| Key Binding | Description |
+|-------------+---------------------------------------------------------------------------|
+| ~SPC s /~ | execute the first found utility (by default =ag=, =pt=, =ack= and =grep=) |
+| ~SPC s a~ | =ag= |
+| ~SPC s g~ | =grep= |
+| ~SPC s G~ | =grep= defaults to symbol at point |
+| ~SPC s k~ | =ack= |
+| ~SPC s p~ | =pt= |
+| ~SPC s L~ | open stored search buffer (stored with ~F3~ in helm search buffer) |
+
+*Note* Use the universal argument to change the search list of ~SPC s /~ to
+=ack= and =grep= (does not look for =ag= or =pt=).
+
+*Note* It is also possible to search in several directories at once by marking
+them in the helm buffer.
+
+*Pro Tip* Use ~F3~ in the helm search buffer to save the list of results to a
+buffer.
+
+**** Searching in a project
+
+To use these utilities in a project using =projectile=:
+
+| Key Binding | Description |
+|-------------+---------------------------------------------------------------------------|
+| ~SPC /~ | execute the first found utility (by default =ag=, =pt=, =ack= and =grep=) |
+| ~SPC p s a~ | =ag= |
+| ~SPC p s A~ | =ag= with symbol at point as default text |
+| ~SPC p s g~ | =grep= defaults to current region then symbol at point |
+| ~SPC p s k~ | =ack= |
+| ~SPC p s K~ | =ack= with symbol at point as default text |
+| ~SPC p s p~ | =pt= |
+| ~SPC p s P~ | =pt= with symbol at point as default text |
+
+*Pro Tip* Use ~SPC h l~ to bring back the last helm session.
+
+**** Searching the web
+
+| Key Binding | Description |
+|-------------+----------------------------------------------------------------------|
+| ~SPC s w g~ | Get Google suggestions in emacs. Opens Google results in Browser. |
+| ~SPC s w w~ | Get Wikipedia suggestions in emacs. Opens Wikipedia page in Browser. |
+
+*** Persistent highlighting
+
+=Spacemacs= uses =evil-search-highlight-persist= to keep the searched expression
+highlighted until the next search. It is also possible to clear the highlighting
+by pressing ~SPC s c~ or executing the ex command =:noh=.
+
+*** Stacking highlights
+
+With [[https://github.com/boyw165/hl-anything][hl-anything]] it is possible to
+highlight all occurrences of the word under point. The highlights can be
+stacked.
+
+| Key Binding | Description |
+|-------------+-----------------------------------------------------------------------------|
+| ~SPC h c~ | clear the highlightings |
+| ~SPC h g c~ | clear the highlightings globally (all opened buffers) |
+| ~SPC h h~ | highlight all occurrence of the word at point |
+| ~SPC h g h~ | highlight all occurrence of the word at point globally (all opened buffers) |
+| ~SPC h n~ | next highlighted occurrence |
+| ~SPC h N~ | previous highlighted occurrence |
+| ~SPC h p~ | toggle auto-highlight of the enclosing parenthesis |
+| ~SPC h r~ | restore saved highlights in the current buffer |
+| ~SPC h s~ | save current highlights |
+
+*** Highlight current symbol
+
+=Spacemacs= supports highlighting of the current symbol on demand (provided by
+the [[https://github.com/emacsmirror/auto-highlight-symbol][auto-highlight-symbol]] mode) and adds a micro-state to easily navigate and
+rename this symbol.
+
+It is also possible to change the range of the navigation on the fly to:
+ - buffer
+ - function
+ - visible area
+
+To initiate the highlighting of the current symbol under point press ~SPC s h~.
+
+Navigation between the highlighted symbols can be done with the commands:
+
+| Key Binding | Description |
+|-------------+------------------------------------------------------------------------------|
+| ~/~ | initiate navigation micro-state on current symbol and jump forwards |
+| ~#~ | initiate navigation micro-state on current symbol and jump backwards |
+| ~SPC s b~ | go to the last searched occurrence of the last highlighted symbol |
+| ~SPC s e~ | edit all occurrences of the current symbol(/) |
+| ~SPC s h~ | highlight the current symbol and all its occurrence within the current range |
+| ~SPC s R~ | change range to default (=whole buffer=) |
+
+In 'Spacemacs' highlight symbol micro-state:
+
+| Key Binding | Description |
+|---------------+---------------------------------------------------------------|
+| ~e~ | edit occurrences (*) |
+| ~n~ | go to next occurrence |
+| ~N~ | go to previous occurrence |
+| ~d~ | go to next definition occurrence |
+| ~D~ | go to previous definition occurrence |
+| ~r~ | change range (=function=, =display area=, =whole buffer=) |
+| ~R~ | go to home occurrence (reset position to starting occurrence) |
+| Any other key | leave the navigation micro-state |
+
+(*) using [[https://github.com/tsdh/iedit][iedit]] or the default implementation
+of =auto-highlight-symbol=
+
+The micro-state text in minibuffer display the following information:
+
+#+BEGIN_EXAMPLE
+ [6/11]* press (n/N) to navigate, (e) to edit, (r) to change range or (R)
+ for reset
+#+END_EXAMPLE
+
+Where = [x/y]*= is:
+ - M: the current range mode
+ - ==: whole buffer range
+ - ==: current display range
+ - ==: current function range
+ - =x=: the index of the current highlighted occurrence
+ - =y=: the total number of occurrences
+ - =*=: appears if there is at least one occurrence which is not currently visible.
+
+*** Visual Star
+
+With [[https://github.com/bling/evil-visualstar][evil-visualstar]] you can search for the next occurrence of the current
+selection.
+
+It is pretty useful combined with the [[#region-selection][expand-region]] bindings.
+
+/Note:/ If the current state is not the =visual state= then pressing ~*~ uses
+[[#auto-highlight-symbols][auto-highlight-symbol]] and its micro-state.
+
+*** Listing symbols by semantic
+
+Use =helm-semantic-or-imenu= command from =Helm= to quickly navigate between the
+symbols in a buffer.
+
+To list all the symbols of a buffer press: ~SPC s l~
+
+*** Helm-swoop
+
+This is very similar to =moccur=, it displays a =helm= buffer with all the
+occurrences of the word under point. You can then change the search query in
+real-time and navigate between them easily.
+
+You can even edit the occurrences directly in the =helm= buffer and apply the
+modifications to the buffer.
+
+| Key Binding | Description |
+|-------------+--------------------------------|
+| ~SPC s s~ | execute =helm-swoop= |
+| ~SPC s S~ | execute =helm-multi-swoop= |
+| ~SPC s C-s~ | execute =helm-multi-swoop-all= |
+
+** Editing
+
+*** Paste text
+
+**** Paste Micro-state
+
+The paste micro-state can be enabled by settings the variable
+=dotspacemacs-enable-paste-micro-state= to =t=. By default it is disabled.
+
+When the micro-state is enabled, pressing ~p~ again will replace the pasted text
+with the previous yanked (copied) text on the kill ring.
+
+For example if you copy =foo= and =bar= then press ~p~ the text =bar= will
+be pasted, pressing ~p~ again will replace =bar= with =foo=.
+
+| Key Binding | Description |
+|---------------+---------------------------------------------------------------------------|
+| ~p~ or ~P~ | paste the text before or after point and initiate the =paste= micro-state |
+| ~p~ | in micro-state: replace paste text with the previously copied one |
+| ~P~ | in micro-state: replace paste text with the next copied one |
+| ~.~ | paste the same text and leave the micro-state |
+| Any other key | leave the micro-state |
+
+**** Auto-indent pasted text
+
+By default any pasted text will be auto-indented. To paste text un-indented use
+the universal argument.
+
+It is possible to disable the auto-indentation for specific major-modes by
+adding a major-mode to the variable =spacemacs-indent-sensitive-modes= in your
+=dotspacemacs/config= function.
+
+*** Text manipulation commands
+
+Text related commands (start with ~x~):
+
+ | Key Binding | Description |
+ |-------------+---------------------------------------------------------------|
+ | ~SPC x u~ | set the selected text to lower case |
+ | ~SPC x U~ | set the selected text to upper case |
+ | ~SPC x a a~ | align region (or guessed section) using default rules |
+ | ~SPC x a r~ | align region using user-specified regexp |
+ | ~SPC x a m~ | align region at arithmetic operators (+-*/) |
+ | ~SPC x a .~ | align region at . (for numeric tables) |
+ | ~SPC x a ,~ | align region at , |
+ | ~SPC x a ;~ | align region at ; |
+ | ~SPC x a =~ | align region at = |
+ | ~SPC x a &~ | align region at & |
+ | ~SPC x a ¦~ | align region at ¦ |
+ | ~SPC x d w~ | delete trailing whitespaces |
+ | ~SPC x g l~ | set languages used by translate commands |
+ | ~SPC x g t~ | translate current word using Google Translate |
+ | ~SPC x g T~ | reverse source and target languages |
+ | ~SPC x J~ | move down a line of text (enter micro-state) |
+ | ~SPC x K~ | move up a line of text (enter micro-state) |
+ | ~SPC x t c~ | swap (transpose) the current character with the previous one |
+ | ~SPC x t w~ | swap (transpose) the current word with the previous one |
+ | ~SPC x t l~ | swap (transpose) the current line with the previous one |
+ | ~SPC x w c~ | count the number of words in the selection region |
+ | ~SPC x w C~ | count the number of occurrences per word in the select region |
+
+*** Smartparens Strict mode
+
+[[https://github.com/Fuco1/smartparens][Smartparens]] comes with a strict mode which prevents deletion of parenthesis if
+the result is unbalanced.
+
+This mode can be frustrating for novices, this is why it is not enabled by
+default.
+
+It is possible to enable it easily for /all programming modes/ with the variable
+=dotspacemacs-smartparens-strict-mode= of you =~/.spacemacs=.
+
+#+begin_src emacs-lisp
+ (setq-default dotspacemacs-smartparens-strict-mode t)
+#+end_src
+
+*** Zooming
+
+**** Text
+
+The font size of the current buffer can be adjusted with the commands:
+
+| Key Binding | Description |
+|-----------------+------------------------------------------------------------------------------|
+| ~SPC z x +~ | scale up the font and initiate the font scaling micro-state |
+| ~SPC z x -~ | scale down the font and initiate the font scaling micro-state |
+| ~SPC z x =~ | reset the font size (no scaling) and initiate the font scaling micro-state |
+| ~+~ | increase the font size |
+| ~-~ | decrease the font size |
+| ~=~ | reset the font size |
+| Any other key | leave the font scaling micro-state |
+
+Note that /only/ the text of the current buffer is scaled, the other buffers,
+the mode-line and the minibuffer are not affected. To zoom the whole content of
+a frame use the =zoom frame= bindings (see next section).
+
+**** Frame
+
+You can zoom in and out the whole content of the frame with the commands:
+
+| Key Binding | Description |
+|-----------------+------------------------------------|
+| ~SPC z f +~ | zoom in the frame content |
+| ~SPC z f -~ | zoom out the frame content |
+| ~SPC z f =~ | reset the frame content size |
+| ~+~ | zoom in |
+| ~-~ | zoom out |
+| ~=~ | reset zoom |
+| Any other key | leave the zoom frame micro-state |
+
+*** Increase/Decrease numbers
+
+=Spacemacs= uses [[https://github.com/cofi/evil-numbers][evil-numbers]] to easily increase or increase numbers.
+
+| Key Binding | Description |
+|-------------+-----------------------------------------------------------------|
+| ~SPC n +~ | increase the number under point by one and initiate micro-state |
+| ~SPC n -~ | decrease the number under point by one and initiate micro-state |
+
+In micro-state:
+
+| Key Binding | Description |
+|-----------------+------------------------------------------|
+| ~+~ | increase the number under point by one |
+| ~-~ | decrease the number under point by one |
+| Any other key | leave the micro-state |
+
+*Tips:* you can increase or decrease a value by more that once by using a prefix
+argument (ie. ~10 SPC n +~ will add 10 to the number under point).
+
+*** Spell checking
+
+Spell checking commands start with =S=:
+
+ | Key Binding | Description |
+ |-------------+----------------------------------------|
+ | ~SPC S c~ | list of corrections in a =helm= buffer |
+ | ~SPC S d~ | change dictionary language |
+ | ~SPC S n~ | go to the next spell check error |
+
+*** Region selection
+
+Vi =Visual= modes are all supported by =evil=.
+
+**** Expand-region
+
+=Spacemacs= adds another =Visual= mode via the [[https://github.com/magnars/expand-region.el][expand-region]] mode.
+
+| Key Binding | Description |
+|-------------+------------------------------------------|
+| ~SPC v~ | initiate expand-region mode then... |
+| ~v~ | expand the region by one semantic unit |
+| ~V~ | contract the region by one semantic unit |
+| ~r~ | reset the region to initial selection |
+| ~ESC~ | leave expand-region mode |
+
+**** Indent text object
+
+With [[https://github.com/cofi/evil-indent-textobject][evil-indent-textobject]] the following action can be performed in =normal
+state=:
+ - ~ii~ - Inner Indentation: the surrounding textblock with the same indentation
+ - ~ai~ - Above and Indentation: ~ii~ + the line above with a different indentation
+ - ~aI~ - Above and Indentation+: ~ai~ + the line below with a different indentation
+
+Example (=|= is the point):
+
+#+begin_src emacs-lisp
+ (while (not done) (messa|ge "All work and no play makes Jack a dull boy."))
+ (1+ 41)
+#+end_src
+
+- ~vii~ will select the line with message
+- ~vai~ will select the whole while loop
+- ~vaI~ will select the whole fragment
+
+*** Region narrowing
+
+The displayed text of a buffer can be narrowed with the commands (start with
+~n~):
+
+| Key Binding | Description |
+|-------------+-------------------------------------------|
+| ~SPC n f~ | narrow the buffer to the current function |
+| ~SPC n p~ | narrow the buffer to the visible page |
+| ~SPC n r~ | narrow the buffer to the selected text |
+| ~SPC n w~ | widen, i.e show the whole buffer again |
+
+*** Line formatting
+
+=Spacemacs= performs =go to the line below point and indent it= with ~SPC j k~.
+You may repeat this operation with =evil-repeat= if you need to indent many
+lines.
+
+Line formatting commands start with ~j~:
+
+ | Key Binding | Description |
+ |-------------+----------------------------------------------------------|
+ | ~J~ | join the current line with the next line |
+ | ~SPC j j~ | same as SPC j k but will split the current line at point |
+ | ~SPC J~ | split a quoted string or s-expression in place |
+ | ~SPC j J~ | split a quoted string or s-expression and auto-indent |
+ | ~SPC j k~ | go to next line and indent it using auto-indent rules |
+
+Used together these key bindings are very powerful to quickly reformat code.
+
+*** Replacing text with iedit
+
+=Spacemacs= uses the powerful [[https://github.com/tsdh/iedit][iedit]] mode through [[https://github.com/syl20bnr/evil-iedit-state][evil-iedit-state]] to quickly
+edit multiple occurrences of a symbol or selection.
+
+=evil-iedit-state= defines two new evil states:
+ - =iedit state=
+ - =iedit-insert state=
+
+The color code for these states is =red=.
+
+=evil-iedit-state= has also a nice integration with [[https://github.com/magnars/expand-region.el][expand-region]] for quick
+edition of the current selected text by pressing ~e~.
+
+**** iedit states key bindings
+
+***** State transitions
+
+| Key Binding | From | To |
+|-------------+------------------+--------|
+| ~SPC s e~ | normal or visual | iedit |
+| ~e~ | expand-region | iedit |
+| ~ESC~ | iedit | normal |
+| ~C-g~ | iedit | normal |
+| ~fd~ | iedit | normal |
+| ~ESC~ | iedit-insert | iedit |
+| ~C-g~ | iedit-insert | normal |
+| ~fd~ | iedit-insert | normal |
+
+To sum-up, in =iedit-insert state= you have to press ESC twice to go back to the
+=normal state=. You can also at any time press ~C-g~ or ~fd~ to return to =normal
+state=.
+
+*Note:* evil commands which switch to =insert state= will switch in
+=iedit-insert state=.
+
+***** In iedit state
+
+=iedit state= inherits from =normal state=, the following key bindings are
+specific to =iedit state=.
+
+| Key Binding | Description |
+|-------------+-----------------------------------------------------------------------------------------|
+| ~ESC~ | go back to =normal state= |
+| ~TAB~ | toggle current occurrence |
+| ~0~ | go to the beginning of the current occurrence |
+| ~$~ | go to the end of the current occurrence |
+| ~#~ | prefix all occurrences with an increasing number (SPC u to choose the starting number). |
+| ~A~ | go to the end of the current occurrence and switch to =iedit-insert state= |
+| ~D~ | delete the occurrences |
+| ~F~ | restrict the scope to the function |
+| ~gg~ | go to first occurrence |
+| ~G~ | go to last occurrence |
+| ~I~ | go to the beginning of the current occurrence and switch to =iedit-insert state= |
+| ~J~ | increase the edition scope by one line below |
+| ~K~ | increase the edition scope by one line above |
+| ~L~ | restrict the scope to the current line |
+| ~n~ | go to next occurrence |
+| ~N~ | go to previous occurrence |
+| ~p~ | replace occurrences with last yanked (copied) text |
+| ~S~ | (substitute) delete the occurrences and switch to =iedit-insert state= |
+| ~V~ | toggle visibility of lines with no occurrence |
+| ~U~ | Up-case the occurrences |
+| ~C-U~ | down-case the occurrences |
+
+*Note:* ~0~, ~$~, ~A~ and ~I~ have the default Vim behavior when used outside of
+an ~occurrence~.
+
+***** In iedit-insert state
+
+| Key Binding | Description |
+|-------------+---------------------------|
+| ~ESC~ | go back to =iedit state= |
+| ~C-g~ | go back to =normal state= |
+
+**** Examples
+- manual selection of several words then replace: ~v w w SPC s e S "toto" ESC ESC~
+- append text to a word on two lines: ~v i w SPC s e J i "toto" ESC ESC~
+- substitute symbol /with expand-region/: ~SPC v v e S "toto" ESC ESC~
+- replace symbol with yanked (copied) text /with expand region/: ~SPC v
+ e p ESC ESC~
+
+*** Replacing text in several files
+
+Replacing an occurrence of text in several files can be performed via [[https://github.com/syohex/emacs-helm-ag][helm-ag]].
+
+Say you want to replace all =foo= occurrences by =bar= in your current
+project:
+ - initiate a search with ~SPC /~
+ - enter in edit mode with ~C-c C-e~
+ - go to the occurrence and enter in =iedit state= with ~SPC s e~
+ - edit the occurrences then leave the =iedit state=
+ - press ~C-c C-c~
+
+*Note* in Spacemacs, =helm-ag= despite its name works with =ack= and =pt= as
+well.
+
+*** Commenting
+
+Comments are handled by [[https://github.com/redguardtoo/evil-nerd-commenter][evil-nerd-commenter]], it's bound to the following keys.
+
+ | Key Binding | Description |
+ |-------------+--------------------|
+ | ~SPC ;~ | comment operator |
+ | ~SPC c i~ | comment invert |
+ | ~SPC c l~ | comment lines |
+ | ~SPC c p~ | comment paragraphs |
+ | ~SPC c r~ | comment region |
+ | ~SPC c t~ | comment to line |
+ | ~SPC c y~ | comment and yank |
+
+*Tips:* To comment efficiently a block of line use the combo ~SPC ; SPC l~
+
+*** Deleting files
+
+Deletion is configured to send deleted files to system trash.
+
+On OS X the =trash= program is required. It can be installed with [[http:www.brew.sh][homebrew]] with
+the following command:
+
+#+begin_src sh
+ $ brew install trash
+#+end_src
+
+To disable the trash you can set the variable =delete-by-moving-to-trash= to
+=nil= in your =~/.spacemacs=.
+
+*** Editing Lisp code
+
+Edition of lisp code is provided by [[https://github.com/syl20bnr/evil-lisp-state][evil-lisp-state]].
+
+Commands will set the current state to =lisp state= where different commands
+combo can be repeated without pressing on ~SPC m~.
+
+When in =lisp state= the color of the mode-line changes to pink.
+
+Examples:
+ - to slurp three times while in normal state: ~SPC k 3 n~
+ - to wrap a symbol in parenthesis then slurping two times: ~SPC k w 2 n~
+
+*Note* The =lisp state= commands are available in /any/ modes! Try it out.
+
+**** Lisp Key Bindings
+
+***** Lisp state key bindings
+
+These commands automatically switch to =lisp state=.
+
+| Key Binding | Function |
+|-------------+---------------------------------------------------------------------|
+| ~SPC k %~ | evil jump item |
+| ~SPC k :~ | ex command |
+| ~SPC k (~ | insert expression before (same level as current one) |
+| ~SPC k )~ | insert expression after (same level as current one) |
+| ~SPC k $~ | go to the end of current sexp |
+| ~SPC k ` k~ | hybrid version of push sexp (can be used in non lisp dialects) |
+| ~SPC k ` p~ | hybrid version of push sexp (can be used in non lisp dialects) |
+| ~SPC k ` s~ | hybrid version of slurp sexp (can be used in non lisp dialects) |
+| ~SPC k ` t~ | hybrid version of transpose sexp (can be used in non lisp dialects) |
+| ~SPC k 0~ | go to the beginning of current sexp |
+| ~SPC k a~ | absorb expression |
+| ~SPC k b~ | forward barf expression |
+| ~SPC k B~ | backward barf expression |
+| ~SPC k c~ | convolute expression |
+| ~SPC k ds~ | delete symbol |
+| ~SPC k Ds~ | backward delete symbol |
+| ~SPC k dw~ | delete word |
+| ~SPC k Dw~ | backward delete word |
+| ~SPC k dx~ | delete expression |
+| ~SPC k Dx~ | backward delete expression |
+| ~SPC k e~ | unwrap current expression and kill all symbols after point |
+| ~SPC k E~ | unwrap current expression and kill all symbols before point |
+| ~SPC k h~ | previous symbol |
+| ~SPC k H~ | go to previous sexp |
+| ~SPC k i~ | switch to =insert state= |
+| ~SPC k I~ | go to beginning of current expression and switch to =insert state= |
+| ~SPC k j~ | next closing parenthesis |
+| ~SPC k J~ | join expression |
+| ~SPC k k~ | previous opening parenthesis |
+| ~SPC k l~ | next symbol |
+| ~SPC k L~ | go to next sexp |
+| ~SPC k p~ | paste after |
+| ~SPC k P~ | paste before |
+| ~SPC k r~ | raise expression (replace parent expression by current one) |
+| ~SPC k s~ | forwared slurp expression |
+| ~SPC k S~ | backward slurp expression |
+| ~SPC k t~ | transpose expression |
+| ~SPC k u~ | undo |
+| ~SPC k U~ | got to parent sexp backward |
+| ~SPC k C-r~ | redo |
+| ~SPC k v~ | switch to =visual state= |
+| ~SPC k V~ | switch to =visual line state= |
+| ~SPC k C-v~ | switch to =visual block state= |
+| ~SPC k w~ | wrap expression with parenthesis |
+| ~SPC k W~ | unwrap expression |
+| ~SPC k y~ | copy expression |
+
+***** Emacs lisp specific key bindings
+
+| Key Binding | Function |
+|-------------+--------------------------------------------|
+| ~SPC m e $~ | go to end of line and evaluate last sexp |
+| ~SPC m e b~ | evaluate buffer |
+| ~SPC m e c~ | evaluate current form (a =def= or a =set=) |
+| ~SPC m e e~ | evaluate last sexp |
+| ~SPC m e f~ | evaluate current defun |
+| ~SPC m e l~ | go to end of line and evaluate last sexp |
+| ~SPC m e r~ | evaluate region |
+
+
+| Key Binding | Function |
+|-------------+----------------------------------------------------|
+| ~SPC m g g~ | go to definition |
+| ~SPC m h h~ | describe elisp thing at point (show documentation) |
+| ~SPC m t b~ | execute buffer tests |
+| ~SPC m t q~ | ask for test function to execute |
+
+** Managing projects
+
+Projects in =Spacemacs= are managed with [[https://github.com/bbatsov/projectile][projectile]]. In =projectile= projects
+are defined implicitly, for instance the root of a project is found when a
+=.git= repository or =.projectile= file is encountered in the file tree.
+
+=Helm= is used whenever it is possible.
+
+To search in a project see [[#searching-in-a-project][project searching]].
+
+=projectile= commands start with p:
+
+ | Key Binding | Description |
+ |-------------+-------------------------------------------------------|
+ | ~SPC /~ | search in project with the best search tool available |
+ | ~SPC p !~ | run shell command in root |
+ | ~SPC p &~ | run async shell command in root |
+ | ~SPC p s a~ | run =ag= |
+ | ~SPC p s k~ | run =ack= |
+ | ~SPC p b~ | switch to project buffer |
+ | ~SPC p c~ | compile project using =projectile= |
+ | ~SPC p d~ | find directory |
+ | ~SPC p D~ | open project root in =dired= |
+ | ~SPC p f~ | find file |
+ | ~SPC p s g~ | run =grep= |
+ | ~SPC p h~ | find file using =helm= |
+ | ~SPC p I~ | invalidate the projectile cache |
+ | ~SPC p k~ | kill all project buffers |
+ | ~SPC p o~ | run =multi-occur= |
+ | ~SPC p p~ | switch project |
+ | ~SPC p R~ | regenerate the project's =etags=/=gtags= |
+ | ~SPC p r~ | replace a string |
+ | ~SPC p s~ | see [[#searching-in-a-project][search in project]] |
+ | ~SPC p t~ | open =NeoTree= in =projectile= root |
+ | ~SPC p T~ | find test files |
+ | ~SPC p v~ | open project root in =vc-dir= or =magit= |
+ | ~SPC p y~ | find tags |
+
+** Registers
+
+Access commands to the various registers start with =r=:
+
+| Key Binding | Description |
+|-------------+------------------------------------|
+| ~SPC r e~ | show evil yank and named registers |
+| ~SPC r m~ | show marks register |
+| ~SPC r r~ | show helm register |
+| ~SPC r y~ | show kill ring |
+
+** Errors handling
+
+=Spacemacs= uses [[https://github.com/flycheck/flycheck][Flycheck]] to gives error feedback on the fly. The checks are
+only performed at save time by default.
+
+Errors management commands (start with ~e~):
+
+ | Key Binding | Description |
+ |-------------+------------------------------------------------|
+ | ~SPC e c~ | clear all errors |
+ | ~SPC e f~ | toggle flycheck |
+ | ~SPC e l~ | display the =flycheck= list of errors/warnings |
+ | ~SPC e n~ | go to the next error |
+ | ~SPC e p~ | go to the previous error |
+
+Custom fringe bitmaps:
+
+| Symbol | Description |
+|--------------------------+-------------|
+| [[file:img/dot-error.png]] | Error |
+| [[file:img/dot-warning.png]] | warning |
+| [[file:img/dot-info.png]] | Info |
+
+** Compiling
+
+=Spacemacs= binds a few commands to support compiling a project.
+
+ | Key Binding | Description |
+ |-------------+--------------------------------|
+ | ~SPC c c~ | use =helm-make= via projectile |
+ | ~SPC c C~ | compile |
+ | ~SPC c r~ | recompile |
+
+** Modes
+
+*** Major Mode leader key
+
+Key bindings specific to the current =major mode= start with ~SPC m~. For
+convenience a shortcut key called the major mode leader key is set by default on
+~,~ which saves one precious keystroke.
+
+It is possible to change the major mode leader key by defining the variable
+=dotspacemacs-major-mode-leader-key= in your =~/.spacemacs=. For example to
+setup the key on tabulation:
+
+#+begin_src emacs-lisp
+ (setq-default dotspacemacs-major-mode-leader-key "")
+#+end_src
+
+*** Helm
+
+=Spacemacs= add =hjkl= navigation to =helm= buffers:
+
+ | Key Binding | Description |
+ |-------------+---------------------|
+ | ~C-h~ | go to previous page |
+ | ~C-j~ | go to previous item |
+ | ~C-k~ | go to next item |
+ | ~C-l~ | go to next page |
+
+*** Python
+
+Writing python code with spacemacs is supported by python contribution. Please
+see [[../contrib/!lang/python][python contribution]] documentation for detail.
+
+*** JavaScript
+
+More featured JavaScript support is provided by the javascript contribution.
+Please see [[../contrib/!lang/javascript][javascript contribution]] documentation for detail.
+
+*** HTML and CSS
+
+HTML contribution provides support for editing HTML, CSS, Scss and Less files.
+Please see [[../contrib/!lang/html][html contribution]] documentation for detail.
+
+** Emacs Server
+
+=Spacemacs= starts a server at launch. This server is killed whenever you close
+your Emacs windows.
+
+*** Connecting to the Emacs server
+
+You can open a file in Emacs from the terminal using =emacsclient=. Use
+=emacsclient -c= to open the file in Emacs GUI. Use =emacsclient -t= to open the
+file in Emacs within the terminal.
+
+If you want your Linux/OS X system to use Emacs by default for any prompt, use
+=export EDITOR="emacsclient -c"= in your shell configuration.
+
+Note that if you're on OS X, you may have to refer to the emacsclient that comes
+with your GUI Emacs, e.g. =export
+EDITOR="/Applications/Emacs.app/Contents/MacOS/bin/emacsclient -c"=.
+
+Tip: Remember to use ~:wq~ or ~C-x #~ after you are done editing the file in
+Emacs.
+
+See [[https://www.gnu.org/software/emacs/manual/html_node/emacs/Emacs-Server.html][Emacs as a Server]] in the official Emacs manual for more details.
+
+** Keeping the server alive
+
+It is possible to keep the server alive when you close Emacs by setting the
+variable =dotspacemacs-persistent-server= to =t= in your =~./spacemacs=.
+
+#+begin_src emacs-lisp
+ (setq-default dotspacemacs-persistent-server t)
+#+end_src
+
+When this variable is set to =t=, the only way to quit Emacs /and/ kill the
+server is to use the following bindings:
+
+| Keybinding | Description |
+|------------+--------------------------------------------------------------------|
+| ~SPC q q~ | Quit Emacs and kill the server, prompt for changed buffers to save |
+| ~SPC q Q~ | Quit Emacs and kill the server, lose all unsaved changes. |
+| ~SPC q s~ | Save the buffers, quit Emacs and kill the server |
+| ~SPC q z~ | Kill the current frame |
+
+** Troubleshoot
+
+*** Loading fails
+
+If any errors happen during the loading the mode-line will turn red and the
+errors should appear inline in the startup buffer. Spacemacs should still be
+usable, if it is not the case then restart Emacs with =emacs --debug-init= and
+open a [[https://github.com/syl20bnr/spacemacs/issues][Github issue]] with the backtrace.
+
+*** I have no file ~/.spacemacs
+
+You have to manually copy the =~/.emacs.d/core/templates/.spacemacs.template=
+file to =~/.spacemacs=
+
+* Achievements
+
+** Issues
+
+| Achievements | Account |
+|---------------------------+--------------|
+| [[https://github.com/syl20bnr/spacemacs/pull/100][100th issue (PR)]] | [[https://github.com/danielwuz][danielwuz]] |
+| [[https://github.com/syl20bnr/spacemacs/issues/200][200th issue (question)]] | [[https://github.com/justrajdeep][justrajdeep]] |
+| [[https://github.com/syl20bnr/spacemacs/pull/300][300th issue (PR)]] | [[https://github.com/danielwuz][danielwuz]] |
+| [[https://github.com/syl20bnr/spacemacs/pull/400][400th issue (PR)]] | [[https://github.com/CestDiego][CestDiego]] |
+| [[https://github.com/syl20bnr/spacemacs/pull/500][500th issue (PR)]] | [[https://github.com/bjarkevad][bjarkevad]] |
+| [[https://github.com/syl20bnr/spacemacs/pull/600][600th issue (PR)]] | [[https://github.com/bjarkevad][bjarkevad]] |
+| [[https://github.com/syl20bnr/spacemacs/pull/700][700th issue (enhancement)]] | [[https://github.com/jcpetkovich][jcpetkovich]] |
+| [[https://github.com/syl20bnr/spacemacs/pull/800][800th issue (PR)]] | [[https://github.com/laat][ryansroberts]] |
+| [[https://github.com/syl20bnr/spacemacs/pull/900][900th issue (PR)]] | [[https://github.com/jcpetkovich][jcpetkovich]] |
+| [[https://github.com/syl20bnr/spacemacs/pull/1000][1000th issue (PR)]] | [[https://github.com/tuhdo][tuhdo]] |
+
+** Merged Pull Requests
+
+| Achievements | Account |
+|--------------------+------------|
+| [[https://github.com/syl20bnr/spacemacs/pull/228][100th pull request]] | [[https://github.com/bru][bru]] |
+| [[https://github.com/syl20bnr/spacemacs/pull/418][200th pull request]] | [[https://github.com/smt][smt]] |
+| [[https://github.com/syl20bnr/spacemacs/pull/617][300th pull request]] | [[https://github.com/BrianHicks][BrianHicks]] |
+| [[https://github.com/syl20bnr/spacemacs/pull/806][400th pull request]] | [[https://github.com/cpaulik][cpaulik]] |
+| [[https://github.com/syl20bnr/spacemacs/pull/993][500th pull request]] | [[https://github.com/tuhdo][tuhdo]] |
+| [[https://github.com/syl20bnr/spacemacs/pull/1205][600th pull request]] | [[https://github.com/trishume][trishume]] |
+
+** Stars, forks and watchers
+
+| Achievements | Account |
+|---------------+-----------------|
+| 100th watcher | [[https://github.com/adouzzy][adouzzy]] |
+| 100th fork | [[https://github.com/balajisivaraman][balajisivaraman]] |
+| 200th fork | [[https://github.com/alcol80][alcol80]] |
+| 300th fork | [[https://github.com/mlopes][mlopes]] |
+| 100th star | [[https://github.com/Jackneill][Jackneill]] |
+| 200th star | [[https://github.com/jb55][jb55]] |
+| 400th star | [[https://github.com/dbohdan][dbohdan]] |
+| 600th star | [[https://github.com/laat][laat]] |
+| 700th star | [[https://github.com/kendall][kendall]] |
+| 800th star | [[https://github.com/urso][urso]] |
+| 900th star | [[https://github.com/luisgerhorst][luisgerhorst]] |
+| 1000th star! | [[https://github.com/rashly][rashly]] |
+
+** Specials
+
+| Achievements | Account |
+|----------------------------------------+--------------|
+| [[https://github.com/syl20bnr/spacemacs/pull/19][First contribution]] | [[https://github.com/trishume][trishume]] |
+| [[https://github.com/syl20bnr/spacemacs/commit/e802027d75d0c0aed55539b0da2dfa0df94dfd39][First contribution layer]] | [[https://github.com/trishume][trishume]] |
+| [[http://oli.me.uk/2014/11/06/spacemacs-emacs-vim/][First blog article on Spacemacs]] | [[https://github.com/Wolfy87][Wolfy87]] |
+| [[https://github.com/syl20bnr/spacemacs/commit/7b44a56263049482ed540ed6815a295633ffe9d1][First contributed banner]] | [[https://github.com/chrisbarrett][chrisbarrett]] |
+| The Gunner (made 18 PRs in a row) | [[https://github.com/ralesi][ralesi]] |
+| The Saint (unlocked the holy-mode) | [[https://github.com/trishume][trishume]] |
+| The Artist (made the spacemacs logo) | [[https://github.com/nashamri][nashamri]] |
+| The Meme Master (made the doge banner) | [[https://github.com/chrisbarrett][chrisbarrett]] |
+| The Helm captain (see [[http://tuhdo.github.io/helm-intro.html][here]]) | [[https://github.com/tuhdo][tuhdo]] |
+
+* Thank you
+
+[[#using-configuration-layers][Jokes aside]], thank you Richard for this great piece of software.
+
+Thank you to all the contributors and the whole Emacs community from core
+developers to elisp hackers!
diff --git a/spacemacs/extensions/helm-spacemacs/helm-spacemacs.el b/spacemacs/extensions/helm-spacemacs/helm-spacemacs.el
index 0480548fb..0575984c8 100644
--- a/spacemacs/extensions/helm-spacemacs/helm-spacemacs.el
+++ b/spacemacs/extensions/helm-spacemacs/helm-spacemacs.el
@@ -94,20 +94,20 @@
(when (or (equal file-extension "md")
(equal file-extension "org"))
(push (f-relative file-path spacemacs-docs-directory) result)))
- ;; delete DOCUMENTATION.md to make it the first guide
- (delete "DOCUMENTATION.md" result)
- (push "DOCUMENTATION.md" result)
+ ;; delete DOCUMENTATION.org to make it the first guide
+ (delete "DOCUMENTATION.org" result)
+ (push "DOCUMENTATION.org" result)
;; give each document an appropriate title
(mapcar (lambda (r)
(cond
- ((string-equal r "CONTRIBUTE.md")
+ ((string-equal r "CONTRIBUTE.org")
`("How to contribute to Spacemacs" . ,r))
- ((string-equal r "CONVENTIONS.md")
+ ((string-equal r "CONVENTIONS.org")
`("Spacemacs conventions" . ,r))
- ((string-equal r "DOCUMENTATION.md")
+ ((string-equal r "DOCUMENTATION.org")
`("Spacemacs starter guide" . ,r))
- ((string-equal r "HOWTOs.md")
+ ((string-equal r "HOWTOs.org")
`("Quick HOW-TOs for Spacemacs" . ,r))
((string-equal r "VIMUSERS.org")
`("Vim users migration guide" . ,r))