doomemacs/modules/config/literate/README.org

config/literate

• Description
  • Maintainers
  • Module Flags
  • Plugins
• Prerequisites
• Features
• Configuration
  • Change the location of config.org
  • Change where src blocks are tangled or prevent it entirely
• Troubleshooting
  • How to tangle to DOOMDIR/init.el
  • How to disable tangle-on-save

Description

This module enables support for a literate config.

A literate config consists of a DOOMDIR/config.org, which can be tangled to any file(s) you like. By default, elisp src blocks are tangled to config.el whenever doom sync is executed.

Maintainers

This module has no dedicated maintainers.

Module Flags

This module provides no flags.

Plugins

This module installs no plugins.

Prerequisites

This module has no prerequisites.

Features

• Automatically tangle config.org to config.el when saving.

Configuration

Change the location of config.org

The +literate-config-file variable controls where to look for your central config.org. However, it must be changed early, in DOOMDIR/init.el or DOOMDIR/cli.el.

• Source blocks needs to be in some language for example #+BEGIN_SRC elisp but currently it does not matter what language is used, it tangles all to config.el. elisp gives correct syntax highlight. If you don't want to specify language in block you can also enforce tangling by adding #+BEGIN_SRC :tangle

Change where src blocks are tangled or prevent it entirely

By default, this module tangles all elisp src blocks to config.org unless otherwise specified.

To specify otherwise, use the :tangle parameter to:

• Specify another destination, other than config.el, like packages.el
• Disable tangling of the block altogether
• Or force non-elisp src blocks to tangle somewhere

For example:

#+BEGIN_SRC elisp :tangle no
(message "Don't tangle me")
#+END_SRC

#+BEGIN_SRC elisp :tangle packages.el
(package! my-package)
(package! other-package)
#+END_SRC

#+BEGIN_SRC sh :tangle ~/.dotfiles/bin/script.sh
#!/usr/bin/env bash
echo Hello world
#+END_SRC

Troubleshooting

How to tangle to DOOMDIR/init.el

If your literate needs are more complex (e.g. you want to incorporate your init.el into your literate config), this module won't cut it. Doom comes with a bin/org-tangle script, which you can use to tangle arbitrary org files from then command line. Use it to create your own compilation workflows.

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)