
Configure Emacs Writing Studio

Peter Prevos |
2762 words | 13 minutes
Share this content
Commercial software is usually good at doing one thing really well. You write documents in LibreOffice Writer or Google Docs. You create presentation slides in PowerPoint or Keynote and manage tasks with Trello or Todoist. If you are lucky, the developers let you change the configuration to customise the software’s behaviour and optimise your workflow. In most cases, however, you are bound by the choices the developers have made for you. Linking the information that is held in these programs can be problematic. Emacs does not have such limitations. You do almost all tasks in one program, but you have to configure it to make it behave the way you want.
This article explains how to configure Emacs to transform it into a personalised productivity suite for authors. Please note that this configuration assumes that you are using the latest version of Emacs, which at the time of writing is 29.4.
This article is part of Emacs Writing Studio, a book that explains how to use Emacs to undertake research and write and publish articles, books, and websites. Emacs Writing Studio is also available as an e-book from your favourite retailer.
Emacs Writing Studio
A comprehensive guide for writers seeking to streamline their workflow using Emacs. The book covers everything from organising ideas and writing distraction-free to publishing in multiple formats. It’s perfect for both beginners and experienced Emacs users, offering practical tips and a tailored configuration to enhance your writing process.
The source files of the book and EWS configuration are also freely available on GitHub.
Configuring Emacs
A vanilla version of Emacs has a lot of functionality out of the box and you could easily write a book without any configuration. But to truly leverage its capabilities, Emacs needs external packages and additional configuration.
Some Emacs users use pre-configured systems, such as Doom Emacs, or Spacemacs, or one of the other starter kits. While these configurations are helpful, they sometimes provide ‘everything but the kitchen sink’.
On the other side of the spectrum, you can configure your system from scratch, which can become a productivity sink as you wade your way through highly technical instructions written by experts.
Emacs Writing Studio (EWS) seeks the golden mean by providing a minimal configuration. The main objective of EWS is to get you started writing in Emacs and generate sufficient curiosity for you to further develop your skills and keep improving your configuration.
The Initialisation File
When you start Emacs, it loads the initialisation file, or init file in short. This file contains Lisp code that configures Emacs and loads additional packages.
The first time you start Emacs, it will create the configuration directory. The init file lives in this location, which will also contain the packages and other files needed to personalise your system.
Emacs looks for a file called .emacs
, .emacs.el
or init.el
. The dot in front of the file means that it is hidden from view to prevent cluttering your directories. The location of the configuration folder depends on your operating system and Emacs version. The Emacs help functionality can tell you where to store the init.el
file.
Type C-h v
(describe-variable
), and type user-emacs-directory
and Enter (or user-e TAB
) in the minibuffer at the bottom of the screen. The help buffer that now appears provides the correct folder name, for example "Its value is "~/.config/emacs/
".
You can now visit (open or create) the init.el
file in your Emacs directory and copy and write your configuration. Your init file will become active after you restart Emacs (use M-x restart-emacs
).
You can download the complete EWS configuration file from GitHub and save it in the user directory. Copy the init.el
and ews.el
files to your user directory. The first file contains the Emacs configuration and the second file contains bespoke EWS functions.
Please note that when you start Emacs with the Emacs Writing Studio configuration for the first time, Emacs will download several packages from their online repositories and compile them. This process might generate scary-looking text, but you can ignore it, as it only appears when you install new packages.
Emacs Lisp
While using commercial software is like renting a fully furnished house, using Emacs is more like buying a new empty house. Your new digital home needs some paint and new carpets, which means you need to configure Emacs to make it your digital home.
Commercial software provides graphical menus to define how the software operates. Like the examples below, you might tick a box, select an item in a list, or enter a value in a text box to configure the program to your wishes.
Being a plain text program, Emacs doesn't use a graphical interface but a programming language called Lisp. The code below is equivalent to the graphical user interface shown above.
(setq-default inhibit-startup-message t
initial-scratch-message "Hello world"
cursor-type 'bar)
Although the text-based method is superficially more complex than ticking boxes, writing text and selecting a drop-down list, it is far more potent than a graphical interface. Writing code to configure your computer may not seem user-friendly initially because we are used to the graphical interface. However, once you learn how to write simple Emacs Lisp programs, you will find that Emacs is the most user-friendly system because it gives you so much power over your computer. But with that power comes great responsibility and a steep learning curve.
Using Emacs Lisp is the epitome of ease of use. You control how your computer behaves instead of the computer controlling your behaviour.
A Lisp program consists of expressions, which are statements enclosed in parentheses. Each expression starts with the name of a function (setq-default
), followed by some parameters.
The setq-default
function is commonly used to set the default value of a parameter. For example, (setq-default inhibit-startup-message t)
has the same effect as putting a checkmark in the inhibit-startup-message box, while inhibit-startup-message nil
is the same as removing the checkmark in that box. The expression in this example determines whether Emacs displays a startup message when you open it for the first time.
You don’t have to learn to program Lisp to configure Emacs. The examples on this site provide sensible defaults to turn vanilla Emacs into your personal writing studio. Each article offers a thoroughly documented configuration. Many Emacs users share their configuration with the community so that you can copy their code. The copy-and-paste method is a shortcut to learning more about Emacs Lisp because you can change the settings and examine the results of your changes.
The Emacs Writing Studio Configuration
Checking external software requirements
Emacs is not just a text editor but a Lisp computing environment that can interface with command line tools. For Emacs Wring Studio to function fully, it needs to have access to a bunch of external programs, which are listed in the relevant articles.
A bespoke Emacs Writing Studio function (ews-missing-executables
) tests wether the relevant external executable files are available. This function displays an error message into the *Messages*
buffer if it cannot find one or more of the external tools. Emacs will still work, but some functionality might be unavailable.
Each article in the Emacs Writing Studio series explains which external software is required an how to obtain it. The core functionality of Emacs will work fine without these, but some specialised tasks require assistance from this software.
soffice
(LibreOffice): View and create office documentszip
: Unpack ePub documentspdftotext
(poppler-utils): Convert PDF to textdjvu
(DjVuLibre): View DjVu filescurl
: Reading RSS feedsdot
(GraphViz): Create note network diagrams-
Convert image files
convert
(ImageMagick)gm
(GraphicsMagick)
-
latex
(TexLive, MacTex or MikTeX): Preview LaTex and export Org to PDFdivpng
: Part of LaTeX
hunspell
: Spellcheck. Also requires a hunspell dictionary-
Search inside files
grep
ripgrep
: Faster alternative for grep
-
View PDF files
gs
(GhostScript): View PDF filesmutool
(MuPDF): View PDF files
-
Play music
mpg321
,ogg123
(vorbis-tools),mplayer
,mpv
,vlc
Loading Packages
The Emacs base system has extensive functionality, but you can extend its capability with external packages. Many people write packages in Emacs Lisp to improve or enhance what the system can do. You can also download Lisp files directly from GitHub or other sources. Developers of these packages often share their work through public package repositories, which are websites that let you easily download and install packages. The two most important ones are:
- ELPA: GNU Emacs Lisp Package Archive — the official package archive, enabled by default.
- MELPA: Milkypostman’s Emacs Lisp Package Archive — Unofficial archive.
The next blob of Elisp (Emacs Lisp) code adds the MELPA archive to the packages archive list. The ELPA archive is installed by default. This code appends the configuration (add-to-list
) and does not override the default. Just ensure you add a trailing slash (at the end of the URL), otherwise, Emacs gets confused when downloading the package index.
(use-package package
:config
(add-to-list 'package-archives
'("melpa" . "https://melpa.org/packages/"))
(package-initialize))
You can explore the list of packages with the list-packages
function. This function has no keyboard shortcut, so first press M-x
and type the function name, followed by the Enter key.
Configuring Packages
John Wiggle has developed the use-package
software, which simplifies configuring packages. Computer scientists call this approach ‘syntactic sugar’ because it makes the syntax of a configuration file a bit easier to read and write. Most configurations on this website use this method to install and configure Emacs extensions.
(use-package use-package
:custom
(use-package-always-ensure t)
(package-native-compile t)
(warning-minimum-level :error))
This is the basic setup required to run any other configurations in this series of articles.
Keeping your packages up-to-date
Packages are constantly updated by their developers. To ensure you get the latest version, you can use the package-upgrade-all
function, which has no default keybinding. This might seem a strange name for this function, upgrade-all-packages
would seem a bit more linguistically sound. However, the convention for naming Emacs Lisp functions is that the first word is the package name, which is package
. So, for example, all Emacs Writing Studio functions start with ews-
.
Changing keyboard shortcuts
The previous article explained how Emacs uses the keyboard and the use of shortcuts to run functions. Emacs comes with a lot of default key bindings, all of which you can change or you can add new ones for functions you need to use regularly that don't have a default shortcut.
For example, adding this line to your configuration lets you play Tetris whenever you hit F8
. So this line associates the keyboard shortcut (kbd "<f8>")
in the global keymap with the tetris
function.
(keymap-set global-map "<f8>" #'tetris)
EWS deploys the use-package
configuration, which has a slightly different convention. You can as such change any of the keyboard shortcuts in this EWS configuration to your preference by simply changing the bit between quotation marks. Please note that function keys and other special keys are between <>
to prevent them being interpreted as individual keys.
(use-package emacs
:bind ("<f8>" . tetris))
Emacs Writing Studio configuration
Besides crafting your own configuration or using a starter kit, Emacs has a customisation menu that lets you configure Emacs without writing code. This system writes the required Emacs Lisp code to the init file.
Emacs Wring Studio uses two separate init files to prevent Emacs from changing your hand-crafted config. The configuration below changes the automated configuration file’s name to custom.el
and evaluates it when it exists.
(setq-default custom-file
(expand-file-name "custom.el" user-emacs-directory))
(when (file-exists-p custom-file)
(load custom-file))
The first lines of code instruct Emacs to use a separate file for the internal configuration system (custom.el
). The expand-file-name
expression adds the filename to the location of the Emacs user directory. This method ensures the code works irrespective of the Emacs user directory location.
The last two lines load this file when it exists (file-exists-p
). As this is the first action in the configuration, your personal init file will override any settings in the custom file.
Emacs Writing Studio variables
For convenience, the Emacs Writing Studio defines some variables to configure the system.
You can change these, and any other variable in Emacs, variables with the customize-variable
function, search for ews
, and pick the variable you seek to change. Alternatively, use customize-group
and search for ews
to see all variables. You can then change the entry in the text field to your preference and hit the Apply and save
button. Emacs saves the new value(s) to the custom.el
file and they will be loaded next time you start Emacs.

The Emacs customisation functionality is a low-code option to configure your system and the Emacs Writing Studio is configured so that the variables set with this method will override the default configuration presented in these pages. Alternatively you can of course hack your init file directly.
Emacs Writing Studio also includes a handful of bespoke convenience functions, which are discussed in their relevant pages. All bespoke configuration is stored in the ews.el
file on GitHub.
Is Emacs a Productivity Sink?
Configuring Emacs can be a daunting task and become a productivity sink because of the ease by which it can be done. Within the Emacs community, a discussion emerges every now and then about the need to make so many changes to the vanilla software to get it to behave how you like it.
A commonly asked question is why can't Emacs have 'sensible default' values? This may seem like a reasonable question, but what is sensible to one user is an annoyance for another. Emacs developers are as such quite conservative when it comes to changing the default settings.
The Emacs developers cannot cater to every personal preference, so they provide a skeleton system you must enhance to suit your workflow. Emacs Lisp is like a box of Lego. You can play with it out of the box using vanilla Emacs, but it is much more fun when you create your own toys. Working on your Emacs configuration is like building with Lego and eventually you configure Emacs to perfectly meet your needs.

It can be tempting to constantly fine-tune your configuration. Wielding the power to create a bespoke Emacs system is a temptation that can lead to fake productivity, which is one of the three forms of procrastination:
- Nihilistic procrastination: Watching TV or playing computer games.
- Sophisticated procrastination: Fake productivity, e.g. Emacs hacking, switching productivity tools, taking notes for volume instead of quality.
- Productive procrastination: Daydreaming.
Tinkering with your Emacs configuration is not as bad as nihilistic procrastination but can become a form of fake productivity. The productivity gains from fine-tuning your Emacs to cut out a few keystrokes can take more time than you will save with your new workflow. Writing is more than the number of words you can type into your buffer. Writing is as much a contemplative act as it is about productivity. Don’t get sucked into trying as many packages as possible. It will lead to what Emacs aficionados call Dot Emacs bankruptcy, which occurs when your init file is so enormous and disorganised that it becomes unmanageable.
The best way to learn how to configure your Emacs system is to search the web for examples and copy them to your init file. Initially, the code might look gibberish, but its logic will become more apparent as you do this more often. Emacs has an extensive help system that you can use to explore functions or variables you like to know more about. Use C-h o
(describe-symbol
) to search for any function or variable.

Hopefully, the Emacs Writing Studio configuration will help you reduce the time it takes to configure Emacs to suit your preferred workflow.
Emacs Writing Studio
If you like to support my work, then please purchase the Emacs Writing Studio book.
Emacs Writing Studio
A comprehensive guide for writers seeking to streamline their workflow using Emacs. The book covers everything from organising ideas and writing distraction-free to publishing in multiple formats. It’s perfect for both beginners and experienced Emacs users, offering practical tips and a tailored configuration to enhance your writing process.
Emacs is a malleable system, and everybody has personal preferences on how to undertake a task and configure Emacs. Any article on how to use Emacs is thus opinionated. If you have a different way of doing things, please complete the contact form to send me an email or contact me on social media.
The next article explains the principles of writing prose in Emacs.
Share this content