Allow opt-in of pages, #162

  - Document opt-in and various fixes of documentation
  - Demote `macro_info()` (start with header of level 2), #123

CHANGELOG.md

@@ -4,6 +4,25 @@ All notable changes to this project will be documented in this file.
 
 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).
 
+## 1.1.0-alpha, 2023.04-25
+
+* Added: (#162) Allow opt-in of page rendering, by using parameter
+    `render_macros: true` in yaml header of the page
+    (requires `render_by_default:false` in the macro parameters,
+    in the config file).
+
+* Fixed: `macro_info()` now generates a header of category 2,
+    so as to be used with other material in the same page,
+    and not confuse the macro generators.
+
+* Changed: `ignore_macros: true` in page header is deprecated. 
+    Use `render_macros: false` instead.
+
+* Fixed: issues #155 (documentation type), #143 (`git.tab`), 
+    #135 (indicate page where rendering failed).
+
+* Bump version to 1.1.0 to acknowledge that API is stable
+
 ## 0.7.0, 2022-03-25
 
 * Added: (#133) `on_error_fail` in config file to make build/serve process

mkdocs_macros/macros_info.md

@@ -4,13 +4,13 @@ Template for the macro_info() command
 #}
 
 
-# Macros Plugin Environment
+## Macros Plugin Environment
 
-## General List
+### General List
 All available variables and filters within the macros plugin:
 {{ context() | pretty }}
 
-## Config Information
+### Config Information
 Standard MkDocs configuration information. Do not try to modify.
 
 e.g. {{ "`{{ config.docs_dir }}`" }}
@@ -19,20 +19,20 @@ See also the [MkDocs documentation on the config object](https://www.MkDocs.org/
 
 {{ context(config)| pretty }}
 
-## Macros
+### Macros
 These macros have been defined programmatically for this environment
 (module or pluglets). 
 {{ context(macros)| pretty }}
 
-## Git Information
+### Git Information
 Information available on the last commit and the git repository containing the
 documentation project:
 
 e.g. {{ "`{{ git.message }}`" }}
 
 {{ context(git)| pretty }}
 
-## Page Attributes
+### Page Attributes
 Provided by MkDocs. These attributes change for every page
 (the attributes shown are for this page).
 
@@ -53,11 +53,11 @@ To have all titles of all pages, use:
 {% endraw %}
 ```
 
-## Plugin Filters
+### Plugin Filters
 These filters are provided as a standard by the macros plugin.
 {{ context(filters)| pretty }}
 
-## Builtin Jinja2 Filters
+### Builtin Jinja2 Filters
 These filters are provided by Jinja2 as a standard.
 
 See also the [Jinja2 documentation on builtin filters](https://jinja.palletsprojects.com/en/2.11.x/templates/#builtin-filters)).

mkdocs_macros/plugin.py

@@ -84,6 +84,8 @@ class MacrosPlugin(BasePlugin):
                                     default=DEFAULT_MODULE_NAME)),
         ('modules', PluginType(list,
                                default=[])),
+        # How to render pages by default: yes (opt-out), no (opt-in)
+        ('render_by_default', PluginType(bool, default=True)),
         # include directory for templates ({% include ....%}):
         ('include_dir',  J2_STRING),
         # list of additional yaml files:
@@ -461,19 +463,39 @@ def render(self, markdown: str):
           then NO rendering will be done, and the markdown will be returned
           as is.
         """
+
+        # Process meta_variables
+        # ----------------------
         # copy the page variables and update with the meta data
         # in the YAML header:
         page_variables = copy(self.variables)
         meta_variables = self.variables['page'].meta
-        # it must be possible to completely
+        # Warning this is ternary logique (True, False, None: nothing said)
+        ignore_macros = None
+        render_macros = None
+
         if meta_variables:
-            # a trick to force of a page NOT to be interpreted,
-            if meta_variables.get('ignore_macros') == True:
+            # 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
+        else:
+            # opt-in: force a page to be interpreted
+            opt_in = render_macros == True or ignore_macros == False
+            if not opt_in:
                 return markdown
-            # trace("Metavariables for '%s':" % self.variables['page'].title,
-            #                 meta_variables)
-            page_variables.update(meta_variables)
+        # Update the page with meta variables
+        # i.e. what's in the yaml header of the page
+        page_variables.update(meta_variables)
 
+        # Rendering
+        # ----------------------
         # expand the template
         on_error_fail = self.config['on_error_fail']
         try:

setup.py

@@ -12,7 +12,7 @@
 # Initialization
 # --------------------
 
-VERSION_NUMBER = '0.7.0'
+VERSION_NUMBER = '1.0.0-alpha'
 
 # required if you want to run document/test
 # pip install 'mkdocs-macros-plugin[test]'

test/opt-in/docs/index.md

@@ -0,0 +1,5 @@
+# Hello World
+
+## Should not be rendered
+{{ macros_info() }}
+

test/opt-in/docs/page_with_macros.md

@@ -0,0 +1,7 @@
+---
+render_macros: true # opt-in
+title: Rendered title
+---
+# {{ title }}
+
+{{ macros_info() }}

test/opt-in/mkdocs.yml

@@ -0,0 +1,15 @@
+site_name: Opt-in of pages rendering
+theme: mkdocs
+
+nav:
+    - Home: index.md
+    - Second: page_with_macros.md # opt-in
+
+
+plugins:
+  - search
+  - macros:
+      # do not render the pages by default
+      # requires an opt-in
+      render_by_default: false
+

test/opt-out/docs/index.md

@@ -0,0 +1,12 @@
+---
+render_macros: false # opt-out
+title: Rendered title (opt-out)
+---
+
+# Hello World
+
+## {{ title }}
+(This title should not be rendered)
+
+{{ macros_info() }}
+

test/opt-out/docs/page_with_macros.md

@@ -0,0 +1,7 @@
+---
+render_macros: true # opt-in
+title: Rendered title
+---
+# {{ title }}
+
+{{ macros_info() }}

test/opt-out/mkdocs.yml

@@ -0,0 +1,15 @@
+site_name: Opt-out for rendering pages
+theme: mkdocs
+
+nav:
+    - Home: index.md
+    - Second: page_with_macros.md
+
+
+plugins:
+  - search
+  - macros:
+      # do not render the pages by default
+      # this is the default case
+      render_by_default: true
+