allenwoods / emacs.onboard

Single-file Emacs starter kit without 3rd-party packages. Almost vanilla Emacs, with just the right amount of sweetness to flatten the learning curve.

🚀 ONBOARD – Emacs onboarding made easy

Portable Emacs starter kit without any 3rd-party packages

Overwhelmed by the complexity of (excellent) Emacs distributions like Doom-Emacs or Spacemacs? You want to roll your own Emacs config bottom-up, but not overlook those easy-to-miss basics? Or you don’t want to configure Emacs, but … just use it??? 🤯

The ONBOARD Emacs starter is a clean slate to build upon. It’s almost vanilla Emacs, but gives you some convenience and a better user experience, without relying on other packages. It’s all built-in, all onboard.

✔ One single file

✔ Only built-in packages

✔ Beginner-friendly drop-in config

Why, oh 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 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 libraries – e. g. an extension layer where 3rd-party packages are configured, configs for programming languages, etc …

… but this is the 💝 heart piece!

TRY IT

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

INSTALL

1. Clone this repository: git clone https://github.com/monkeyjunglejuice/emacs.onboard.git

2. Put this in your Emacs init file:

(add-to-list 'load-path "/path/to/emacs.onboard")
(require 'init-onboard)

3. (Re)start Emacs

You don’t have a init file or don’t know where it is?

By default (freshly installed Emacs) there is no init file. 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
  • /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

Installation without Git

Some like it quick and dirty, eh? 🙈

1. Download init-onboard.el and rename it to init.el
2. Put it in your .emacs.d directory
3. (Re)start Emacs

or

1. Download init-onboard.el
2. Put this in your Emacs init file: (require 'init-onboard "/path/to/init-onboard.el")
3. (Re)start Emacs

Getting comfortable

The seemingly weird keybindings are not what make Emacs. They are in fact secondary. All those 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:

There are 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)
• “M-x check-parens” Check if all parens match (within Emacs Lisp code)
• “M-x help” to reach the ultimate help menu

Tested with:

• [X] Emacs 28.1 Guix build
• [X] Emacs 27.1 on Ubuntu 20.04 LTS
• [X] Emacs 26.1 on Debian 10.9.0
• [ ] Emacs 27 on Windows 10
• [ ] Emacs 26 on Windows 10
• [ ] Emacs 27 on MacOS
• [ ] Emacs 26 on MacOS

Goals

• Portable: Should work on recent Linux/Unix, Windows and MacOS systems; Emacs versions >= 26
• Beginner-friendly: Novice Emacs users willing to touch Elisp code should be able to follow
• 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
• New keybindings. However, they may be useful in certain circumstances
• 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

Contribute

You are welcome! Here’s the agenda what’s currently important/worked on:

• Testing the config on various Emacsen and operating systems
• Ensure portability between various host OS. All features should work in Linux, Windows and Mac equally well.