🚀 Emacs is Like an Ancient Starship Built by an Advanced Alien Civilization, Discovered Half-buried in The Amazon Jungle.

This is The Human-written Launch Sequence to Get You Into Space.

Emacs ONBOARDing made Easy. Overwhelmed by complex Emacs distros like Doom-Emacs or Spacemacs? You want to roll your own Emacs config bottom-up? Or you don’t want to configure Emacs at all? But … just use it? Right now? 🤯

Emacs ONBOARD aims to be a comprehensive, portable starter-kit. It’s not supposed to replace your init.el, but loaded from there as a library (see installing instructions down below).

TRY IT

1. Download eon.el
2. Open a terminal
3. Run the shell command: emacs -q --load ~/path/to/eon.el

Emacs ONBOARD is vanilla Emacs, but gives you a vastly better user experience, without any 3rd-party packages.

It’s all built-in – all on board

✔ One single file, ZERO dependencies

✔ Beginner-friendly

✔ Convenient drop-in config: just load it early from your init.el

INSTALL

1. Clone this repository:

git clone https://github.com/monkeyjunglejuice/emacs.onboard.git ~/.emacs.onboard

2. Put this in your Emacs init file directly after (custom-set-faces ... )

(load-file (expand-file-name "~/.emacs.onboard/eon.el"))

3. (Re)start Emacs

You don’t have a init file or don’t know where it is? With a freshly installed Emacs there is no init file. But you can ask Emacs where it expects to find the init file:

“M-x describe-variable” <RET> user-init-file

Typical results:

• on Linux / Unix / MacOS
  • /home/USERNAME/.emacs
  • /home/USERNAME/.emacs.d/init.el
• on Windows
  • c:/Users/USERNAME/AppData/Roaming/.emacs
  • c:/Users/USERNAME/AppData/Roaming/.emacs.d/init.el

Goals and Principles

• As un-opinionated as possible – there’s no “one-fits-all”, and you should be able to make your Emacs whatever you want it to be. That’s the spirit. Emacs ONBOARD removes the need for caring about the mundane stuff.
• Don’t be invasive: Provide an Emacs config as a library; don’t try to be a replacement, but an add-on you can build upon. So, no “delete your .emacs.d/ directory and then …” here.
• Portable: Should work on recent Linux/Unix, Windows and MacOS systems.
• Documentation is first class: It should be clear why something is in the code.
• Beginner-friendly: Novice Emacs users willing to touch Elisp code should be able to follow (well, most of it).
• No-code friendly: The Emacs user base isn’t just programmers – expose important preferences via GUI M-x eon-customize-group.
• Modern: Emacs Lisp code should be written in contemporary style and be free from errors and warnings (iterate and refactor often).
• Only rely on built-in packages and features enabled by the GNU Emacs distribution’s default build options.
• Extendable by 3rd-party packages without interfering or breaking things.
• Modular: Code should not be tightly coupled, but easily modificable and separately usable.
• Reasonable backwards-compatibility: Don’t overdo – follows the Emacs version in Debian Stable, which is a fairly conservative GNU/Linux distro (currently Emacs 30.1).

Non-goals

• Providing an opinionated experience like Spacemacs or Doom-Emacs.
• Re-configuring standard keybindings (with a few minor exceptions). Actually, stock Emacs keybindings are just fine, and users should not be surprised and feel at home instantly. Everything else is bound under the leader / local leader key.
• Re-creating complex functionality where a 3rd-party package would be a better fit. There are a few exceptions in Emacs ONBOARD, e.g. it includes some convenience to manage Treesitter grammars.

Much Better Defaults

Some features – without any dependencies:

• Leader key & Localleader key bindings (easy to extend/change). It gives you quasi-infinite room for your own keybindings under the leader prefix.
  • Graphical Emacs: the default leader key is C-,; reach the local leader via C-, C-,.
  • Emacs in the terminal: the default leader key is C-z, and the local leader C-z C-z.
  • Works with Evil mode (Vim keybindings etc. in Emacs) – example config here; e.g. the leader key could be just , and the local leader , ,; or SPC as the leader and SPC SPC as the local leader – or something else.
  • Three options for leader keybindings (customizable via GUI):
    1. Use the default leader keymap with many useful bindings.
    2. Don’t like the default leader keybindings? Select the empty eon-leader-user-map keymap to roll your own keybindings under the leader.
    3. Bind any keymap you like to the leader key.
• Check-parens-mode: Emacs warns you before accidently saving Lisp source code with mismatched parens or quotes.
• Vertical “fuzzy” completion for commands, files, etc. in the minibuffer (built-in fido-vertical-mode).
• Lets you customize the most important preferences in Emacs’ Customization GUI: <leader> x C.
• Toggle between your light/dark theme via <leader> x t; and run own Elisp code triggered by switching themes, e.g. for adjusting fonts and other personal styling, depending on the light/dark theme variant.
• MacOS ready: the <Command> key acts as <Ctrl> key, and the <Option> key acts as <Meta> key.
• Clipboard integration just works – even on Windows.
  • WSL (Windows Subsystem for Linux) copy/paste between Windows apps and Emacs.
  • Copy the path of the current file to the clipboard via M-x eon-copy-file-path.
• Tree-sitter grammar registry: handle language grammars and trigger build/install declaratively via eon-treesitter-ensure-grammar and/or interactively via M-x eon-treesitter-install-all.
• Smooth pixel-based scrolling (Emacs doesn’t do that by default).
• Basic Org mode setup to get started.
• Garbage Collection tuning: includes ”The Emacs Garbage Collection Magic Hack”.
• The package manager is pre-configured with MELPA: install from over 5500 Emacs packages right away.
• Makes it easy to set the fonts you like – all options in one place.
• Dired, the most powerful file manager in existence …
  • doesn’t accumulate used buffers.
  • uses the OS system trash, instead of deleting files right away.
  • opens files in desktop apps via M-RET.
  • clean directory listings per default in Dired, toggle file infos via (.
• Visit any file when the file name is under the cursor: <leader> f p.
• Kill all buffers at once via <leader> b K.
• Access Shell- and Eshell buffer via <leader> e s and <leader> e e
• Quickly reach the *scratch* buffer via <leader> z.
• Visit any URL in your browser via <leader> g w and <leader> g W in the built-in Emacs web browser.
• Emacs saves versioned backups of your files to ~/.emacs.d/backup/ before editing.
• Send emails directly from Emacs: includes an SMTP-template for you to get started.
• … and much more.

Getting Comfortable

The seemingly weird keybindings are not what make Emacs – these are in fact secondary. All these keybindings are just convenience shortcuts to use commands, but they are not the commands themselves. The commands are the really interesting things – and they are just functions. Literally all interactions in Emacs are commands – and therefore functions. Every keystroke calls a function; even hitting the key e while writing ordinary text. That way, Emacs can actually be acknowledged as the purest embodiment of the “Unix philosophy” (nevertheless Emacs is often accused as “monolithic”, which is really funny).

Emacs has Only 3 Really Important Keybindings:

M-x – Press <Alt>+<x> to show all commands (a.k.a “interactive” functions).

C-g – Get out! Press <Ctrl>+<g> to cancel whatever happens (or hit 3x <ESC> in utter panic – same effect!).

C-] – Get out of recursive minibuffers, also reachable via M-x abort-recursive-edit.

Further Examples:

• M-x customize-group Set preferences via GUI – no need to write Emacs Lisp code.
• M-x list-packages Install 3rd-party packages (the “Emacs app store” or “Emacs marketplace” cough-cough capitalism cough-cough).
• M-x help to reach the ultimate help menu.
• M-x describe-symbol Read the documentation of each function/variable (and more).

Why Yet Another Emacs Starter Kit?

Legit question. Well, when I was setting up a VM to test some things, I wished I had a one-file-config that I can simply drop in and have a sane Emacs environment in no time.

And later then, when I was cleaning up my Emacs config, I realized that I haven’t touched some parts within the last months or so. They just worked incredibly well.

So I stripped out those parts and put it all in one file, and made them my core config. Then added some grooming to make everything digestable for the public, and – here we are.

Actually I use not only that config file, but have my Emacs config split into several modules – an extension layer where 3rd-party packages are configured, configs for programming languages, etc. It’s available too – and surprisingly – it’s called Emacs ONTOP.

… but this is the 💝 piece.

What is Emacs, Anyway?

It’s often described as an ancient, weird Editor. Some call Emacs jokingly as a “operating system” – but that’s actually not so far from the truth. Like almost anything, it depends on the perspective – it depends on what categories someone is used to think in. To make it short, Emacs may be best understood as a text-based fully introspectable and programmable computing environment. Emacs is probably the closest thing to the mythical Lisp Machines.

Some examples: The defining editor component of Emacs is just one thing; the VIM editor has been implemented in Emacs too, called “Evil” mode. Emacs makes Git a joy (Magit package) and has Org mode, which unifies organizing your life, publishing and is more powerful than Jupyter notebooks. At least one (desktop) window manager has been implemented in Emacs. Webservers and even a video editor were built in Emacs too – the list goes on and on.

Well, the only problem (as I see it) is: Emacs is tied to the implementation of its underlying Lisp engine right now, which is essentially single-threaded and not that performant for advanced applications (well, there are some tricks). But when it comes to what can be expressed as text in the widest sense (and most programming is text-based), there’s nothing else that comes even close.

Credits

Emacs ONBOARD has grown over the years, influenced by hundereds of dotemacs configs and blog posts. As it wasn’t intended as a public endeavor from the beginning, it’s now impossible to trace back what originated where; so you might encounter code that you’ve seen somwhere else before. Recently adopted some ideas from Minimal Emacs (mostly tweaking details) and Doom Emacs.