MinEmacs is a lightweight Emacs configuration framework.
Since many years, Emacs forms the foundation of my workflow, serving as my go-to tool for various tasks such as document writing, academic paper writing, programming in multiple languages, email management, and staying updated with news, among other things.
Hence, I wanted a VIM-style framework that is both robust and straightforward.
Spacemacs was the first framework I’ve tested, I liked the idea of using SPC
as
a leader key, but I didn’t like the way Spacemacs packs things in layers, and
imposes a unique way of writing your configuration.
I discovered then Doom Emacs, which I found a remarkable software that
introduced me to the world of Emacs. Nonetheless, my experience with it turned
out to be less enjoyable later. In fact, before I started the MinEmacs project
back in September 2022, I encountered numerous issues with Doom Emacs.
Occasionally, after running the doom upgrade
command, everything would cease to
function properly. These problems always seemed to arise during my busiest days,
causing unnecessary additional stress. To be frank, at that time, Doom Emacs
started to feel overly complex as a configuration framework. It incorporated a
command line interface, an extensive library with extra features, numerous
unnecessary hacks to tweak Emacs behavior for a negligible improvement in
startup time, configuration modules that tightly combined various packages in an
opinionated manner, CI commands, and even a profile manager! Each of these
features introduced extra complexity and more failure points at every layer.
As a result, MinEmacs emerged as my personal configuration framework for Emacs, and it continues to serve that purpose. I’m trying to tailor it to my specific needs while maintaining its modularity and portability. You can refer to the change log for more information about the evolution of MinEmacs. However, I have no intention or availability to create an alternative to Doom Emacs or Spacemacs. While I find joy (like every other Emacser out there) in tinkering with Emacs, MinEmacs remains just a tool that I use in my everyday work, and that I like to share with other Emacsers. However, please note that I am not really interested in becoming a full-time maintainer of this tool that I would only use to maintain itself!
Open a shell and run:
git clone https://github.com/abougouffa/minemacs.git ~/.emacs.d && emacs
By executing this command, the repository will be cloned, and Emacs will be launched. During the initial run, Emacs will automatically install the necessary packages.
[!IMPORTANT] Please note that I’m using a fresh Emacs 29 built from source on a Manjaro Linux system. I have enabled basic Github CI actions to automatically test running Emacs 28, 29 and a fresh 30 build on Ubuntu Linux and MacOS and Emacs 28 on Windows. These actions ensure that MinEmacs is “runnable”; with all modules enabled on these systems. However, more testing should be done to validate the configuration on systems other than Linux.
I’m trying to support at least Emacs 28.1, so I back port some of the new functions/macros I use to Emacs 28. Furthermore, for Emacs 28 and earlier, MinEmacs includes the
me-compat
module which loads thecompat
package at early stage (just after bootstrappingstraight
anduse-package
), this can facilitate porting MinEmacs to earlier Emacs versions. However, I’ve never tested MinEmacs with versions earlier than 28.1, and I don’t plan to do so!
To personalize MinEmacs, you can incorporate a specific set of files within the
default user configuration directory, which is located at ~/.minemacs.d
.
However, if you prefer to use a different directory, you have the flexibility to
do so by setting the MINEMACSDIR
environment variable.
There are two main files that can be added in the ~/.minemacs.d
directory:
~/.minemacs.d/modules.el
file contains a list of enabled modules and a
list of disabled packages (minemacs-core-modules
, minemacs-modules
and
minemacs-disabled-packages
can be set in this file).~/.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).
In my workflow, I use mainly the same configuration files across all my machines (which are traditionally shared in my dotfiles repository). However, I have some machine-specific (local) configurations that I like to load. For example, to overwrite the email address on my workstation.
For this purpose, MinEmacs will also check for files in
~/.minemacs.d/local/{early-config,config,modules}.el
and load them if they
exists.
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.
~/.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.~/.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_ALWAYS_DEMAND
: Load all packages immediately (this works by setting
use-package-always-demand
to t
and use-package-always-defer
to nil
.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.MINEMACS_IGNORE_USER_CONFIG
: space-separated values, used to disables loading
~/.minemacs.d/<file>.el
user configuration files. Accepted values for <file>
are: early-config
, init-tweaks
, modules
, config
, local/early-config
,
local/init-tweaks
, local/modules
and local/config
. Use all
to disable all
user configuration files.MINEMACS_LOAD_ALL_MODULES
: Load all modules (without taking
~/.minemacs.d/modules.el
into account).MinEmacs defines several keybindings, mainly using general.el. To see the full
list of keybindings defined using general, you can type SPC h g
or M-x
general-describe-keybindings
.
More information about customization variables, functions and commands defined by MinEmacs can be found in the documentation generated from the source code.
If you experienced an issue with MinEmacs, you can check the FAQ, check open issues or open a new one.