🚀 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). Consider it as a “normalize.css”, but for Emacs.

Emacs ONNBOARD 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, and without re-inventing the wheel:

• Ergonomic leader key / Localleader key menus (super easy to extend). That gives you infinite room for your own keybindings under the leader prefix!
  • Graphical Emacs: the leader key is C-,; reach the local leader via C-, C-,.
  • Emacs in the terminal: reach the leader menu via C-z, and the local leader via C-z C-z.
• Vertical fuzzy completion for commands, files, etc. in the minibuffer.
• Tree-sitter: handle language grammars and trigger build/install declaratively.
• Toggle between your light/dark theme via <leader> x t; you can also run own Elisp code triggered by switching themes, e.g. for adjusting fonts and other personal styling, depending on the theme variant.
• Smooth, pixel-based scrolling (Emacs doesn’t do that by default).
• Comprehensive Org mode setup to get started.
• MacOS ready: the <Command> key acts as <Ctrl> key, and the <Option> key acts as <Meta> key.
• Garbage Collector tuning: includes ”The Emacs Garbage Collection Magic Hack”.
• 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 at one place.
• The Emacs file-manager Dired doesn’t accumulate used buffers.
• Dired uses the system trash instead of deleting files right away.
• Clean directory listings per default in Dired, toggle via (.
• Hide and show hidden files (dotfiles) in Dired simply by typing .
• 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.
• Open files in desktop apps via M-RET (uses xdg-open; Linux only for now).
• Visit any file when the file name is under the cursor: C-z C-..
• Kill all buffers at once via M-x eon-kill-buffers.
• Open Shell- and Eshell buffer via C-z e s and C-z e e
• Quickly reach the *scratch* buffer via C-z s s.
• Visit any URL in your browser via C-z g w, and via C-z g W in Emacs built-in browser.
• Emacs saves versioned backups of your files to ~/.emacs.d/backup/ before editing.
• Sending emails directly from Emacs: includes an SMTP-template for you to get started.
• … and much more sensible presets.

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.