First steps in Spacemacs

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.

Install

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 SPC b 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 (k, j) and back or forth a character (h, l).

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 f for files, and then s for 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. SPC b d will execute the command kill-this-buffer, and bring us back to the home screen.

Configuration

First things first now - you will probably want to change the way Spacemacs looks! You can preview installed themes with SPC T 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 SPC f f - or you can directly use the shortcut, SPC f e d.

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 (RET). 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 :w or SPC b s, as before. Then restart Spacemacs to let the changes take effect, using SPC q r. It should have the new theme, and automatically re-open the .spacemacs buffer.

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.

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

Save (SPC f s) and kill (SPC b d) the buffer, then restart again (SPC q 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 SPC f f to Find Files to open in a new buffer, or SPC b b to choose a buffer to display, including recently closed ones.

Once the buffer is open, rename it to tmp_spacemacs.md, using SPC f 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 i 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, SPC t 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, SPC t 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 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 SPC SPC markdown-mode 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.

Windows

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.

SPC w 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 SPC 2. To open another buffer in this window, use SPC f f or SPC b b as before.

To close the window again, press SPC w d. Note that this does not close the buffer displayed in the window! The buffer will remain active and accessible - use SPC b 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 discussedCTRL-g, to close any unwanted menu, and the switching between Normal and Insert states using ESC and i. But there are other states you might find yourself in accidentally. For instance you might have pressed v or 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 SPC SPC evil-normal-state RET.

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

Conclusions

Hopefully this brief overview will have given you all the tools to navigate Spacemacs. I recommend doing the Evil mode tutorial (SPC h 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!