:config literate

This module has no dedicated maintainers. Become a maintainer?

This module has no flags.

This module doesn’t install any packages.

No hacks documented for this module.

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

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")
#+end_src

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

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

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

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

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)

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.