• Forewords
  • How it works
  • Prerequisites
  • Installation
• Organisation
  • Look and Feel
  • Workflow
  • Projects
  • Packages
  • General
• Feedback
• License

This literate Emacs configuration is based off Doom Emacs. It differs in how the configuration is organised. Most literate configurations are composed of a single Org file that is tangled into a .el file. I quickly found that approach difficult to maintain and work with, quickly approaching Emacs Bankruptcy.

Note: Most of the configurations here are copy/pasted from the package repositories README.md or other sources. I added attribution/source wherever possible.

My approach to configuration organisation is to split into logical units that can be updated independently. This means both the source configuration (org file) and the output (elisp file) are maintained independently from one unit to the other. Ideally it should be easier to work with this approach by having less lines of code per file and having files enforcing organisation.

But first let’s start with an obligatory screenshot:

This configuration is organised in a variety categories (see Organisation for details). This forces me to segregate configuration into files (per category) and keep the over all length of these to a level I’m comfortable with.

The current file you’re reading (Emacs.org) is tangled into config.el, this file is loaded by Doom Emacs on start up. The section down below is responsible for loading the individual section’s tangled file, in turns this loads the entire configuration.

(load "~/.config/doom/.elisp/general.el")
(load "~/.config/doom/.elisp/ui.el")
(load "~/.config/doom/.elisp/fonts.el")
(load "~/.config/doom/.elisp/keybindings.el")
(load "~/.config/doom/.elisp/writing.el")
(load "~/.config/doom/.elisp/coding.el")
(load "~/.config/doom/.elisp/version-control.el")
(load "~/.config/doom/.elisp/project-management.el")
(load "~/.config/doom/.elisp/org-everything.el")
(load "~/.config/doom/.elisp/other.el")

TODO: Test loading .el files via glob. Ideally it should not cause any problem, but some keybindings might be overwritten here and there.

Doom Emacs loads init.el from the user’s configuration directory (~/.config/doom/). This file is responsible for activating Doom Emacs modules.

In order to tangle the different sections you’ll need to run the following command:

$ ~/.emacs.d/bin/org-tangle ~/.config/doom/config

Alternatively you can use the make command to tangle your configuration intelligently and additionally run doom sync.

The command above will tangle the Org files in the user’s directory. The sections define the output’s location via property headers such as:

#+property: header-args :tangle .elisp/general.el

WARNING: Each category file has property headers indicating the tangle’s output file. Using :tangle yes in src blocks inside the files will cause the output file to be overwritten by the single block. Instead simply use begin_src / end_src without :tangle.

This is a list of applications that need to be installed previously to enjoy all the goodies of this configuration.

• ag (Silver Searcher) or rg (ripgrep)
• git
• make

See Doom Emacs > Version Control.

This configuration also requires two fonts that will require to be installed in the system to properly load the Look and Feel:

• JetBrains Nerd Font
• Fira Sans

See font installation instructions in Doom Emacs > Fonts.

You’ll need to execute two commands in order to get this configuration setup. Firstly you’ll need to clone the project and then run the make command in order to compile and execute doom sync.

Important: Be sure to back up your previous configuration.

$ git clone https://github.com/desyncr/.doom.d ~/.config/doom
$ cd ~/.config/doom
$ make

Fonts, Themes, Icons and such. This section (and subsections) are related to look and feel configuration options and packages.

Ideally if this configuration doesn’t load or I intentionally disable it the overall Emacs workflow should remain intact. Meaning that I could work almost as normal.

Keybindings for common commands and shortcuts for different operations as well and bindings for specific packages should be here.

Programming related packages and configuration settings go here. Primarly sorrounding LSP-mode and related.

Section sorrounding Git and Magit configuration and options. Nothing else is required anyways.

Configuration related to how to work around projects, workspaces, bookmarks and moving around the file system.

Org related configuration, including a miriad of org-related packages such as org-roam, org-agenda, org-tasks etc.

General purpose section for tools I’m trying out or doesn’t fit any other category.

Section for prose writing related configurations. This section is rarely updated.

If you’d like to contribute to the project or file a bug or feature request, please visit the project’s page.

The project is licensed under the GNU GPL v3 license. Which means you’re allowed to copy, edit, change, hack, use all or any part of this project as long as all of the changes and contributions remains under the same terms and conditions.