Emacs Substrate

A clean basis to organically grow your config onto.

     .⌒.      ▗▄▄▖▗  ▖ ▗▖  ▗▄  ▄▄      ▄▄ ▗  ▖▗▄▄  ▄▄ ▄▄▄▖▗▄▄  ▗▖ ▄▄▄▖▗▄▄▖
   .#   #.    ▐   ▐▌▐▌ ▐▌ ▗▘ ▘▐▘ ▘    ▐▘ ▘▐  ▌▐  ▌▐▘ ▘ ▐  ▐ ▝▌ ▐▌  ▐  ▐
  /       \   ▐▄▄▖▐▐▌▌ ▌▐ ▐   ▝▙▄     ▝▙▄ ▐  ▌▐▄▄▘▝▙▄  ▐  ▐▄▄▘ ▌▐  ▐  ▐▄▄▖
 (,,,___,,,)  ▐   ▐▝▘▌ ▙▟ ▐     ▝▌      ▝▌▐  ▌▐  ▌  ▝▌ ▐  ▐ ▝▖ ▙▟  ▐  ▐
     ) (      ▐▄▄▖▐  ▌▐  ▌ ▚▄▘▝▄▟▘    ▝▄▟▘▝▄▄▘▐▄▄▘▝▄▟▘ ▐  ▐  ▘▐  ▌ ▐  ▐▄▄▖
    (___)

NOTICE: Requires Emacs 29.1 or newer.

Description

This is a minimal Emacs base config. Here's the short of the philosophy:

• Focus on using default, built-in Emacs behaviour
• Emacs-lisp centric, encourage configuration through code
• Provide an upgrade path for Substrate
• Stay minimal, only include as little packages and config as possible
• Encourage tweaking and coding of Emacs and its ecosystem
• Keep to the project vision, even though users are free to turn features off

Installation

With automated script

Copy and paste the following into a terminal:

curl https://raw.githubusercontent.com/Etenil/emacs-substrate/refs/heads/main/installer/installer.sh | bash

This will install emacs-substrate in your ~/.emacs.d folder. You can set the environment variable EMACS_DIR before running the script to install it in a different folder.

Manually

To install emacs-substrate, clone this repository somewhere, then create the following 2 files:

;; ~/.emacs.d/early-init.el
(add-to-list 'load-path "<path-where-emacs-substrate-was-cloned>")

(require 'early-substrate)

;; ~/.emacs.d/init.el
(require 'substrate)

;; Set custom variables here

(substrate-init)

;; The rest of your config below

How to update

Emacs-substrate's code lives within the local clone of the git repository. Updating your installation is as simple as running git pull within that folder. If using the installer, do as follows:

pushd $HOME/.emacs.d/emacs-substrate
git pull
popd

And restart emacs.

Customisation

Available settings

Substrate can be configured through Emacs's built-in customisation framework. To access it, use M-x customize and search for substrate. Alternatively, set the options with setopt in your init file. The available options are:

• substrate-enable-windmove: Enable windmove to hop around windows with ctrl+arrow - default t
• substrate-display-startup-help: Show a help window on startup - default t
• substrate-enable-which-key: Use which-key to list available key combos - default t
• substrate-display-line-numbers: Display line numbers on buffers - default t
• substrate-enable-cua-mode: Enable CUA mode (C-c for copy, C-p for paste etc.) - default t
• substrate-configure-theme: Configure the default theme - default t
• substrate-enable-evil: Enable evil-mode and the Vi-like keyboard mapping - default nil

If you'd rather use setopt to configure those variables, it can be used like so:

;; Configure all the opposite defaults for substrate
(setopt substrate-enable-windmove nil)
(setopt substrate-display-startup-help nil)
(setopt substrate-enable-which-key nil)
(setopt substrate-display-line-numbers nil)
(setopt substrate-enable-cua-mode nil)
(setopt substrate-configure-theme nil)
(setopt substrate-enable-evil t)

Setting a different theme

To set a different theme, first disable the default theme from Substrate like so:

(setopt substrate-configure-theme t)

Then set your favourite theme. Instead of using load-theme, use substrate-set-theme, as it will also work when running emacs as a daemon.

(use-package nord-theme
    :config (substrate-set-theme 'nord))

;; Or

(straight-use-package 'nord-theme)
(substrate-set-theme 'nord)

Screenshots

What you should see on opening Emacs up with Substrate installed: a simple splash screen, and the help-quick display at the bottom.

Basic code editing: line numbers and hl-line-mode.

Requirements

• Emacs 29.1 or later.
• Git

Credits

This project is a radical fork of Emacs-bedrock

Maintainer of Emacs-substrate:

• Gene Pasquet

Creator and maintainer of Emacs-bedrock:

• Ashton Wiersdorf