daviwil / Emacs From Scratch

#+title: 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 [[https://www.youtube.com/c/SystemCrafters?sub_confirmation=1][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 [[https://github.com/sponsors/daviwil][becoming a sponsor]] to support the development of future content!

• How to Use This Configuration

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 :)

• Episodes

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

** [[https://www.youtube.com/playlist?list=PLEoMzSkcN8oPH1au7H6B7bBJ4ZO7BXjSZ][Emacs From Scratch]]

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

1. [[https://www.youtube.com/watch?v=74zOY-vgkyw][Live-Coding a Custom Emacs Configuration from Scratch]] ([[https://github.com/daviwil/emacs-from-scratch/tree/c0266ff684f670ecc5e41615c0282912e6615214][Code]], [[file:show-notes/Emacs-01.org][Notes]])
2. [[https://www.youtube.com/watch?v=IspAZtNTslY][Adding Helpful UI Improvements]] ([[https://github.com/daviwil/emacs-from-scratch/tree/43c0401355c7971cb4491690ee4b8449505a5d58][Code]], [[file:show-notes/Emacs-02.org][Notes]])
3. [[https://www.youtube.com/watch?v=xaZMwNELaJY][Key Bindings and Evil]] ([[https://github.com/daviwil/emacs-from-scratch/tree/29e542c79632853d85124019e47506cc0571cd05][Code]], [[file:show-notes/Emacs-03.org][Notes]])
4. [[https://youtu.be/INTu30BHZGk][Projectile and Magit]] ([[https://github.com/daviwil/emacs-from-scratch/tree/500370fa06889dad313e60473d73090fcfbe106d][Code]], [[file:show-notes/Emacs-04.org][Notes]])
5. [[https://www.youtube.com/watch?v=VcgjTEa0kU4][Org Mode Basics]] ([[https://github.com/daviwil/emacs-from-scratch/tree/1a13fcf0dd6afb41fce71bf93c5571931999fed8][Code]], [[file:show-notes/Emacs-05.org][Notes]])
6. [[https://youtu.be/PNE-mgkZ6HM][Organizing Your Life with Org Mode]] ([[https://github.com/daviwil/emacs-from-scratch/tree/c55d0f5e309f7ed8ffa3c00bc35c75937a5184e4][Code]], [[file:show-notes/Emacs-06.org][Notes]])
7. [[https://youtu.be/kkqVTDbfYp4][Configure Everything with Org Babel]] ([[https://github.com/daviwil/emacs-from-scratch/tree/9388cf6ecd9b44c430867a5c3dad5f050fdc0ee1][Code]], [[file:show-notes/Emacs-07.org][Notes]])
8. [[https://youtu.be/E-NAM9U5JYE][Build Your Own IDE with lsp-mode]] ([[https://github.com/daviwil/emacs-from-scratch/tree/6d078217a41134cc667f969430d150c50d03f448][Code]], [[file:show-notes/Emacs-08.org][Notes]])
9. [[https://youtu.be/wa_wZIuT9Vw][Learn to Love the Terminal Modes]] ([[https://github.com/daviwil/emacs-from-scratch/tree/bbfbc77b3afab0c14149e07d0ab08d275d4ba575][Code]], [[file:show-notes/Emacs-09.org][Notes]])
10. [[https://youtu.be/PMWwM8QJAtU][Effortless File Management with Dired]] ([[https://github.com/daviwil/emacs-from-scratch/blob/8c302a79bf5700f6ef0279a3daeeb4123ae8bd59/Emacs.org#dired][Code]], [[file:show-notes/Emacs-10.org][Notes]])
11. [[https://youtu.be/dtjq68F2dXw][Keeping Your Emacs Packages Up to Date]] ([[https://github.com/daviwil/emacs-from-scratch/blob/4e921ccbe603d5fdd9c7f16c2418ac7322c8ab71/Emacs.org#automatic-package-updates][Code]], [[file:show-notes/Emacs-Scratch-11.org][Notes]])
12. [[https://youtu.be/9i_9hse_Y08][How to Cut Emacs Start Up Time in Half!]] (Code, [[file:show-notes/Emacs-Scratch-12.org][Notes]])

** [[https://www.youtube.com/playlist?list=PLEoMzSkcN8oPZvSdewHG8uApD7THlLLCV][Emacs Essentials]]

1. [[https://youtu.be/48JlgiBpw_I][The Absolute Beginner's Guide to Emacs]] ([[file:show-notes/Emacs-Beginners-01.org][Notes]])

** [[https://www.youtube.com/watch?v=RQK_DaaX34Q&list=PLEoMzSkcN8oPQtn7FQEF3D7sroZbXuPZ7][Learning Emacs Lisp]]

1. [[https://youtu.be/RQK_DaaX34Q][Introduction to Emacs Lisp]] ([[file:show-notes/Emacs-Lisp-01.org][Notes]])
2. [[https://youtu.be/XXpgzyeYh_4][Types, Conditionals, and Loops]] ([[file:show-notes/Emacs-Lisp-02.org][Notes]])
3. [[https://youtu.be/EqgkAUHw0Yc][Defining Functions and Commands]] ([[file:show-notes/Emacs-Lisp-03.org][Notes]])
4. [[https://youtu.be/tq4kTNL1VD8][Defining Variables and Scopes]] ([[file:show-notes/Emacs-Lisp-04.org][Notes]])
5. [[https://youtu.be/J7d2LmivyyM][Reading and Writing Buffers in Practice]] ([[file:show-notes/Emacs-Lisp-05.org][Notes]], [[https://github.com/daviwil/dotcrafter.el/blob/8d507eda31e08a789c38a5d729866eb4cda6abaf/dotcrafter.el][Code]])

** [[https://www.youtube.com/playlist?list=PLEoMzSkcN8oNPbEMYEtswOVTvq7CVddCS][Emacs Desktop Environment]]

1. [[https://www.youtube.com/watch?v=f7xB2fFk1tQ][Getting Started with EXWM]] ([[https://github.com/daviwil/emacs-from-scratch/blob/219c060e1bd695948c7691955a12a5dcaf3a9530/Emacs.org#window-management][Code]], [[file:show-notes/Emacs-Desktop-01.org][Notes]])
2. [[https://youtu.be/9gfKrrTtyOk][Improving the EXWM Experience]] ([[https://github.com/daviwil/emacs-from-scratch/blob/2805904966dbd5810ee735e25c4b427014761be5/Desktop.org][Code]], [[file:show-notes/Emacs-Desktop-02.org][Notes]])
3. [[https://youtu.be/HGGU5Zvljj8][Optimizing Window Placement in EXWM]] ([[https://github.com/daviwil/emacs-from-scratch/blob/39f63fe133cd4c41e13bbd1551c6517162851411/Desktop.org#exwm-configuration][Code]], [[file:show-notes/Emacs-Desktop-03.org][Notes]])
4. [[https://youtu.be/eF5NfVN411Q][Using Multiple Monitors in EXWM]] ([[https://github.com/daviwil/emacs-from-scratch/blob/5ebd390119a48cac6258843c7d5e570f4591fdd4/Desktop.org#exwm-configuration][Code]], [[file:show-notes/Emacs-Desktop-04.org][Notes]])
5. [[https://youtu.be/usCfMstCZ7E][The Perfect Panel: Integrating Polybar with Emacs]] ([[https://github.com/daviwil/emacs-from-scratch/blob/75f1d4e08512c49ea073c26058df6d4cca3a0d6b/Desktop.org#panel-with-polybar][Code]], [[file:show-notes/Emacs-Desktop-05.org][Notes]])
6. [[https://youtu.be/GX_LGfuojcE][Enabling Desktop Notifications with Dunst]] ([[https://github.com/daviwil/emacs-from-scratch/blob/b927109521b4b8a7e701709dabbdd9c1ea2fc27c/Desktop.org#desktop-notifications-with-dunst][Code]], [[file:show-notes/Emacs-Desktop-06.org][Notes]])

** [[https://www.youtube.com/playlist?list=PLEoMzSkcN8oNvsrtk_iZSb94krGRofFjN][Emacs IDE]]

1. [[https://youtu.be/0bilcQVSlbM][How to Debug Your Code with dap-mode]] ([[https://github.com/daviwil/emacs-from-scratch/blob/210e517353abf4ed669bc40d4c7daf0fabc10a5c/Emacs.org#debugging-with-dap-mode][Code]], [[file:show-notes/Emacs-IDE-01.org][Notes]])
2. [[https://youtu.be/jPXIP46BnNA][Python Development Configuration]] ([[https://github.com/daviwil/emacs-from-scratch/blob/dd9320769f3041ac1edca139496f14abe147d010/Emacs.org#python][Code]], [[file:show-notes/Emacs-IDE-02.org][Notes]])

** [[https://www.youtube.com/watch?v=wKTKmE1wLyw&list=PLEoMzSkcN8oMHJ6Xil1YdnYtlWd5hHZql][Emacs Tips]]

1. [[https://youtu.be/gbdE7oZEdtA][How to Create and Manage Multiple Windows]] ([[file:show-notes/Emacs-Tips-05.org][Notes]])
2. [[https://youtu.be/C7ZlNRbWdVI][Organize Your Windows with the Tab Bar in Emacs 27]] ([[file:show-notes/Emacs-Tips-06.org][Notes]])
3. [[https://youtu.be/_qXZNfRcNnw][Dynamic Tiling Windows in Emacs with Edwina]] ([[file:show-notes/Emacs-Tips-07.org][Notes]])
4. [[https://youtu.be/ZjCRxAMPdNc][Unlock the Power of the Daemon with emacsclient]] ([[file:show-notes/Emacs-Tips-08.org][Notes]])
5. [[https://youtu.be/T9kygXveEz0][Give Emacs Psychic Completion Powers with prescient.el]] ([[file:show-notes/Emacs-Tips-Prescient.org][Notes]])
6. [[https://youtu.be/XZjyJG-sFZI][Teach Emacs to Keep Your Folders Clean]] ([[https://github.com/daviwil/emacs-from-scratch/blob/a57d99ba80276926a2b68521f9a9d23dc173a628/Emacs.org][Code]], [[file:show-notes/Emacs-Tips-Cleaning.org][Notes]])
7. [[https://youtu.be/nZ_T7Q49B8Y][Managing Encrypted Passwords with Emacs]] ([[file:show-notes/Emacs-Tips-Pass.org][Notes]])
8. [[https://youtu.be/-H2nU0rsUMY][Hey Emacs, Don't Move My Windows!]] ([[file:show-notes/Emacs-Tips-DisplayBuffer-01.org][Notes]])

** [[https://www.youtube.com/watch?v=yZRyEhi4y44&list=PLEoMzSkcN8oM-kA19xOQc8s0gr0PpFGJQ][Emacs Mail]]

1. [[https://youtu.be/yZRyEhi4y44][Streamline Your E-mail Management with mu4e]] ([[file:show-notes/Emacs-Mail-01.org][Notes]])
2. [[https://youtu.be/olXpfaSnf0o][Managing Multiple Email Accounts with mu4e and mbsync]] ([[file:show-notes/Emacs-Mail-02.org][Notes]])
3. [[https://youtu.be/WiyqU7gmKsk][Compose and Send Email with Emacs]] ([[file:show-notes/Emacs-Mail-03.org][Notes]])
4. [[https://youtu.be/aml36yZ-ANc][Enhance Your Emails with Org Mode]] ([[file:show-notes/Emacs-Mail-04.org][Notes]])
5. [[https://youtu.be/dSZu4jwvaSs][Craft an Email Workflow with Org Mode]] ([[file:show-notes/Emacs-Mail-05.org][Notes]])

• Usage Instructions

IMPORTANT: Be sure to read the commentary in [[file:Emacs.org][Emacs.org]] in case anything unexpected happens when you load this configuration. Feel free to [[https://github.com/daviwil/runemacs/issues][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 [[https://brew.sh/][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 [[https://ftp.gnu.org/gnu/emacs/windows/emacs-27/][GNU FTP site]]. Downloading and running the [[https://ftp.gnu.org/gnu/emacs/windows/emacs-27/emacs-27.1-x86_64-installer.exe][installer package]] will likely be the easiest way to get started. You can also [[https://chocolatey.org/packages/Emacs][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 [[https://www.gnu.org/software/emacs/manual/html_node/efaq-w32/Location-of-init-file.html#Location-of-init-file][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 [[https://github.com/tonsky/FiraCode][Fira Code]] font by [[https://github.com/tonsky][@tonsky]] and installation instructions can be found on [[https://github.com/tonsky/FiraCode/wiki/Installing][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 [[https://askubuntu.com/questions/33774/how-do-i-remap-the-caps-lock-and-ctrl-keys][many ways]] to accomplish this in Linux, but the easiest (and most repeatable) I've found is to use [[https://wiki.archlinux.org/index.php/Xmodmap][xmodmap]]. First, create a file named =.Xmodmap= in your home folder and populate it like so:

#+begin_src

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

#+end_src

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):

#+begin_src sh

xmodmap ~/.Xmodmap

#+end_src

Linux sway

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

#+begin_src input * { xkb_options caps:ctrl_modifier } #+end_src

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=:

#+begin_src

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

#+end_src

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 [[https://support.apple.com/guide/mac-help/change-the-behavior-of-the-modifier-keys-mchlp1011/mac][official documentation]] for your version of macOS to find the Modifier Keys settings and then switch Caps Lock to Control on that page.