Add basic support for Jinja2 options (#29)

* Add support for Jinja2 config

* Make it so that the "start" replacement does not necessarily need to be the last thing in the content

* Var instead of magic value

Author: miffels

README.md

@@ -102,7 +102,19 @@ If inside your data folder you have a directory and a file file
 called `[path/to/datafiles/]sections/captions.yaml` - where `[path/to/datafiles/]` is the path in your configuration -
 the data inside that file will be available in your templates as `sections.captions.whatever_variable_in_the_yaml`.
 
+### Jinja2 Template Engine Configuration
 
+You may provide [Jinja2 configuration](https://jinja.palletsprojects.com/en/2.11.x/api/#high-level-api) as plugin options:
+
+```yml
+plugins:
+    - markdownextradata:
+        jinja_options:
+          comment_start_string: __CUSTOMCOMMENTSTART__
+```
+
+The above example will make it so that instead of `{#`, the template engine will interpret `__CUSTOMCOMMENTSTART__` as comment start delimiter. This is useful in cases where
+you write Markdown that contains Jinja-like syntax that's colliding with the template engine. Alternatively, it lets you control what the variable delimiter is (instead of the default `{{ }}`).
 
 ## Testing
 

markdownextradata/plugin.py

@@ -27,8 +27,11 @@ class MarkdownExtraDataPlugin(BasePlugin):
     Inject certain config variables into the markdown
     """
 
+    JINJA_OPTIONS = "jinja_options"
+
     config_scheme = (
         ("data", mkdocs.config.config_options.Type(str_type, default=None)),
+        (JINJA_OPTIONS, mkdocs.config.config_options.Type(dict, default={}))
     )
 
     def __add_data__(self, config, namespace, data):
@@ -91,6 +94,7 @@ def on_pre_build(self, config, **kwargs):
     def on_page_markdown(self, markdown, config, **kwargs):
         context = {key: config.get(key) for key in CONFIG_KEYS if key in config}
         context.update(config.get("extra", {}))
-        env = jinja2.Environment(undefined=jinja2.DebugUndefined)
+        jinja_options = self.config[self.JINJA_OPTIONS]
+        env = jinja2.Environment(undefined=jinja2.DebugUndefined, **jinja_options)
         md_template = env.from_string(markdown)
         return md_template.render(**config.get("extra"))

test/docs/index.md

@@ -2,4 +2,7 @@
 
 Welcome to {{ customer.web_url }}
 
-Inside the included md file there 3 {{ star }}
+Inside the included md file there 3 {{ star }}
+
+<!-- throws TemplateSyntaxError('Missing end of comment tag') unless comment_start_string is configured -->
+You can use `{#binding.path}` to update the UI when the model changes.

test/mkdocs.yml

@@ -5,7 +5,9 @@ use_directory_urls: true
 #     custom_dir: 'theme/'
 plugins:
     - search
-    - markdownextradata
+    - markdownextradata:
+        jinja_options:
+          comment_start_string: __COMMENTSTART__
 
 extra:
   star: "![star](ressources/star.png)"

test/test_basic.py

@@ -23,7 +23,8 @@ def test_basic_working():
         contents = index_file.read_text()
 
         assert '<h1 id="hi-there-your-name-here">Hi there, Your name here</h1>' in contents, f"customer.name is not in index"
-        assert '<p>Inside the included md file there 3 <img alt="star" src="ressources/star.png" /></p></div>' in contents, f"customer.star is not in index or not rendering as expected"
+        assert '<p>Inside the included md file there 3 <img alt="star" src="ressources/star.png" /></p>' in contents, f"customer.star is not in index or not rendering as expected"
         assert f"Welcome to {customer.get('web_url')}" in contents, f"customer.web_url is not in index"
+        assert f"{{#binding.path}}" in contents, f"Jinja2 comment syntax wasn't reconfigured via jinja_options as expected"
         assert isinstance(test_json_string, str), "test_json_string is not a str it should be"
         assert '{"name": "Bob"}' == test_json_string, f"Json string is not correct"