MinEmacs is a lightweight Emacs configuration framework. The keybinding is inspired by Doom Emacs.

I was using Doom Emacs, which I found an excellent piece of software that introduced me to the Emacs world. However, I have a not very pleasant experience with it.

I’m using Emacs at the core of my workflow, I use it to write documents, write academic papers, write programs in different programming languages, manage my emails, read news, etc.

Therefore, I want a robust yet simple framework. Doom Emacs was a good choice for me. But at the time of starting this project (September 2022), I was experiencing a lot of problems with Doom Emacs, sometimes I run a doom upgrade, and just after, nothing works properly! This kind of problems happen only in my most busy days, causing additional (unnecessary) stress to manage. And to be honest, Doom Emacs became a bit too much for a configuration framework! It implements a command line interface, a library with extra features, many unnecessary hacks that modifies Emacs behavior to gain 0.0001s of startup time!, configuration modules gluing a bunch of packages in an opinionated way, CI commands, and recently a profile manager! This adds extra complexity at each layer.

Because of that, MinEmacs started as (and still) a personal configuration framework for Emacs. I’m trying to make it fit my own needs, while keeping it modular and portable. However, I have neither the intention nor the time to create a Doom Emacs or Spacemacs alternative. Hacking Emacs brings a lot of fun, however, MinEmacs for me is just a tool that I use in my daily work, I’m not interested of becoming a full-time maintainer of a tool that I use just to maintain itself!

Open a shell and run:

git clone https://github.com/abougouffa/minemacs.git ~/.emacs.d && emacs

This will clone the repository and launch Emacs, which, in the first run, will install the required packages.

Please note that I’m using a fresh Emacs (Emacs 30.0.50) built from source on a Manjaro Linux system.

I’m trying to support at least Emacs 28.2, so I back port some of the new functions/macros I use to Emacs 28. In addition, for Emacs 28 and earlier, MinEmacs includes the me-compat module which loads the compat package at early stage (just after bootstrapping straight and use-package), this can facilitate porting MinEmacs to earlier Emacs versions. However, I’ve never tested MinEmacs with versions earlier than 28.2, and I don’t plan to do so!

You can customize MinEmacs by adding a set of special files under ~/.minemacs.d. This is MinEmacs’ default user configuration directory, however, you can use another directory by setting the MINEMACSDIR environment variable.

There are two main files that can be added in the ~/.minemacs.d directory:

1. The ~/.minemacs.d/modules.el file contains a list of enabled modules (both minemacs-core-modules and minemacs-modules can be set in this file).
2. The ~/.minemacs.d/config.el file contains the user configuration and customization, you can think of it as your init.el, which gets loaded at the end of MinEmacs’ init.el!

This repository contains skeleton files for modules.el and config.el (under skel/). We highly recommend following the same structure as in the skeleton files, specially the use of with-eval-after-load and use-package instead of using require directly (require loads the packages immediately, which increases the startup time of Emacs).

MinEmacs provides also some advanced customization files, these files can be used to tweak MinEmacs’ behavior, add some early initialization code, make MinEmacs runnable on older Emacs versions, etc.

1. The ~/.minemacs.d/early-config.el file is loaded at the end of MinEmacs’ early-init.el. You can use it to set up some early stuff like tweaking the UI, overwrite the variables set by MinEmacs, and so on.
2. The ~/.minemacs.d/init-tweaks.el file is loaded at an early stage of the init.el file. You can use it to do some useful stuff before MinEmacs starts to customize packages and load modules. This can be useful for porting MinEmacs to an older Emacs version by providing an implementation of new functions MinEmacs uses. See the init.el for more information.

You can customize MinEmacs’ behavior via some environment variables.

• MINEMACS_DIR or MINEMACSDIR: Path for MinEmacs user configuration directory, if not set, ~/.minemacs.d/ is used.
• MINEMACS_MSG_LEVEL: Change message log level, from 1 (only errors) to 4 (all messages).
• MINEMACS_VERBOSE: Be more verbose (useful for debugging).
• MINEMACS_DEBUG: Enable debugging at startup.
• MINEMACS_ALPHA: Set frame background-alpha to percentage (value from 0 to 100).
• MINEMACS_NOT_LAZY: Load lazy packages immediately after loading Emacs.
• MINEMACS_IGNORE_VERSION_CHECK: Do not perform version check in init.el, this can be useful if you use ~/.minemacs.d/init-tweaks.el to implement the functionalities used by MinEmacs and missing from your Emacs version.

If you experienced an issue with MinEmacs, you can check the FAQ, check open issues or open a new one.