:config literate

Disguise your config as documentation

1. Description

This module enables support for a literate config.

1.1. Maintainers

This module has no dedicated maintainers. Become a maintainer?

1.2. Module flags

This module has no flags.

1.3. Packages

This module doesn’t install any packages.

1.4. Hacks

No hacks documented for this module.

2. Prerequisites

This module has no external prerequisites.

3. TODO Usage

This module’s usage documentation is incomplete. Complete it?

This module automatically tangles $DOOMDIR/config.org to $DOOMDIR/config.el when $ doom sync is executed. Will also auto-tangle when saving an org file in your $DOOMDIR (see Configuration below on how to disable it).

4. Configuration

4.1. Change the location of config.org

The +literate-config-file variable controls where to look for your config.org. To change this it must be modified early – in $DOOMDIR/init.el or $DOOMDIR/cli.el.

Source blocks needs to be in some language to be automatically tangled, for example #+begin_src emacs-lisp, but it doesn’t matter what language is used. All blocks are tangled to config.el, but elisp gives correct syntax highlighting. If you don’t want to specify language in block you can also enforce tangling by adding #+begin_src :tangle yes

4.2. Change where src blocks are tangled or prevent it entirely

By default, this module tangles all emacs-lisp src blocks to config.el unless otherwise specified.

To specify otherwise use the :tangle parameter to:

  • Specify a destination other than config.el: :tangle packages.el
  • Disable tangling of the block altogether with :tangle no
  • Or force non-elisp src blocks to tangle somewhere

For example:

#+begin_src emacs-lisp :tangle no
(message "Don't tangle me")

#+begin_src emacs-lisp :tangle packages.el
(package! my-package)
(package! other-package)

#+begin_src bash :tangle ~/.dotfiles/bin/script.sh :tangle-mode (identity #o755)
#!/usr/bin/env bash
echo Hello world

#+begin_src bash :tangle ~/.dotfiles/bin/script.sh :shebang "#!/usr/bin/env bash"
echo Hello world

More information about babel src blocks and the parameters they support can be found in the Org manual.

4.3. How to disable tangle-on-save

There are occasions where tangling on save may be undesirable. Maybe it’s too slow, produces too much noise, or happens too often (on unrelated org files in your $DOOMDIR). This behavior can be disabled with:

;; add to DOOMDIR/config.el
(remove-hook 'org-mode-hook #'+literate-enable-recompile-h)

5. Troubleshooting

5.1. How to tangle to DOOMDIR/init.el

If your literate needs are more complex (e.g. you want to make your init.el literate), this module won’t cut it. init.el is loaded long before config.org is tangled in the $ doom sync process.

However, Doom comes with a bin/org-tangle script which can be used to tangle arbitrary org files from the command line. Use it to create your own compilation workflows. This is much faster than using org-babel-load-file directly to load your literate config every time Doom is started.

6. TODO Appendix

This module has no appendix yet. Write one?