This is an example of a fully custom Emacs configuration that you can use as inspiration when building your own!

We’re developing this configuration live on YouTube, subscribe to System Crafters (make sure to click the bell!) so that you’re notified of future streams.

If you’re enjoying the videos and benefitting from the examples in this repo, please consider becoming a sponsor to support the development of future content!

This repo is meant to be a companion to the Emacs From Scratch video series, serving as an example of a custom configuration build on top of vanilla Emacs. I give instructions below for how to set it up to try it out, but it isn’t meant to be used as your main configuration! My goal here is to provide a working configuration that you can take inspiration from (and copy from directly).

Just keep in mind that this repo isn’t set up to be used directly as your own configuration! Copy the code to your own dotfiles repository and have fun :)

This repo now contains configuration from multiple series on the channel!

Here is a list of all the episode videos with links to the configuration we built for each one:

1. Live-Coding a Custom Emacs Configuration from Scratch (Code, Notes)
2. Adding Helpful UI Improvements (Code, Notes)
3. Key Bindings and Evil (Code, Notes)
4. Projectile and Magit (Code, Notes)
5. Org Mode Basics (Code, Notes)
6. Organizing Your Life with Org Mode (Code, Notes)
7. Configure Everything with Org Babel (Code, Notes)
8. Build Your Own IDE with lsp-mode (Code, Notes)
9. Learn to Love the Terminal Modes (Code, Notes)
10. Effortless File Management with Dired (Code, Notes)
11. Keeping Your Emacs Packages Up to Date (Code, Notes)
12. How to Cut Emacs Start Up Time in Half! (Code, Notes)

1. The Absolute Beginner’s Guide to Emacs (Notes)

1. Introduction to Emacs Lisp (Notes)
2. Types, Conditionals, and Loops (Notes)
3. Defining Functions and Commands (Notes)
4. Defining Variables and Scopes (Notes)
5. Reading and Writing Buffers in Practice (Notes, Code)

1. Getting Started with EXWM (Code, Notes)
2. Improving the EXWM Experience (Code, Notes)
3. Optimizing Window Placement in EXWM (Code, Notes)
4. Using Multiple Monitors in EXWM (Code, Notes)
5. The Perfect Panel: Integrating Polybar with Emacs (Code, Notes)
6. Enabling Desktop Notifications with Dunst (Code, Notes)

1. How to Debug Your Code with dap-mode (Code, Notes)
2. Python Development Configuration (Code, Notes)

1. How to Create and Manage Multiple Windows (Notes)
2. Organize Your Windows with the Tab Bar in Emacs 27 (Notes)
3. Dynamic Tiling Windows in Emacs with Edwina (Notes)
4. Unlock the Power of the Daemon with emacsclient (Notes)
5. Give Emacs Psychic Completion Powers with prescient.el (Notes)
6. Teach Emacs to Keep Your Folders Clean (Code, Notes)
7. Managing Encrypted Passwords with Emacs (Notes)
8. Hey Emacs, Don’t Move My Windows! (Notes)

1. Streamline Your E-mail Management with mu4e (Notes)
2. Managing Multiple Email Accounts with mu4e and mbsync (Notes)
3. Compose and Send Email with Emacs (Notes)
4. Enhance Your Emails with Org Mode (Notes)
5. Craft an Email Workflow with Org Mode (Notes)

IMPORTANT: Be sure to read the commentary in Emacs.org in case anything unexpected happens when you load this configuration. Feel free to file an issue to discuss any questions or problems you have so we can discuss it in a future stream!

Linux and macOS

On Linux, Emacs can be found in every major Linux distribution’s package manager. On macOS you can install Emacs using Homebrew via brew install emacs.

You can easily get started with this configuration on Linux and macOS by following these steps:

1. Clone this repository to a folder on your system: git clone https://github.com/daviwil/emacs-from-scratch
2. Back up any existing Emacs configuration you may already have in your home directory in the .emacs.d folder (you could try moving it to .emacs.d-old)
3. Rename the directory for the clone of this repo to ~/.emacs.d.
4. Start Emacs!

Windows

You can download the latest Emacs version (27.1 at the time of this writing) for Windows by heading to the GNU FTP site. Downloading and running the installer package will likely be the easiest way to get started. You can also install Emacs via Chocolatey if you prefer a more automated approach.

The location where the Emacs configuration folder lives may vary based on your version of Windows. If you have trouble getting this to work, check the official FAQ on the topic. If you still can’t get it to work, feel free to file an issue and I can help investigate.

For most modern Windows versions (Windows 7+), these steps should work:

1. Clone this repository to a folder on your system: git clone https://github.com/daviwil/emacs-from-scratch
2. Back up any existing Emacs configuration you may already have in your home directory (likely C:\Users\yourusername\) in the .emacs.d folder (you could try moving it to .emacs.d-old)
3. Rename the directory for the clone of this repo to C:\Users\yourusername\.emacs.d.
4. Start Emacs!

This configuration uses the Fira Code font by @tonsky and installation instructions can be found on this wiki page.

However, since this is meant to be your configuration, feel free to choose your own font!

Here are some general recommendations on Emacs usage that you might find helpful:

Most people don’t use the CapsLock key (unless you like YELLING ON THE INTERNET) so you can use this simple fix to replace it with the CTRL to make your Emacs life easier. Doing this will prevent you from having to bend your pinky down all day long to hit all those fabled Emacs keybindings, allowing you to keep your hands on the home row of the keyboard.

Here’s how to do it across all 3 major operating systems:

Linux X11

There are many ways to accomplish this in Linux, but the easiest (and most repeatable) I’ve found is to use xmodmap. First, create a file named .Xmodmap in your home folder and populate it like so:

clear lock
clear control
keycode 66 = Control_L
add control = Control_L
add Lock = Control_R

This replaces CapsLock with control and also replaces the Ctrl key on the right side with CapsLock just in case you ever need to use it. Most login systems (GDM, KDM, etc) will load this file when you log in so you might not need to do anything extra for it to take effect, just log out and log back in again. If that doesn’t seem to work, you can add this line to one of your startup files (.xinitrc, .profile, window manager configuration, etc):

xmodmap ~/.Xmodmap

Linux sway

In your ~/.config/sway/config file add this stanza and reload the config (usually $mod-Shift-c) or swaymsg reload:

input * {
xkb_options caps:ctrl_modifier
}

Windows

Approach #1: Change the binding in the Windows registry

On Windows you can use a simple registry file to tweak the CapsLock mapping. Save the following text to a file called CapsLockHack.reg:

REGEDIT4
[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Keyboard Layout]
"Scancode Map"=hex:00,00,00,00,00,00,00,00,02,00,00,00,1d,00,3a,00,00,00,00,00

Now double-click on this file in Windows Explorer and allow Windows to apply it to your registry settings. After you log out of your current session and log back in the new key mapping should be in effect. Note that this change will affect all users on your system.

Approach #2: Use Microsoft’s PowerToys

You can use PowerToys’ Keyboard Manager to easily remap the keys. Download the tool from their github page and install it. Then open the powertoys settings (you sould find it in the taskbar), go to keyboard manager, enable it if it isn’t already enabled and remap your keys. Once finished you should see something like:

Caps Lock ➞ Ctrl (Left)

Ctrl (left) ➞ Caps Lock

macOS

Thankfully Apple saw fit to make this a first-class option in macOS. You can follow the official documentation for your version of macOS to find the Modifier Keys settings and then switch Caps Lock to Control on that page.