🚀 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.

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 ONBOARDing made Easy

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

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

Vastly Better Defaults

Some features – without any dependencies or “re-inventing the wheel”:

• Leader key & Localleader key menus (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.
  • 3 options for leader keybindings (customizable via GUI):
    • Use the default leader keymap with many useful bindings.
    • Don’t like the default leader keybindings? Select the empty eon-leader-user-map keymap to roll your own keybindings under the leader.
    • Bind any keymap you like to the leader key.
• Vertical “fuzzy” completion for commands, files, etc. in the minibuffer (built-in fido-vertical-mode).
• Check-parens-mode: Emacs warns you before accidently saving Lisp source code with mismatched parens or quotes.
• 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.
  • Browse your kill ring (the Emacs “clipboard”) via M-y and insert directly from a selection preview.
• Tree-sitter grammar registry: handle language grammars and trigger build/install declaratively via eon-treesitter-ensure-grammar and/or 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 o.
• Kill all buffers at once via <leader> b K.
• Open 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.

TRY IT

1. Download eon.el
2. Open a terminal
3. Run the shell command: emacs -q --load ~/path/to/eon.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

Getting Comfortable

The seemingly weird keybindings are not what make Emacs. They 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. What that means:

Emacs has Only 2 Really Important Keybindings:

“M-x” – Press <Alt>+<x> to show all commands

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

Examples:

• “M-x list-packages” Install 3rd-party packages (the “Emacs app store” or “Emacs marketplace” cough-cough capitalism cough-cough)
• “M-x check-parens” Check if all parens match (within Emacs Lisp code)
• “M-x help” to reach the ultimate help menu

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. I’m making that available too; surprisingly, it’s called Emacs ONTOP.

… but this is the 💝 piece.

Backwards-compatibility follows the Emacs version in Debian Stable.

Goals

• Be 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.
• Portable: Should work on recent Linux/Unix, Windows and MacOS systems, while maintaining reasonable backwards-compatibility.
• Beginner-friendly: Novice Emacs users willing to touch Elisp code should be able to follow (most of the time). Elisp code should be free from errors and warnings.
• Use only 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.
• Don’t be invasive: Provide an Emacs config as a library; don’t try to be a replacement, rather an add-on.
• Documentation is first class; it should be clear why something is in the code.
• Modular simplicity: Code should not be tightly coupled, but easily modificable and separately usable.

Non-goals

• Providing a whole new experience like Spacemacs or Doom-Emacs.
• Re-configuring standard keybindings (with few exceptions).
• (Re)creating complex functionality where a 3rd-party package would be a better fit.

Credits

Recently adopted some ideas from Minimal Emacs (mostly tweaking details) and Doom Emacs.