1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
|
# 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:
```lisp
;; ~/.emacs.d/early-init.el
(add-to-list 'load-path "<path-where-emacs-substrate-was-cloned>")
(require 'early-substrate)
```
```lisp
;; ~/.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:
```lisp
;; 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:
```lisp
(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.
```lisp
(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, [modus-vivendi](https://protesilaos.com/emacs/modus-themes) active, and the `help-quick` display at the bottom.
Basic code editing: line numbers and `hl-line-mode`.
## Philosophy
- Maintainable: Substrate is a library and can be easily updated
- Unobtrusive: provide sound defaults but don't take over emacs's config system
- Minimal: only provide the minimum to get started and no more. Configuration is part of the Emacs'experience
## Requirements
Emacs 29.1 or later.
Emacs 29.1 is, as of 2023-09-04, the latest stable release. The specific features from Emacs 29.1 that Substrate relies on are:
- Enhancements to the built-in completion help (`completions-auto-select`, `completion-auto-help`, etc.)
- Built-in tree-sitter support
- Built-in LSP client (Eglot)
## Credits
This project is a radical fork of [Emacs-bedrock](https://codeberg.org/ashton314/emacs-bedrock)
Maintainer of Emacs-substrate:
- [Gene Pasquet](https://github.com/Etenil)
Creator and maintainer of Emacs-bedrock:
- [Ashton Wiersdorf](https://lambdaland.org)
G
|
