Emacs From Scratch

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!

Episodes

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

Emacs From Scratch

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)
2. Adding Helpful UI Improvements (Code)
3. Key Bindings and Evil (Code)
4. Projectile and Magit (Code)
5. Org Mode Basics (Code)
6. Organizing Your Life with Org Mode (Code)
7. Configure Everything with Org Babel (Code)
8. Build Your Own IDE with lsp-mode (Code)
9. Learn to Love the Terminal Modes (Code)
10. Effortless File Management with Dired (Code)

Learning Emacs Lisp

1. Introduction to Emacs Lisp (Notes)
2. Types, Conditionals, and Loops (Notes)
3. Defining Functions and Commands (Notes)
4. Defining Variables and Scopes (Notes)

Emacs Desktop Environment

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)

Emacs IDE

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

Emacs Tips

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)

Emacs Mail

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)

Usage Instructions

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!

Installing the Fira Code Font

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!

Recommendations

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

Replace CapsLock with CTRL

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

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.

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.