WARNING: THIS IS A WORK IN PROGRESS. USING THIS AS IS WILL RESULT IN YOU HAVING A BAD TIME. YOU HAVE BEEN WARNED!

This is a very biased starter configuration for GNU Emacs. It is the result of wanting to give people a good start for using Emacs in the way that I believe is best. That said this configuration is not meant to completely dictate how you should use Emacs. At several points I document alternatives to what I recommend for the sake of completeness. Emacs is, after all, about freedom of choice.

These are guiding principles I used when creating this configuration. These are in no particular order and there is no rule for priority. For the most part these principles do not conflict. If they do, document why I have chosen one over the other on a case by case basis.

Prioritize Base Emacs

When choosing between something built into Emacs and an external package, choose the Emacs builin unless you truly need the extra feature(s) that the external package provides.

Use Emacs Constructs

Emacs is built on some basic constructs (buffers, alists, keymaps, etc.). Prioritize using these over some custom data structure.

Make It Easy to Write Your Own Extensions

It should be trivial to write your own extension on top of what the package (Emacs builtin or external) does. This mainly means two things: 1) the packages themselves should be extensible and 2) the friction between idea and implementing it yourself should be minimized.

Maximize Declarative Configuration

We will be using use-package to configure Emacs. This is so that each part of our configuration can be treated as one unit.

Easy Modularization

While the entirety of this configuration gets put in one file, init.el, it should be trivial to simply pick up a piece of configuration and move it into its own file once init.el gets too long or too hard to debug.

Centralize Tribal Knowledge

Much of Emacs is documented in its manual, the Emacs Lisp manual, and function/variable documentation strings. However, there are also tons of great explainer blog posts and videos that really made some of these concepts click for me. I will try to explain what you need to know to get up and going here and link to others who have explained these concepts better and in more detail.

Emphasize, Not Dictate, Literate Configuration

I will go more into depth on literate configuration in the configuration file itself but for now the gist: documentation and code are part of one file and the code gets copied out to the file(s) it needs to in order for it to run. This has the benefit that anyone (including future you) can read you what you wrote and why. Literate configuration is good for a number of reasons but some people just wont like it and would rather just write their configuration. It should be easy for people to switch to whatever configuration paradigm they want.

Default:

meow (external)

meow is a modal editing package that, by default, creates a modal editing system similar to that of helix or kakoune. The biggest difference between it and vim is the inversion of the verb-subject syntax. For instance, to delete to the end of a word in vim you would type d e where as in meow you would type e d. This has the benefit of being able to see what you are about to operate on before you operate on it. Combined with the repetition as a prefix, vim commands such as 3 d f s become f s 2 d, showing you what exactly what you are going to be deleting before you delete it. meow also has other things to it as well, such as the creation of custom “things” (think vim text objects). However, I firmly believe that the best part about it is that it integrates seamlessly with other Emacs interfaces such as magit (git interface) and dired (file manager).

meow-tresitter (external)

This is an Emacs package that allows meow to select regions of text that correspond to tree-sitter nodes, such as a class or function.

avy (external)

This is an Emacs package that allows you to quickly jump to a piece of text on a screen with your keyboard (as opposed to a mouse). You can even make it so that you execute an editing command instead of or in addition to jumping there. If you are coming from vim this is a lot like vim-easymotion.

repeat-mode (built-in)

Allows for quick repeating of really long key chords.

shell (built-in)

eat (external)

Short for Emulate A Terminal, it is a terminal emulator in Emacs. While it isn’t the fastest, most complete, or most “Emacsy”, it does hit that sweet spot of the 3 and is what I recommend for most people who need a terminal emulator in Emacs.

eshell (built-in)

Optional:

vterm (external)

vertico (external)

marginalia (external)

orderless (external)

consult (external)

Optional:

embark (external)

Default:

ace-window (external)

popper (external)

Default:

dired (builtin)

Default:

modus-themes (builtin)

Optional:

ef-themes (external)

doom-themes (external)

catppucin (external)

Default:

lsp-mode (external)

lsp-ui (external)

Default:

project (builtin)

magit (external)

Optional:

projectile (external)

Default:

flycheck (external)

Default:

envrc (builtin)