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. Elsewhere
5.1. In my garden
Notes that link to this note (AKA backlinks).