| 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. |