Setting up a spacemacs literate config file


I spent a bit of time switching my spacemacs config in to a Literate configuration style.

1 Why?

I use spacemacs a lot. For coding, for writing, for work, for organisation, for my personal knowledge management. It's central to to most of my day-to-day activities on my computer. I've been using for maybe 4 years now, and have built up quite a mess of a configuration file with various tweaks over the years.

Given how much I use it, it seems sensible to give a bit of TLC to this configuration. I've tried to comment it as I've tweaked it, but it still has gotten messy. I've learned and copied a lot from other people's configs, so endeavouring to make my own readable to others seems like a good thing to do.

I'm also just keen to try out org-babel for some literate coding, and this is an easy way in to doing that.

2 What I did

Here's what I've done to get started on this.

2.1 File reorganisation

First off, I put my existing .spacemacs file into a folder structure where you can split it up into multiple files.

mkdir ~/.spacemacs.d
cp ~/.spacemacs .spacemacs.d/init.el

In classic refactoring fashion - just do this simple thing, and make sure that things still work.

2.2 Extract out user-config into own file

OK, after that, the next refactoring was to move move everything in the user-config function out in to it's own file, .spacemacs.d/user-config.el.

When its in its own file, you can source that from init.el like so:

(defun dotspacemacs/user-config ()
  (let ((uc (concat dotspacemacs-directory "user-config.el")))
 (message (concat "ds-d" dotspacemacs-directory))
 (load-file uc)))

(above source came from here: Spacemacs configuration in a structured org-mode file : emacs)

Again, check that everything still works fine afterwards.

3 Move config into an org file and set up tangling on it

The section on Converting your existing config files in Literature Configuration was really helpful for this. It recommends a great path for moving things incrementally to the literate configuration. Essentially you start off with one huge source block, and gradually split that up in to smaller blocks with org-babel-demarcate-block.

I did that, putting each new source block in to a logical org heading, and adding a bit of description and narrative around them. Each time I split out a new bit, I ran org-babel-tangle to check things were still working.

I have the following config properties at the top of the file:

#+property: header-args:elisp :tangle ~/.spacemacs.d/user-config.el :comments org

which says for all the elisp source blocks in this file, combine them together in to user-config.el when I tangle the file. And also include my narrative as comments.

So my user-config is now literally all in My Spacemacs User Config here in my wiki. As in, that is the file that I use to generate my .spacemacs/user-config.el that spacemacs runs. (The source is here.)

I like it, and think it works pretty well for config files. I'm going to try it on my org-roam config next.

4 Resources

5 Backlinks

This page last updated: 2020-11-27 Fri 16:47. Map. Recent changes. Source. Peer Production License. Webring: << random >>