Allow pages to opt-in, instead of opt-out.

mkdocs_macros/plugin.py

@@ -84,6 +84,8 @@ class MacrosPlugin(BasePlugin):
                                     default=DEFAULT_MODULE_NAME)),
         ('modules', PluginType(list,
                                default=[])),
+        # allow default 'ignore' configuration
+        ('ignore_macros', PluginType(bool, default=False)),
         # include directory for templates ({% include ....%}):
         ('include_dir',  J2_STRING),
         # list of additional yaml files:
@@ -466,10 +468,15 @@ def render(self, markdown: str):
         page_variables = copy(self.variables)
         meta_variables = self.variables['page'].meta
         # it must be possible to completely
-        if meta_variables:
+        if meta_variables and 'ignore_macros' in meta_variables:
+            ignore_macros = meta_variables.get('ignore_macros')
+        else:
+            ignore_macros = self.config['ignore_macros']
+        if ignore_macros:
             # a trick to force of a page NOT to be interpreted,
-            if meta_variables.get('ignore_macros') == True:
-                return markdown
+            return markdown
+
+        if meta_variables:
             # trace("Metavariables for '%s':" % self.variables['page'].title,
             #                 meta_variables)
             page_variables.update(meta_variables)

test/opt-in/docs/index.md

@@ -0,0 +1,6 @@
+---
+ignore_macros: false
+---
+
+{{ macros_info() }}
+

test/opt-in/docs/literal.md

@@ -0,0 +1,18 @@
+# In this document, macros are ignored (`ignore_macros: true`)
+
+## Some pre-existing directive (not Jinja2)
+
+`{% Vimeo ID}`
+
+
+## Offending LaTeX
+
+```LaTeX
+\begin{tabular}{|ccc|}
+    \hline
+    2   & 9     & 4\\
+    7   & \multicolumn{2}{c|} {\multirow{2}*{{?}}} \\
+    6   &       &\\
+    \hline
+\end{tabular}
+```

test/opt-in/mkdocs.yml

@@ -0,0 +1,14 @@
+site_name: Main test site
+theme: material
+copyright: (C) Laurent Franceschetti 2020
+
+nav:
+    - Home: index.md
+    - Not interpreted: literal.md
+
+plugins:
+  - macros:
+      ignore_macros: true
+      # toggle to true if you are in CD/CI environment
+      on_error_fail: true
+      verbose: true # toggle to true if you want to macro debug

webdoc/docs/advanced.md

@@ -301,6 +301,28 @@ You may, of course, chose the combination that best suits your needs.
     of trouble, please do not expect help from the maintainers of this
     plugin.
 
+#### Solution 5: Make the rendering process opt-in, instead of opt-out
+
+_From version x.x.x_
+
+Sometimes, only a select few pages need to make use of the Jinja2 statements, or
+the introduction of mkdocs-macros is late. To facilitate this, it's possible to
+make the rengering process opt-in, instead of opt-out.
+
+For example, place the following parameter in the `macros` section of the config:
+
+      - macros:
+          ignore_macros: true
+
+And then, for the pages which require rendering, add the following to the page's
+header section:
+
+```yaml
+---
+ignore_macros: false
+---
+```
+
 
 
 Including snippets in pages

webdoc/docs/index.md

@@ -240,6 +240,7 @@ of the MkDocs' config file:
 | -- | -- | --
 | `module_name` | `main` | [Name of the Python module](python/#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.
 | `modules` | `[]`| [List of preinstalled Python modules](python/#adding-pre-installed-modules), i.e. listed by `pip list`.
+| `ignore_macros` | `False` | [Allow pages to opt-in, instead of opt-out](advanced/#solution-5-make-the-rendering-process-opt-in-instead-of-opt-out)
 | `include_dir` | | [Directory for including external files](advanced/#changing-the-directory-of-the-includes) 
 | `include_yaml`| `[]` | [List of yaml files or `key: filename` pairs to be included](advanced/#including-external-yaml-files)
 | `j2_block_start_string` | | [Non-standard Jinja2 marker for start of block](advanced/#solution-3-altering-the-syntax-of-jinja2-for-mkdocs-macros)