MinEmacs is a lightweight Emacs configuration framework. The keybinding is inspired by Doom Emacs.
I was using Doom Emacs, which I initially considered to be a remarkable software that introduced me to the world of Emacs. Nonetheless, my experience with it turned out to be less enjoyable later.
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 framework that is both robust and straightforward. Doom Emacs
seemed like a suitable choice initially. However, before I started this 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. 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 && emacsBy executing this command, the repository will be cloned, and Emacs will be launched. During the initial run, Emacs will automatically install the necessary packages.
Please note that I’m using a fresh Emacs (29.0.91 or 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. Furthermore, 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!
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:
- The
~/.minemacs.d/modules.elfile contains a list of enabled modules and a list of disabled packages (minemacs-core-modules,minemacs-modulesandminemacs-disabled-packagescan be set in this file). - The
~/.minemacs.d/config.elfile contains the user configuration and customization, you can think of it as yourinit.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.
- The
~/.minemacs.d/early-config.elfile 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. - The
~/.minemacs.d/init-tweaks.elfile is loaded at an early stage of theinit.elfile. 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_DIRorMINEMACSDIR: 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 framebackground-alphato 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 ininit.el, this can be useful if you use~/.minemacs.d/init-tweaks.elto implement the functionalities used by MinEmacs and missing from your Emacs version.MINEMACS_IGNORE_CONFIG_EL,MINEMACS_IGNORE_MODULES_EL,MINEMACS_IGNORE_EARLY_CONFIG_ELandMINEMACS_IGNORE_INIT_TWEAKS_EL: Ignore loading, respectively, the user configuration files~/.minemacs.d/config.el,~/.minemacs.d/modules.el,~/.minemacs.d/early-config.elet~/.minemacs.d/init-tweaks.el.MINEMACS_IGNORE_USER_CONFIG: Ignore loading all user configuration files (present in~/.minemacs.d, or directory pointed by$MINEMACSDIR).
If you experienced an issue with MinEmacs, you can check the FAQ, check open issues or open a new one.