tecosaur's Doom Emacs config, written as a literate Org file

One Org file, and everything else generated from it

The repository description is blunt: my configuration for Doom Emacs, and a mirror of the canonical repository at git.tecosaur.net. The README states that there is only one significant file, config.org, the configuration file, and that this generates the init.el, config.el and packages.el files, as well as about a hundred others, with a listing of the generated files published alongside. The primary language recorded for the repository is Org, and the topics say literate-configuration, which is the accurate description. The approach is the same one the LaTeX community has used for decades, where the document is the source and the code is an artefact of tangling it. Here the document is also the manual, because the same Org file is exported to HTML and to PDF, so the explanation of a setting sits next to the setting itself. The badges in the README header follow from that: an Emacs 30 badge, an Org literate config badge, a publish workflow badge, a package status badge and a funding badge.

The generated files are outputs, not the source

The distinction between config.org and the generated Elisp is the thing a new user has to internalise before editing anything. The tree at the root makes the layout clear: config.org, README.org, a lisp/ directory holding submodules for the author's own packages, a misc/ directory for resources, and a snippets/ directory. The README notes that resources are put in misc/ and that you may find submodules for packages of the author in lisp/. So the authored surface is small: one Org file, some resources, and a set of personal packages, and everything else is derived. This has an obvious benefit, which is that the published HTML and PDF are always in step with the code because they are the same document. It also has an obvious hazard, which is that editing a generated .el file looks like editing configuration and is silently discarded the next time the files are regenerated. For a user who intends to diverge from the author's setup, that means forking config.org and living in it, rather than patching the generated output and losing the work.

Installing it is really installing Doom

The installation block in the README is a shell snippet that does three separate things, and the reader should notice that the second one is the actual configuration hook:

git clone --recurse-submodules [email protected]:tecosaur/emacs-config.git ~/.config/doom
echo "(doom! :config literate)" > ~/.config/doom/init.el
git clone --depth 1 https://github.com/hlissner/doom-emacs ~/.emacs.d
~/.emacs.d/bin/doom install; ~/.emacs.d/bin/doom sync; ~/.config/doom/setup.sh

The first command clones the configuration with its submodules, which is required because the author's own packages arrive that way. The second writes a three-line init.el telling Doom to use the literate configuration, and the literate flag is what makes Doom tangle config.org into the Elisp it loads. The third clones Doom itself with a shallow history, installs it, syncs it and then runs the configuration's own setup.sh. The author is careful about expectations here, writing that this is mostly a personal note and pointing readers at the warning in the config, which is the right thing for someone to do with a setup that will rewrite parts of their Emacs configuration.

The publish workflow and the package status page

The repository publishes itself. The workflow badge in the README points at a GitHub Actions workflow named publish, and the artefacts it produces are the HTML version and the PDF version of the configuration, linked from the README title, plus a files listing that documents the hundred generated files. There is also a package status badge, and it points at an upgradable-packages.txt file and a pkg-status.svg, which is a small piece of engineering worth explaining because it solves a real problem for a literate configuration. When your configuration depends on a dozen Emacs packages, the question of which versions are known to work together is the question that bites, and a published status file with a badge next to it makes that answerable at a glance rather than by archaeology through commits. The repository also keeps a CHANGELOG-style history indirectly through the mirror, and the canonical upstream at git.tecosaur.net is the authoritative copy, with GitHub as a mirror, so the direction of any pull request is the opposite of the usual.

Why literate configuration, and what it costs

The approach has clear appeal for a configuration of this size. A Doom Emacs setup is not a small thing: it is a package list, a module selection, a set of keybindings, custom functions and a good deal of prose explaining why each choice was made. Writing that as Elisp means the explanation lives in comments that nobody reads, and writing it as a literate Org document means the explanation is the document and the code is extracted from it. The trade-off is that the format is not as forgiving as Elisp. Tangling is a step that can fail, the Org file has to be edited with the right conventions for the blocks to extract cleanly, and a reader who wants to change one setting has to find the right place in a long document rather than grep a function. For the author, who writes in Org anyway and publishes the same document as a manual, that trade is obviously worth it. For someone who wants a working Emacs and does not care to read, it is a different calculation, and the author says as much in the warning.

Where this configuration is the wrong choice

Four limits are clear. The first is that it is a personal configuration, and the README says so. The keybindings, the package versions, the modules and the custom functions are one person's working setup, and there is no compatibility matrix or support commitment. A team that standardises on an Emacs setup needs a configuration that a group owns, not one that a stranger published, because the next update of a package will arrive and somebody will have to reconcile it. The second is the mirror relationship, which inverts the usual workflow. The canonical repository is at git.tecosaur.net and GitHub is the mirror, so a fork and a pull request go to the wrong place unless you read the README carefully, and the branch here is master. The third is that the generated files create a trap. Anyone who edits config.el will lose the change at the next generation, and the failure is quiet. The fourth is the size of the commitment. A literate configuration of about a hundred generated files is a substantial artefact to take on for someone who wants an editor with a few packages in it, and the setup script and the submodule clone are more moving parts than a plain Elisp config requires.

Editorial conclusion

Adopt this configuration if you want a complete, opinionated Doom Emacs setup with an unusually clean source of truth, and you are willing to read a literate Org file rather than a pile of Elisp. Do not adopt it as a starting point you will not touch, since the configuration is one person's setup and the author describes it as mostly a personal note. Before you install, read the warning section in the published config, and remember that the generated files are outputs, so any change you want to keep belongs in config.org or in the author's submodules under lisp/, not in the .el files.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. tecosaur/emacs-config on GitHub