This is an introduction to Spacemacs, an extensible text editor and IDE reimagining Emacs with a heavy touch of Vim. Whether Spacemacs is a better choice than Emacs is a matter of preference, but for me it comes down to my brain and fingers being much more compatible with remembering and performing key sequences, than simultaneous key combinations
At first Spacemacs, like Emacs, is to many as overwhelming as it is exciting - there are so many options, it’s hard to know where to begin! Unfortunately many tutorials out there are not very helpful in this regard, since they either assume prior familiarity with Emacs, or branch out wide and deep too quickly.
So in this post the goal is modest: To use Spacemacs as a simple text editor, become comfortable navigating it at a basic level, and provide a solid grounding to gradually build our Spacemacs skills on.
To install Spacemacs we first need to install a recent version of Emacs. In Ubuntu, this can be done with:
sudo add-apt-repository ppa:kelleyk/emacs sudo apt update sudo apt install emacs26
Next we need to replace the Emacs configuration with Spacemacs - essentially, Spacemacs is nothing more than a ready-to-use configuration for Emacs. Back up your
~/.emacs.d directory to, for instance,
~/.emacs.d.bkp and clone the Spacemacs repo to its location instead:
git clone https://github.com/syl20bnr/spacemacs ~/.emacs.d
When you first launch Emacs, Spacemacs will ask you some questions. Choose ‘vim’, ‘spacemacs’ and ‘helm’ when prompted, and wait until everything is fully installed.
Create and write a buffer
When all packages are installed, you will be greeted by the home screen. This offers you some quick links and some information, but you can ignore it for now. Just maximise the window so it covers the entire screen.
Now let’s start the magic: press the spacebar (
SPC). At the bottom of the screen you will see a menu appear:
This presents you with your further choices.
SPC was the leader key for activating the menu, any key you press after this will be used to go deeper into the menu. Press
b - as you can see this is short for ‘buffers’. The next level of the menu appears - now press
N for ‘new-empty-buffer’. This sequence of keys we can write as
N. If you ever find yourself stuck in a menu you don’t want to be in, pressing
CTRL-g (together, not as a sequence) will exit the menu.
All right, you should find yourself presented with a mostly blank screen now - a new, empty buffer. A buffer, is that a file? Not yet! It’s the current state of our text, which we can later save to a file.
Let’s type something. During installation we opted to use Vim keybindings, also known as ‘evil mode’ in Emacs. This means we are using modal editing - keypresses will do something different depending on the state the editor is in. When starting the buffer we are in Normal state, which is meant for navigating, copying and deleting text, not for typing it. You can tell by the orange color around the number ‘1’ in the bottom left corner (the window number, but for now we have just one window). The status bar at the bottom is called the mode-line, displaying among other things information on the editor state.
To start typing, we must switch to the Insert state. When in Normal state, pressing
i will achieve this. The cursor now changes from a yellow block to a vertical green line, and the colour around the window number is now green.
Type a few sentences, preferably on different lines, then go back to Normal state by pressing
ESC. Now you can use the basic Vim navigation keys for going up and down a line (
j) and back or forth a character (
To save the buffer to a file we have two options. Either we save the file in Vim-style, using Vim’s command key
:. For instance,
:w ~/tmp_spacemacs will write the file to your home directory (do not give the file an extension for now). The second option is to save the file Spacemacs-style, by pressing
SPC, which brings up the menu again. Press
files, and then
save-buffer. Since this is a new file, you will have to type the full path now. The Helm completion framework (remember we selected this during installation?) will present you with possible options, which you can complete with
TAB. Upon saving, the asterisk (unsaved changes in buffer) in the mode-line changes to a dash (all changes saved).
Now that we have written the buffer to a file, we can close it.
d will execute the command
kill-this-buffer, and bring us back to the home screen.
First things first now - you will probably want to change the way Spacemacs looks! You can preview installed themes with
s. Personally I like
misterioso, so let’s select that one for now. To make it permanent however, we need to set it in the configuration.
The user configuration is found in
~/.spacemacs, also called the ‘dotfile’. You can try opening this file like any other file using
f - or you can directly use the shortcut,
What you will see is not your typical JSON, YAML or TOML configuration file - this is actual code setting variables to values. To be more precise, this is Emacs Lisp, the programming language in which Emacs is largely written. This is part of what makes Emacs such a popular environment, it is fully configurable because you can interact with it in its own language. For now though, let’s ignore the language itself and look at what we can configure.
Search for the
dotspacemacs-themes variable. When in Normal state, to search you can press
/, type the string to find, and press return (
n will take you to the next match,
N will take you one back. To remove the highlighting, execute
:noh (no highlighting). Add
misterioso to the beginning of the list, until it looks like this:
dotspacemacs-themes '(misterioso spacemacs-dark spacemacs-light)
Congratulations, you are now an Emacs Lisp programmer! Save the file with
s, as before. Then restart Spacemacs to let the changes take effect, using
r. It should have the new theme, and automatically re-open the
Packages and layers
Emacs can be extended using packages which can be installed from a repository - MELPA being the default choice. Spacemacs offers additional convenience, however, by defining layers which bundle and configure a number of packages for a single purpose.
dotspacemacs-configuration-layers variable in the configuration lists the activated layers. Let’s activate the
markdown layer by uncommenting it from the list. This will enable features useful when working on Markdown files.
s) and kill (
d) the buffer, then restart again (
r). You will see Emacs installing the necessary packages connected to the layer.
Major and minor modes
Now let us open the plain text file again. You can use
f to Find Files to open in a new buffer, or
b to choose a buffer to display, including recently closed ones.
Once the buffer is open, rename it to
R. You will see something change to the mode-line at the bottom - the file is now automatically recognised as Markdown!
‘Markdown’ is now the major mode of this buffer. This enables markdown-specific syntax highlighting, and a plethora of Markdown-specific keybindings and commands. To access them, while in Normal state press the leader key for major mode commands,
,. The familiar navigation menu appears again, but now limited to Markdown commands. Choose for instance
l, and enter the URL and text of a link. The markdown code will be inserted into the buffer.
A buffer has only one major mode, but can have multiple minor modes which offer additional functionality, and are not necessarily specific to certain types of files. For instance,
n will toggle line number mode, which will display line numbers on the left side of your buffer. This minor mode does not have an indicator in the mode-line, but others do. For instance,
w will toggle whitespace mode, making whitespace characters visible, and adding a ‘w’ indicator to the mode-line.
Executing any function
You may have noticed by now that any command you give to Emacs, actually executes an Emacs Lisp function. For instance,
kill-buffer. Not all functions are bound to keys, however - or sometimes they may be buried too deep into menus to find easily.
Luckily we can also execute functions by name. Press
SPC, and you will be able to type the name of any function and execute it. In Emacs documentation you will often see this referred to as
M-x, after its Emacs shortcut Meta/Alt-x. Try typing
fundamental-mode and press
RET to confirm. Suddenly your markdown syntax highlighting will disappear, because we have switched back to the most basic major mode, Fundamental. Do
RET to return to Markdown major mode.
Every command in Spacemacs is therefore easily searchable. And if there is a key sequence bound to a command, it will be displayed.
You already know how to open files and buffers, save and close them, and switch between them. But what if you want to display multiple files at the same time? For this we need windows.
v will create a new window to the right - explore the menu for other options. Initially this will be set to the same buffer as the left window, and your cursor will still be active in the first window. To switch to the second window, press
2. To open another buffer in this window, use
b as before.
To close the window again, press
d. Note that this does not close the buffer displayed in the window! The buffer will remain active and accessible - use
b to select it for displaying in the first window.
Exiting undesired states
Nothing is so frustrating as an interface becoming unresponsive to what you really want to do, so what can we do when accidental key combinations get us stuck in a place we don’t want to be in?
Earlier we discussed
CTRL-g, to close any unwanted menu, and the switching between Normal and Insert states using
i. But there are other states you might find yourself in accidentally. For instance you might have pressed
V while in Normal state and found yourself in Visual state, selecting text with the window number now grey.
ESC will return you to Normal state.
More puzzling might be Emacs state, where the colour around your window number turns to light blue - and you are stuck on default Emacs rather than evil mode keybindings, which you probably don’t know. Often this happens when accessing Emacs documentation buffers.
CTRL-z will return you to Normal state.
Motion state will turn the window number colour to purple. You will be able to use the
SPC leader key here and move around using Vim keybindings, but won’t be able to enter Insert mode. The home screen for instance uses Motion state by default, because you are not supposed to edit it. To exit this state, if you would find yourself in it accidentally, execute
Lisp state will turn the window number colour to pink. This is harder to find yourself in by mistake, but if it happens, just press
Hopefully this brief overview will have given you all the tools to navigate Spacemacs. I recommend doing the Evil mode tutorial (
t) for learning more Vim keybindings if you are unfamiliar with them. These are incredibly powerful, and replicated in many IDEs. Don’t overwhelm yourself by learning them all at once though, focus on the basic ones and pick up new bindings one by one as you become more comfortable using Spacemacs!