Correct management of opt-in

  - `render_macros` in the YAML header has the last word
  - update `opt-in` test case
  - update documentation

CHANGELOG.md

@@ -11,6 +11,10 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 * Added: parameters `j2_comment_start_string` and
   `j2_comment_end_string` to plugin's parameters, 
   to specify alternate markers for comments.
+* Added the multiline parameter `force_render_paths` in the config file,
+  to specify directories or file patterns to be rendered for the case when `render_by_default = false`
+  (the `render_macros` parameter in the YAML header of the page
+  has the last word).
 
 ## 1.0.5, 2023-10-31
 

mkdocs_macros/plugin.py

@@ -251,7 +251,7 @@ def reverse(x):
     @property
     def page(self):
         """
-        The page information
+        The current page's information
         """
         try:
             return self._page
@@ -262,7 +262,7 @@ def page(self):
     @property
     def markdown(self):
         """
-        The markdown after interpretation
+        The markdown of the current page, after interpretation
         """
         try:
             return self._markdown
@@ -273,7 +273,7 @@ def markdown(self):
     @markdown.setter
     def markdown(self, value):
         """
-        Used to set the raw markdown
+        Used to set the raw markdown of the current page
         """
         if not isinstance(value, str):
             raise ValueError("Value provided to attribute markdown "
@@ -494,26 +494,35 @@ def _load_modules(self):
 
     def render(self, markdown: str, force_rendering:bool=False):
         """
-        Render a page through jinja2: it executes the macros.
-        It keeps account of the `render_macros` variable 
+        Render a page through jinja2: it reads the code and
+        executes the macros.
+        
+        It tests the `render_macros` metavariable 
         in the page's header to decide whether to actually
         render or not (but you can force it).
 
+        PRINCIPLE OF PRECAUTION:
+        If the YAML header of the page contains `render_macros: false`:
+        that takes priority:
+        NO rendering will be done, and the markdown will be returned
+        as is (even if `force_rendering` is set to true). 
+
+
         Arguments
         ---------
         - markdown: the markdown/HTML page (with the jinja2 macros)
-        - force_rendering: force the rendering anyway
+        - force_rendering: if True, it forces the rendering,
+          even if the page header doesn't say so
+          (used in the case when `render_by_default` is set to false
+          in the config file)
 
         Returns
         -------
         A pure markdown/HTML page.
 
         Notes
         -----
-        - Must called by '_on_page_markdown()'
-        - If the YAML header of the page contains `ignore_macros: true`
-          then NO rendering will be done, and the markdown will be returned
-          as is.
+        - Must called by _on_page_markdown()
         """
 
         # Process meta_variables
@@ -527,30 +536,31 @@ def render(self, markdown: str, force_rendering:bool=False):
             # this is a premature rendering, no meta variables in the page
             meta_variables = {}
 
-        if force_rendering:
-            # [if force_render=True, it skips all the reasoning in the else]
-            pass
-        else:
-            # Warning this is ternary logic(True, False, None: nothing said)
-            ignore_macros = None # deprecated
-            render_macros = None
-
-            if meta_variables:
-                # determine whether the page will be rendered or not
-                # the two formulations are accepted
-                ignore_macros = meta_variables.get('ignore_macros')
-                render_macros = meta_variables.get('render_macros')
-
-            if self.config['render_by_default']:
-                # opt-out: force of a page NOT to be interpreted,
-                opt_out = ignore_macros == True or render_macros == False
-                if opt_out:
-                    return markdown
+
+        # Warning this is ternary logic(True, False, None: nothing said)
+        render_macros = None
+
+        if meta_variables:
+            # determine whether the page will be rendered or not
+            # the two formulations are accepted
+            render_macros = meta_variables.get('render_macros')
+            # ignore_macros should be phased out
+            if meta_variables.get('ignore_macros'):
+                raise ValueError("The metavariable `ignore_macros` "
+                      "is now FORBIDDEN "
+                      "in the header of markdown pages, "
+                      "use `render_macros` instead.")
+
+        # this takes precedence over any other consideration:
+        if render_macros == False:
+            return markdown
+
+        if self.config['render_by_default'] == False:
+            # opt-in
+            if force_rendering or render_macros == True:
+                pass # opt-in
             else:
-                # opt-in: you must force a page to be interpreted
-                opt_in = render_macros == True or ignore_macros == False
-                if not opt_in:
-                    return markdown
+                return markdown
 
         # Update the page with meta variables
         # i.e. what's in the yaml header of the page

test/opt-in/docs/rendered/exception.md

@@ -0,0 +1,17 @@
+---
+render_macros: false # opt-in
+---
+# Opt-out by page header (priority)
+
+{# This page should not be rendered #}
+
+In theory, this page should be rendered because its source file
+is in the `rendered/` directory.
+
+However, it can be NEVER be rendered, because the variable `render_macros`
+is set to `false` in the YAML header.
+
+When it is set to `false`, it takes precedence over the directives
+in the `force_render_paths` variable!
+
+{{ macros_info() }}

test/opt-in/mkdocs.yml

@@ -4,10 +4,10 @@ theme: mkdocs
 nav:
     - Home: index.md
     - Other: not_rendered/noname.md
-    - Rendered (by header): noname.md # opt-in by header
-    - Rendered (by dir): rendered/noname.md # opt-in by directory
-    - Rendered (by name): render_this_one.md  # opt-in by file pattern
-
+    - Render (by header): noname.md # opt-in by header
+    - Render (by dir): rendered/noname.md # opt-in by directory
+    - Render (by name): render_this_one.md  # opt-in by file pattern
+    - Exception: rendered/exception.md # forced opt-out in header
 
 plugins:
   - search
@@ -19,6 +19,7 @@ plugins:
       force_render_paths: |
         # this directory will be rendered:
         rendered/
+        # this pattern of files will be rendered:
         render_*.md
 
 

webdoc/docs/advanced.md

@@ -249,7 +249,17 @@ of conflict, the plugin will attempt to privilege the latest branch.
     algorithm might not work as you expect.
 
 
+Controlling the rendering of pages
+--------------------------------------------
+
+A frequent issue, when adding the Mkdocs-Macros plugin to an
+**existing MkDocs project**, is that some pre-existing markdown pages 
+may not be rendered correctly,
+or cause a syntax error, or some other error.
 
+That is because Mkdocs-Macros might confuse snippets in those pages
+with Jinja2 statements, try to render them and fail.
 
+This issue (as well as its solutions) is described under the