One of my favourite new things in my Emacs rebirth was finding org-mode and learning that you can write your .emacs file in org-mode. But why do it?

Easy to read and write

The file itself is a document. I surround each bit of customization with explanatory text, so I can figure out what the heck is going on in more obscure settings. This is achievable by Elisp code comments, but I can also use the power of org-babel to call code from anywhere (in any language) and inject that into the document when required.

org-babel also makes it easy to do analysis on your .emacs file… within the .emacs file. You can search the file itself for strings like require 'package and build a table of packages you’re potentially loading.

And there’s a clear win when you can export the same file to HTML for easy reading.

Easy to organize

Part of the process of getting accustomed to Emacs is customizing it how you like. This means messing with your .emacs or custom.el file. After a while this gets unwieldy and it helps to organize the customizations.

Organizing things into systems and subsystems easily maps over to org-mode’s headings. At an overview level, my current setup looks like this:

Personal information

This is setting my preferred username and email address, since Windows doesn’t play nice with that.

Startup

This sets default load paths and where my custom.el file is.

Global config

This sets global things like minor modes, coding systems, custom key bindings and setting/disabling certain default Emacs settings.

Helper functions

Custom code that I find useful.

Tasks

From here it’s settings for certain modes (especially org-mode and the various programming modes) and helpful utilities.

This hierarchy makes it easy to quickly drill down to customization options. That’s if I don’t ninja there with org-goto or good ol’ isearch.

And since the hierarchy folds easily with TAB, I don’t have to see all the other stuff if I don’t want to.

You can achieve all this with a straight .el file with code folding, but it’s not quite as slick as org-mode.

Easy to export

I share my .emacs file on Github. There are a few settings that I don’t want to share. Maybe they are API Keys for easy login. Or just code that I don’t want to share. org-babel lets you easily mark things for non-export with a tag, so it can exist in my native .emacs file, but when I export to Github, only the things I want exported go there.

Just run org-org-export-to-org (that’s a lotta orgs) or C-c C-e O v if you have org-export-dispatch bound to C-c C-e.

How to do it?

I haven’t found a good way to have a pure org-babel mode config, but you can quickly shift control to one.

In your .emacs file:

(package-initialize)

(require 'org-install)
(org-babel-load-file "~/emacs/bew_config.org")

This sets up basic packages and org-mode. It then asks org-babel to load (and run) your config file.

Then in your config file (~/emacs/bew_config.org or whatever you like), write an org file using headings to organize the file.

I set file-wide settings of

#+PROPERTY: tangle yes
#+EXCLUDE_TAGS: noexport

which automatically tangles code blocks, and establishes the tag noexport which filters headings in your export.

For actual Emacs settings, write a code block like so:

#+begin_src emacs-lisp
(setq inhibit-startup-screen t)
#+end_src

Plus if you need that setting to be run right now, just C-c C-c in the block and it will run (but might add results underneath the block).

If you want to toggle off a code block (but not the whole section it’s in) just add :tangle no to the options:

#+begin_src emacs-lisp :tangle no
(brettw/broken-code-that-I-want-to-fix-later)
#+end_src

You can check out my .emacs file for inspiration (or offer advice - I’m always keen to improve my Emacs fu!)