Quake Emacs

Lean, fast, focused, and based on the latest Emacs tech

---

If you want to use Emacs, but you:

1. just want to sit down and have your new text editor work well and look good right away, and
2. don’t want the complexity, abstraction, and lack of documentation of a larger Emacs distribution or configuration framework,

then Quake Emacs is for you.

Text editors are most often used for three core tasks: code editing, writing, and note-taking. Quake Emacs is a single-file Emacs distribution architected around those three fundamental tasks, aiming to provide a lean, fast, focused, and complete experience for all three right out of the box, while remaining as simple and vanilla as possible, so you can use it as a great foundation for bare-metal Emacs configuration.

Table of Contents

• How To Install
• Key Features
• Showcase
• Personal Configuration and Extra Layers
• Justification
• Inspiration and Prior Art

How To Install

1. First, you install Quake Emacs like usual:

git clone --depth=1 -b main https://github.com/alexispurslane/quake-emacs.git ~/.emacs.d

1. Then copy the example user.el provided with Quake to your Quake Emacs configuration directory at ~/.quake.d/user.el:

mkdir -p ~/.quake.d/ && cp ~/.emacs.d/user.el ~/.quake.d/

To update, just git pull to the latest tag. I recommend you check the release notes for the tag for any tips, known issues to avoid, etc.

Key Features

• 🎯 Lean and focused: Quake Emacs includes just the packages and configuration you need for a beautiful, modern IDE-lite experience when coding and a focused, ergonomic experience when writing or taking notes, and nothing else. It even completely does away with the need for language-specific layers through the use of tree-sitter and LSP support. Consider Quake Emacs part of your editor — it’s just there to give you a good out of the box experience, like Helix. The rest is up to you!
• 🚀 Fast: On my machine, Quake Emacs loads in under 0.6 seconds. Every single package is carefully chosen with performance in mind, and the default load order is tuned obsessively to ensure Emacs starts as fast as possible. Enjoy fast startup times, or use it as extra headroom to add your own packages.
• 🥇 Just one single file: The configuration framework itself is only one simple, extensively documented, self-contained 1000-line file. That’s it. Just put the file in your Emacs directory and go. No external commands, no multiple thousands of lines of Lisp scattered throughout hundreds of files across interminable layers of abstraction. If you want to know where something is, or how it works, it’s easy to find.
• 🌐 Modern and vanilla: Despite having an opinionated UX out of the box, Quake Emacs prioritizes using Emacs’s built-in capabilities and packages that integrate well with them as much as feasibly possible. No more extra layers of abstraction, no more dozens or hundreds of redundant packages, and no more Emacs documentation not applying to you because of the Emacs distribution you’re using.

Quake Emacs even uses god-mode with evil-god-state to provide Doom/Spacemacs style leader key keybindings while reusing all of Emacs’s default keybindings and mnemonics, meaning there’s no need to define custom keybindings for everything, the defaults that come with any existing Emacs package will just work, and existing Emacs documentation will still be meaningful to you!

Showcase

Simple Config

Before I get to showing you any of the fancy things Quake Emacs can do, the most important thing is proving that it will be manageable for you to understand and fork if necessary, and won’t lead either you or me to Emacs bankruptcy. One of the key things I’ve done in this regard is optimizing the layout of init.el to work with Emacs’s built-in outline-minor-mode to help you get an overview of it and jump to specific things in it without needing finnicky text search or getting overwhelmed:

It’s much more difficult to demonstrate code clarity and simplicity in a gif, though, so if you’re still skeptical, I highly encourage you to skim the source code yourself.

[!NOTE] Why isn’t this a literate config? I’ve seriously considered it for code clarity reasons, but decided against it for a number of reasons:

1. First, as a literate config, I’d want to move all the per-layer documentation out of docstrings and into the org mode markup to avoid tedious duplication, but then eldoc wouldn’t document layers for you.
2. Second, it would mean Quake Emacs would really be two files, instead of one and a user file, which is annoying. I do want it to be as self-sufficient as possible. In fact, I’m planning on making the user file optional.
3. Third, it adds a layer of indirection and complexity that goes against the core goal of Quake Emacs: with a literate config, I’d have to use org-tangle to ‘compile’ it before it could be loaded into Emacs, and it would be possible for the literate config and the tangled config to get out of sync locally, not to mention needing to use {C-c ‘} to edit the blocks.
4. And fourth, it would probably significantly slow start times, since =load=ing is slow, and I want to avoid that. However, I’ve tried to get as close to what a literate configuration file would offer by other means

Feel free to open an issue if you think this was a bad choice, though!

Code Editing

Quake Emacs has fuzzy autocompletion with Corfu and Orderless enabled everywhere.

Full autocompletion even works in the Lisp Eval line (M-:). It’s a real repl, so why not have a real coding experience in it?

We also have a vertical fuzzy searching UI for popups, with live narrowing, like you’re used to in other modern editors, available using Emacs’s built-in completion UI, Icomplete! No need for Vertico now that we have icomplete-vertical-mode and the ability to tweak icomplete’s existing settings to remove all the limits and delays, and especially since Orderless, Marginalia, and Consult integrate with vanilla Emacs’s existing functions and capabilities, so anything tha makes use of them is automatically enhanced!

Quake Emacs also features which-key for more discoverable keybindings, and a meticulous set of evil-mode keybindings, made with general).

Quake Emacs also provides IDE class-features thanks to LSP support via Eglot and eldoc-box, highly automatic tree-sitter support with treesit-auto, inline errors and linting and even quick-fixes with Eglot’s integration with Flymake, and advanced language-agnostic debugging with DAPE. Here’s just LSP and eldoc-box (and tree-sitter’s syntax highlighting) on display:

I’ve also spent a great deal of time setting up tree-sitter based structural text objects for selection, editing, and motion using evil-textobj-tree-sitter, supporting all the text objects Helix or NeoVim does thanks to reading Helix’s source code and NeoVim’s documentation. Enjoy the text generation of advanced text editing!

structural-textobjects.webm

And, Quake Emacs wouldn’t be able to live up to its name unless it had a classic Quake-style popup terminal! So here it is, implemented entirely without any external packages, and bound to SPC ~:

Writing

For those of you who prefer to write your prose in Emacs, I’ve also created an excellent writing mode, which switches to a variable pitch font of your choice, enables a distraction-free writing mode, and enables visual fill column mode wrapped at 65 characters so that lines behave pleasingly like in a WYSIWYG editor:

Writing mode also enables a flymake proselint backend to help you improve your prose:

To enable all of that, just use SPC o d!

Lusting after the capabilities of GNU Hyperbole but not so sure about such a gigantic package, that doesn’t integrate well with Emacs’s standard UI? Quake Emacs has Embark by default, to imbue all your text buffers with meaning and actions without any need for explicit syntax or buttonization. Now every text buffer is an active hypertext experience!

Note-taking

For those that want Emacs to serve as their note-taking machine, Quake Emacs uses Denote, a lightweight personal hypertext information manager that offers all of the same basic features as org-roam, without locking you down to using only Org, or requiring you to use an SQLite database, while also offering optional excellent integration with org if you want it. It can incorporate an extensible list of markup languages instead of just org and markdown, or even non-text-markup files directly into its linking and searching system. Moreover, it also makes deep use of existing Emacs built-ins, as well as integrating explicitly with packages like marginalia, and consult (via consult-notes). And of course I’ve created a set of convenient leader key keybinds for managing it.

I’ve also unlocked the power of having your code editor, word processor, and note-taking application all be one and the same through enabling global buttonization and insertion of denote links. Now you can link to your notes from any file you open, no matter where it is or what file type it is. Want to keep a huge library of notes on your various projects and link to them in the comments of your code? Now you can.

Want to have several separate Zettelkasten for different projects? I’ve created a custom command that allows you to automatically create a new denote silo and add it to project.el, so you can manage your silos just like any other project without having to put them in version control.

Personal Configuration and Extra Layers

When writing custom configuration in your user.el, it is recommended that you separate your configuration out into logical groups according to general purpose, with each group contained within a function (and preferably with everything within those functions/groups bundled neatly into use-package declarations). This is precisely what Quake Emacs does — we call these logical units “layers”, after the fashion of Doom Emacs and Spacemacs, although they’re just regular functions, no boilerplate necessary — and it has a few benefits:

1. It means that your code is easier to fold and navigate with imenu without even needing to insert outline headlines, and easier to document in an accessible way, since you gain the ability to attach docstrings not just to individual utility functions or use-packages, but to logical groups of things, so you can document what you’re doing and why at a higher level, essentially reproducing much of the benefit of a literate config.
2. It just means your code is more logically and neatly organized, the better to avoid Emacs bankruptcy.
3. Finally, it means that you can take advantage of Quake Emacs’s existing logic for running layers, and slot your own code neatly anywhere you want in the Quake Emacs load order, in case you need to run before some things but after others, without having to modify the core init.el or do any other hacks.

Out of the box, Quake Emacs contains only the layers that you will absolutely need for a good general-purpose writing, note taking, and code editing experience, as explained above. However, if you find yourself needing more functionality, in addition to writing your own layers, I have a few Gists containing some layers I’ve constructed for personal use, here:

Layer Name	Layer Description
org-static-blog-layer	Use org-mode and Emacs to directly generate your blog, no external programs needed! Have your blog wherever you have your editor!
eshell-layer	Modernize eshell, for those used to modern shells like Fish and Nushell, or heavily extended Zsh.
gnus-proton-mail-layer	Use GNUS to send (asynchronously!) and receive mail with Proton Mail.
tramp-distrobox-layer	Use TRAMP with Distrobox (for immutable distros mainly)
devil-layer	A basic set of Doom/Spacemacs style leader-key keybindings to get you started. (Quake Emacs has switched to god-mode and a package that makes god-mode behave like a leader key, because it’s more compatible with vanilla emacs, and much easier to maintain.)

[!NOTE] If you write a layer you think might be generally useful to others, as long as it is reasonably small and self-contained, you are more than encouraged to submit a PR on this readme so we can add it to the list!

Justification

With the introduction of various modern Emacs features in the last few years, and the emergence of a new generation of Emacs packages focused on integrating with vanilla Emacs, Emacs distributions as we have known them are less and less relevant.

Now that use-package is included with Emacs by default, configuration frameworks are less necessary then ever, as vanilla Emacs’s built-in capabilities are likely clearer, faster, and more powerful than whatever a configuration framework could offer, with the benefit of also being the community standard. In my experience, Doom Emacs’s ideosyncratic package management system was less clear, less-organized, less-documented, and much less reliable than what is now built into Emacs 29.

Likewise, with the inclusion of eglot and tree-sitter, language-specific “layers” that compose five or six packages, together with a lot of configuration, in order to give a decent experience, are mostly a thing of the past. Quake Emacs leverages these powerful built-in modern Emacs features to give you the experience of an Emacs configuration framework and distribution, without all the downsides.

Similarly, with the creation of amazing packages like vertico, orderless, and corfu, the need to manually integrate added features from various packages into your Emacs system and other Emacs packages is basically obsolete: these packages integrate directly with Emacs, by hooking into or outright replacing Emacs’s built in functions for performing various actions, so there’s no need to do anything. As a result, much of the configuration work Emacs distributions needed to do to wire everything up simply doesn’t need to be done.

Inspiration and Prior Art

Doom Emacs

DOOM Emacs was my previous (and fallback) daily driver. It is an excellent Emacs distribution and piece of software, but essentially its own editor in many ways. Still what I would probably recommend to a newbie until Quake hypothetically becomes stable and mature.

Points of similarity:

1. Extensive evil mode support and integration, allowing you to control your editor entirely from Vim-style leader key combinations, and integrating evil mode into every other mode and package installed.
2. Opinionated and aesthetically pleasing defaults to try to make Emacs look and feel, not like another editor like VSCode, but like a modern Emacs — unique, but not recalcitrant.
3. Obsessive attention to performance, because one of the main benefits of Emacs is providing a powerful editing experience comparable or vastly superior to something like VSCode, while still relatively having the performance and lightweight footprint of a terminal application.

Differences:

1. Doesn’t install nearly as many packages and does fewer (no) ideosyncratic things. This gives you less of a complete experience you aren’t supposed to tinker with besides toggling layers, and more of a comfortable and usable-out-of-the-box, but relatively simple and straightforward, foundation to build from.
2. Has no “alternate” layers to achieve the same functionality in different ways (e.g. helm vs ivy vs vertico). There is one blessed set of packages, to avoid the combinatorial explosion of complexity that brings.
3. Will not have any layers, packages, and configuration available or installed for anything outside of making what I consider core text editor functionality nice to use (so nothing for mail, no vterm, etc).
4. Offers no customization framework or anything bespoke, only Vanilla Emacs constructs.
5. Fully adopts modern Emacs features, including treesit, eglot, use-package, and even electric-pair (Doom Emacs is strugglign with this)
6. Will never have language-specific layers, uses eglot and treesit for generally excellent language support.
7. No complex external terminal commands for management.
8. Has hard complexity and size limits: one 1000-line file, less than a second of startup time even with all layers enabled.

MinEmacs

I have not personally used MinEmacs, but I rifled fairly extensively through its codebase to borrow ideas, tips, tricks, and so on, and read its mission statement and looked at the screenshots.

Points of similarity:

1. Primarily one user’s config, generalized into a general distribution, but not designed to automatically provide for use-cases or configurations wildly separate from the author’s own.
2. Desiring to be more minimal and closer to “bare metal Emacs.”
3. When starting out, Quake Emacs used MinEmacs’s leader key keybindings as a basis, although they’ve diverged a fair amount by now.

Differences:

1. Far less complexity and fewer layers of abstraction, provides NO “configuration framework,” NO custom standard library, nothing like that.
2. Different opinionated design decisions (not based on NANO Emacs’s design philosophy)
3. No language-specific layers

Emacs Prelude

Emacs Prelude seems to be the most philosophically similar Emacs distribution to Quake Emacs. They share many goals and have very similar approaches. You could perhaps think of Quake Emacs as a more modern, and slightly more opinionated, take on Prelude!

Points of similarity:

1. Shared goals:
2. Simplicity
3. Ease of understanding and direct modification (not just tweaking)
4. A foundation for you to build upon
5. Shared practical approaches:
6. Most modules are pretty short and just have essential packages and a few configurations
7. Installs relatively few additional packages (63 at last count)
8. Less opinionated than distributions like Spacemacs or Doom Emacs

Differences:

1. Installs relatively few packages and vets every single one that is installed for active maintinence, general stability/maturity, etc, like MinEmacs, but still uses much more modern Emacs capabilities and packages, as soon as they are reasonably mature, instead of choosing older packages simply for the sake of longevity.
2. Intended to strike a balance between being a great end-user product out of the box while also being a great foundation to build on.
3. Does not come with a bespoke standard library or configuration framework, it’s just pure modern Emacs.
4. Does not make most layers opt-in, since there are so few of them
5. No language specific layers.
6. Uses evil-mode by default (intended to lighten the burden of maintaining an Evil config by sharing that work between users!)
7. Focuses on only supporting the latest Emacs.
8. Much greater focus on performance.