emacs.onboard

emacs.onboard copied to clipboard

• 🚀 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? 🤯

[[file:misc/emacs-onboard.jpg]]

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 [[https://orgmode.org][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][The Emacs Garbage Collection Magic Hack]]".
• Package manager is configured with [[https://melpa.org/#/][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 [[https://github.com/monkeyjunglejuice/emacs.onboard/releases/latest/download/onboard.el][onboard.el]]

2. Open a terminal

3. Run the shell command: ~emacs -q --load ~/path/to/onboard.el~

** INSTALL

1. Clone this repository: #+begin_src shell git clone https://github.com/monkeyjunglejuice/emacs.onboard.git ~/.emacs.onboard #+end_src

2. Put this in your Emacs init file #+begin_src emacs-lisp (load-file (expand-file-name "~/.emacs.onboard/onboard.el")) #+end_src

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>+ to show all commands

"C-g" — Get out! Press <Ctrl>+ 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 [[https://github.com/monkeyjunglejuice/emacs.ontop][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.