doomemacs/modules/config/literate/README.org

:config literate

• Description
  • Maintainers
  • Module flags
  • Packages
  • Hacks
  • Changelog
• Installation
• Usage
• Configuration
  • Change the location of config.org
  • Change where src blocks are tangled or prevent it entirely
• Troubleshooting
• Frequently asked questions
  • How do I tangle to $DOOMDIR/init.el?
  • How do I disable tangle-on-save?
• Appendix

Description   unfold

This module enables support for a literate config.

A literate config consists of a $DOOMDIR/config.org. All src blocks within are tangled $DOOMDIR/config.el, by default, when $ doom sync is executed.

Maintainers

This module has no dedicated maintainers. Become a maintainer?

Module flags

This module has no flags.

Packages

This module doesn't install any packages.

Hacks

No hacks documented for this module.

TODO Changelog

This module does not have a changelog yet.

Installation

Enable this module in your doom! block.

This module only requires a $DOOMDIR/config.org, which will be tangled into $DOOMDIR/config.el when you run $ doom sync.

 Be careful! Enabling this module will overwrite $DOOMDIR/config.el! If you are only trying out the module, back up this file first!

TODO Usage

󱌣 This module's usage documentation is incomplete. Complete it?

• Automatically tangles $DOOMDIR/config.org to $DOOMDIR/config.el when saving. See Troubleshooting section belong on how to disable it.

TODO Configuration

󱌣 This module's configuration documentation is incomplete. Complete it?

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

Change where src blocks are tangled or prevent it entirely

By default, this module tangles all src emacs-lisp 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 sh :tangle ~/.dotfiles/bin/script.sh :tangle-mode (identity #o755)
#!/usr/bin/env bash
echo Hello world
#+end_src

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

You'll find more information about babel src blocks and what parameters they support in the Org manual.

Troubleshooting

There are no known problems with this module. Report one?

Frequently asked questions

Ask a question?

How do I 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 files in modules are 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.

How do I 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)

TODO Appendix

󱌣 This module has no appendix yet. Write one?