diff --git a/mkdocs_macros/plugin.py b/mkdocs_macros/plugin.py index 52cc70b..2770b70 100644 --- a/mkdocs_macros/plugin.py +++ b/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) diff --git a/test/opt-in/docs/index.md b/test/opt-in/docs/index.md new file mode 100644 index 0000000..e2610ba --- /dev/null +++ b/test/opt-in/docs/index.md @@ -0,0 +1,6 @@ +--- +ignore_macros: false +--- + +{{ macros_info() }} + diff --git a/test/opt-in/docs/literal.md b/test/opt-in/docs/literal.md new file mode 100644 index 0000000..336e606 --- /dev/null +++ b/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} +``` diff --git a/test/opt-in/mkdocs.yml b/test/opt-in/mkdocs.yml new file mode 100644 index 0000000..7c5a50a --- /dev/null +++ b/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 diff --git a/webdoc/docs/advanced.md b/webdoc/docs/advanced.md index 727cd3a..af85a1b 100644 --- a/webdoc/docs/advanced.md +++ b/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 diff --git a/webdoc/docs/index.md b/webdoc/docs/index.md index c6b3163..1b8f4f1 100644 --- a/webdoc/docs/index.md +++ b/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)