Skip to content

Commit a76d62b

Browse files
fralaufralau
committed
Add documentation for jinja2_extensions (#272)
 - included `new_syntax` test case in pytest tests - the `config.yml` file contains the j2_extensions parameter - bump version number
1 parent 9a329bc commit a76d62b

5 files changed

Lines changed: 54 additions & 17 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,9 @@ All notable changes to this project are documented in this file.
44

55
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
66

7+
## 1.4.1, 2025-10-18
8+
* Added: support for j2_extensions paramater in config file (#272)
9+
710
## 1.4.0, 2025-09-21
811
* Removed: auto-install of missing pluglet (meaningful error message #262)
912
* Fixed: error with yaml dumps (#258)

‎pyproject.toml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ name = "mkdocs-macros-plugin"
33

44
# This version number is the REFERENCE for the rest of the project,
55
# particularly for update_pypi.sh
6-
version = "1.4.0"
6+
version = "1.4.1"
77

88
description = "Unleash the power of MkDocs with macros and variables"
99
readme = "README.md"

‎test/new_syntax/mkdocs.yml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
# The purpose of this config is to test change of variable/block syntax
2+
# as well as the insertion of Jinja2 extensions
23
site_name: Altered syntax
34
theme: mkdocs
45

@@ -14,6 +15,9 @@ plugins:
1415
j2_variable_end_string: ']]'
1516
j2_comment_start_string: '[#'
1617
j2_comment_end_string: '#]'
18+
# testing extensions, as well
19+
j2_extensions: [jinja2.ext.i18n, jinja2.ext.loopcontrols]
20+
- test # indispensable for testing
1721

1822
extra:
1923
unit_price: 50 # this is overriden in the page

‎test/new_syntax/test_site.py‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
"""
2+
Testing the project
3+
4+
(C) Laurent Franceschetti 2025
5+
"""
6+
import pytest
7+
8+
from test.fixture import MacrosDocProject
9+
10+
CURRENT_PROJECT = '.'
11+
12+
13+
def test_new_syntax():
14+
project = MacrosDocProject(CURRENT_PROJECT)
15+
project.build()
16+
# did not fail
17+
assert not project.build_result.returncode
18+
19+
20+
page = project.get_page('index')
21+
22+
price = page.meta.unit_price
23+
print("Price found in the meta of the page:", price)
24+
assert page.find_text(f'{price} EUR')
25+
if price > 10:
26+
assert page.find_text('this is expensive')
27+
else:
28+
assert page.find_text('this is cheap')
29+

‎webdoc/docs/index.md‎

Lines changed: 17 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -338,22 +338,23 @@ The other parts give you more detailed information.
338338
Here are all the possible arguments in the `plugin` section
339339
of the MkDocs' config file:
340340

341-
| Argument | Default | Description
342-
| -- | -- | --
343-
|`render_by_default`|`true`|Render macros on all pages by default. If set to false, sets an [opt-in mode](rendering.md/#solution-2-opt-in-specify-which-pages-must-be-rendered) where only pages marked with `render_macros: true` in header will be displayed.
344-
| `module_name` | main| [Name of the Python module](macros.md/#local-module) containing macros, filters and variables. Indicate the file or directory, without extension; you may specify a path (e.g. `include/module`). If no `main` module is available, it is ignored.
345-
| `modules` | `[]`| [List of pluglets](pluglets.md) to be added to mkdocs-macros (preinstalled Python modules that can be listed by `pip list`).
346-
| `include_dir` | | [Directory for including external files](advanced.md/#changing-the-directory-of-the-includes)
347-
| `include_yaml`| `[]` | [List of yaml files or `key: filename` pairs to be included](advanced.md/#including-external-yaml-files)
348-
| `j2_block_start_string` | | [Non-standard Jinja2 marker for start of block](rendering.md/#solution-5-altering-the-syntax-of-jinja2-for-mkdocs-macros)
349-
| `j2_block_end_string` || [Non-standard Jinja2 marker for end of block](rendering.md/#solution-5-altering-the-syntax-of-jinja2-for-mkdocs-macros)
350-
| `j2_variable_start_string` || [Non-standard Jinja2 marker for start of variable](rendering.md/#solution-5-altering-the-syntax-of-jinja2-for-mkdocs-macros)
351-
| `j2_variable_end_string` || [Non-standard Jinja2 marker for end of variable](rendering.md/#solution-5-altering-the-syntax-of-jinja2-for-mkdocs-macros)
352-
| `j2_comment_start_string` || [Non-standard Jinja2 marker for start of comment](rendering.md/#solution-5-altering-the-syntax-of-jinja2-for-mkdocs-macros)
353-
| `j2_comment_end_string` || [Non-standard Jinja2 marker for end of comment](rendering.md/#solution-5-altering-the-syntax-of-jinja2-for-mkdocs-macros)
354-
|`on_error_fail`|`false`| [Make the building process fail in case of an error in macro rendering](troubleshooting.md/#make-the-build-process-fail-in-case-of-error) (this is useful when the website is rebuilt automatically and errors must be detected.)
355-
|`on_undefined`|keep|[Behavior of the macros renderer in case of an undefined variable in a page](troubleshooting.md/#is-it-possible-to-make-the-building-process-fail-in-case-of-page-error). By default, it leaves the Jinja2 statement untouched (e.g. `{{ foo }}` will appear as such in the page.) Use the value 'strict' to make it fail.
356-
|`verbose`|`false`| Print [debug (more detailed) statements](troubleshooting.md/#verbose-debug-statements-in-macros) in the console.
341+
| Argument | Default | Description |
342+
| -------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
343+
| `render_by_default` | `true` | Render macros on all pages by default. If set to false, sets an [opt-in mode](rendering.md/#solution-2-opt-in-specify-which-pages-must-be-rendered) where only pages marked with `render_macros: true` in header will be displayed. |
344+
| `module_name` | main | [Name of the Python module](macros.md/#local-module) containing macros, filters and variables. Indicate the file or directory, without extension; you may specify a path (e.g. `include/module`). If no `main` module is available, it is ignored. |
345+
| `modules` | `[]` | [List of pluglets](pluglets.md) to be added to mkdocs-macros (preinstalled Python modules that can be listed by `pip list`). |
346+
| `include_dir` | | [Directory for including external files](advanced.md/#changing-the-directory-of-the-includes) |
347+
| `include_yaml` | `[]` | [List of yaml files or `key: filename` pairs to be included](advanced.md/#including-external-yaml-files) |
348+
| `j2_block_start_string` | | [Non-standard Jinja2 marker for start of block](rendering.md/#solution-5-altering-the-syntax-of-jinja2-for-mkdocs-macros) |
349+
| `j2_block_end_string` | | [Non-standard Jinja2 marker for end of block](rendering.md/#solution-5-altering-the-syntax-of-jinja2-for-mkdocs-macros) |
350+
| `j2_variable_start_string` | | [Non-standard Jinja2 marker for start of variable](rendering.md/#solution-5-altering-the-syntax-of-jinja2-for-mkdocs-macros) |
351+
| `j2_variable_end_string` | | [Non-standard Jinja2 marker for end of variable](rendering.md/#solution-5-altering-the-syntax-of-jinja2-for-mkdocs-macros) |
352+
| `j2_comment_start_string` | | [Non-standard Jinja2 marker for start of comment](rendering.md/#solution-5-altering-the-syntax-of-jinja2-for-mkdocs-macros) |
353+
| `j2_comment_end_string` | | [Non-standard Jinja2 marker for end of comment](rendering.md/#solution-5-altering-the-syntax-of-jinja2-for-mkdocs-macros) |
354+
| `j2_extensions` | `[]` | _From version 1.4.1:_ List of Jinja2 extensions (for more information see the [Jinja2 page on extensions](https://jinja.palletsprojects.com/en/stable/extensions)). |
355+
| `on_error_fail` | `false` | [Make the building process fail in case of an error in macro rendering](troubleshooting.md/#make-the-build-process-fail-in-case-of-error) (this is useful when the website is rebuilt automatically and errors must be detected.) |
356+
| `on_undefined` | keep | [Behavior of the macros renderer in case of an undefined variable in a page](troubleshooting.md/#is-it-possible-to-make-the-building-process-fail-in-case-of-page-error). By default, it leaves the Jinja2 statement untouched (e.g. `{{ foo }}` will appear as such in the page.) Use the value 'strict' to make it fail. |
357+
| `verbose` | `false` | Print [debug (more detailed) statements](troubleshooting.md/#verbose-debug-statements-in-macros) in the console. |
357358

358359
___
359360
For example:

0 commit comments

Comments
 (0)