🚀 ONBOARD — 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 is a portable starter-kit for Emacs without any 3rd-party packages. It’s vanilla Emacs, but gives you a better user experience, without relying on additional 3rd-party packages.

It’s all built-in – all onboard.

✔ One single file

✔ Beginner-friendly

✔ Only built-in packages

✔ Convenient drop-in config

Features

Emacs ONBOARD gives you much better defaults, for instance:

• Vertical completion for commands, files, etc. in the minibuffer.
• Toggle between your light/dark theme via F12; you can also run own Elisp code triggered by switching themes, e.g. for adjusting fonts and other personal styling, depending on the theme.
• Smooth, pixel-based scrolling (Emacs doesn’t do that by default).
• Comprehensive Org mode setup.
• MacOS: the <Command> key acts as <Ctrl> key, and the <Option> key acts as <Meta> key.
• More room for your own keybindings: use C-z ... as additional prefix key.
• Garbage Collector tuning: includes ”The Emacs Garbage Collection Magic Hack”.
• Package manager is configured with MELPA: install from over 5500 Emacs packages right away.
• Install Emacs packages declaratively (eon-package 'install '(the-matrix-theme)).
• Makes it easy to set the fonts you like – all options at one place.
• The Emacs filemanager Dired doesn’t accumulate used buffers any more.
• Dired uses the system trash instead of deleting files right away.
• Clean directory listings per default in Dired, toggle via S-(.
• Hide and show hidden files (dotfiles) in Dired simply by typing .
• Clipboard integration works perfectly.
• 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.
• WSL (Windows Subsystem for Linux): copy/paste between Windows apps and Emacs.
• 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 M-z w w, and via M-z w 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.

TRY IT

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

Tested with:

• [X] Emacs 29.2 from Homebrew on MacOS Sonoma 14.2.1
• [X] Emacs 28.1 on Debian Stable
• [X] Emacs 28.1 from Guix

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. (e.g. with Emacs ONTOP, an extension layer on top of Emacs ONBOARD)
• 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.