Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/monkeyjunglejuice/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.
https://github.com/monkeyjunglejuice/emacs.onboard

better-defaults emacs emacs-config emacs-configuration emacs-customizations emacs-lisp emacs-starter-kit learn-emacs leave-the-yak-alone onboard onboarding vanilla-emacs yak-shaving

Last synced: 26 days ago
JSON representation

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

Awesome Lists containing this project

README 

        
* 🚀 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  key acts as  key, and the  key acts as  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 pre-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 file-manager 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"  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 + to show all commands



"C-g" — Get out! Press + to cancel whatever happens (or hit 3x  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.

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