🚀 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 ONBOARD is 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 from your init.el

Vastly Better Defaults

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

• Ergonomic leader key & Localleader key menus (easy to extend / change). That gives you 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 seamlessly with Evil mode (Vim keybindings etc. in Emacs); e.g. the leader key could be just , and the local leader , ,.
• Vertical fuzzy completion for commands, files, etc. in the minibuffer (built-in fido-vertical-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: handle language/grammars and trigger build/install declaratively.
• Smooth, pixel-based scrolling (Emacs doesn’t do that by default).
• Basic Org mode setup to get started.
• Garbage Collector 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 (Linux).
  • opens files in desktop apps via M-RET (uses xdg-open; Linux only for now).
  • shows directory listings per default in Dired, toggle file infos via (.
  • hides hidden files (dotfiles) per default, show them by simply hitting .
• 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

(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. 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 …

… but this is the 💝 piece.

Backwards-compatibility follows the Emacs version 28.2 in Debian Stable.

• Emacs 26 and Emacs 27 are no longer supported since 27.01.2024.

Goals

• 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. 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 intertwined, but easily modificable and separately usable.

Non-goals

• Providing a whole new experience like Spacemacs or Doom-Emacs.
• Re-configuring keybindings (with few exceptions).
• Pre-configure everything and the cat’s pillow (if you know cats …).
• (Re)creating 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.