Debian Codegraph @

docs/template/templating.md

raw
1 # Templating
2
3 Dotdrop leverages the power of [Jinja2](https://palletsprojects.com/p/jinja/) to handle the
4 templating of dotfiles. See [the Jinja2 templates docs](https://jinja.palletsprojects.com/en/2.11.x/templates/)
5 or the below sections for more information on how to template your dotfiles.
6
7 ## Templating or not templating
8
9 The dotfile config entry [template](../config/config-dotfiles.md#dotfiles-block)
10 and the global config entry [template_dotfile_default](../config/config-config.md)
11 allow to control whether a dotfile is processed by the templating engine.
12
13 Obviously, if the dotfile uses template directives, it needs to be templated. However, if it
14 is not, disabling templating will speed up its installation (since it won't have to be
15 processed by the engine).
16
17 For dotfiles being symlinked (`absolute`, `relative` or `link_children`), see
18 [the dedicated doc](../howto/symlink-dotfiles.md#templating-symlinked-dotfiles).
19
20 ## Delimiters
21
22 Dotdrop uses different delimiters than
23 [Jinja2](https://palletsprojects.com/p/jinja/)'s defaults:
24
25 * Block/statement start = `{%@@`
26 * Block/statement end = `@@%}`
27 * Variable/expression start = `{{@@`
28 * Variable/expression end = `@@}}`
29 * Comment start = `{#@@`
30 * Comment end = `@@#}`
31
32 More info in [Jinja2 templating docs](https://jinja.palletsprojects.com/en/2.11.x/templates/?highlight=delimiter)
33
34 ## Importing macros
35
36 Macros must be imported `with context` in order to have access to the variables:
37 ```
38 {%@@ from 'macro_file' import macro with context @@%}
39 ```
40
41 For more information, see the [dedicated Jinja2 docs](https://jinja.palletsprojects.com/en/2.11.x/templates/#macros).
42
43 ## Dotdrop header
44
45 Dotdrop is able to insert a header in the generated dotfiles. This allows
46 to remind anyone opening the file for editing that this file is managed by dotdrop.
47
48 Here's what it looks like:
49 ```none
50 This dotfile is managed using dotdrop
51 ```
52
53 The header can be automatically added with:
54 ```none
55 {{@@ header() @@}}
56 ```
57
58 Properly commenting the header in templates is the responsibility of the user,
59 as [Jinja2](https://palletsprojects.com/p/jinja/) has no way of knowing what is the proper char(s) used for comments.
60 Either prepend the directive with the commenting char(s) used in the dotfile
61 (for example `# {{@@ header() @@}}`) or provide it as an argument `{{@@ header('# ') @@}}`.
62 The results are equivalent.