diff --git a/CHANGELOG.md b/CHANGELOG.md
index 0d7bb70..c3e3ec5 100644
--- a/CHANGELOG.md
+++ b/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
diff --git a/mkdocs_macros/macros_info.md b/mkdocs_macros/macros_info.md
index 47a4a8a..348be1c 100644
--- a/mkdocs_macros/macros_info.md
+++ b/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,12 +19,12 @@ 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:
 
@@ -32,7 +32,7 @@ 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)).
diff --git a/mkdocs_macros/plugin.py b/mkdocs_macros/plugin.py
index 52cc70b..ce35fe1 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=[])),
+        # 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:
diff --git a/setup.py b/setup.py
index 57894de..ba1869a 100644
--- a/setup.py
+++ b/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]'
diff --git a/test/opt-in/docs/index.md b/test/opt-in/docs/index.md
new file mode 100644
index 0000000..0729df5
--- /dev/null
+++ b/test/opt-in/docs/index.md
@@ -0,0 +1,5 @@
+# Hello World
+
+## Should not be rendered
+{{ macros_info() }}
+
diff --git a/test/opt-in/docs/page_with_macros.md b/test/opt-in/docs/page_with_macros.md
new file mode 100644
index 0000000..7fd3df3
--- /dev/null
+++ b/test/opt-in/docs/page_with_macros.md
@@ -0,0 +1,7 @@
+---
+render_macros: true # opt-in
+title: Rendered title
+---
+# {{ title }}
+
+{{ macros_info() }}
\ No newline at end of file
diff --git a/test/opt-in/mkdocs.yml b/test/opt-in/mkdocs.yml
new file mode 100644
index 0000000..97d2294
--- /dev/null
+++ b/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
+
diff --git a/test/opt-out/docs/index.md b/test/opt-out/docs/index.md
new file mode 100644
index 0000000..e24605a
--- /dev/null
+++ b/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() }}
+
diff --git a/test/opt-out/docs/page_with_macros.md b/test/opt-out/docs/page_with_macros.md
new file mode 100644
index 0000000..7fd3df3
--- /dev/null
+++ b/test/opt-out/docs/page_with_macros.md
@@ -0,0 +1,7 @@
+---
+render_macros: true # opt-in
+title: Rendered title
+---
+# {{ title }}
+
+{{ macros_info() }}
\ No newline at end of file
diff --git a/test/opt-out/mkdocs.yml b/test/opt-out/mkdocs.yml
new file mode 100644
index 0000000..a61e139
--- /dev/null
+++ b/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
+
diff --git a/webdoc/docs/advanced.md b/webdoc/docs/advanced.md
index 727cd3a..fed5a9d 100644
--- a/webdoc/docs/advanced.md
+++ b/webdoc/docs/advanced.md
@@ -8,11 +8,6 @@ The purpose of this page is to provide information
 for **large projects**, or **projects with 
 specific technical requirements**.
 
-!!! Tip "Migrations to mkdocs-macros"
-    It may be useful for mkdocs projects
-    which that have decided to adopt mkdocs-macros at some
-    stage in their existence.
-
 
 Can I make mkdocs-macros build process to fail in case of error (instead of displaying the error on the page)?
 -----------------------------------------------------------
@@ -61,247 +56,6 @@ Meaning that the parameter "`on_error_fail` should be set to the value of
 
 
 
-How to prevent accidental interpretation of "Jinja-like" statements?
-------------------------
-
-### Issue
-
-The most frequent issue, when adding the mkdocs-macros plugin to an
-existing mkdocs project, is some markdown pages 
-may not be rendered correctly,
-or cause a syntax error, or some other error.
-
-The reason is that if Jinja2 template engine in the **macro plugin** 
-meets any text that has the standard markers (typically starting with `{%`} or
-`{{`) this will cause a conflict:
-it will try to interpret that text as a macro
-and fail to behave properly. 
-
-
-
-
-The most likely places where this can occur are the following:
-
-| Location in Markdown file (Block or Inline) | Description                                                                                                |
-| ------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
-| **Code**                                    | Documented Jinja2 statements (or similar syntax), LaTeX                                                    |
-| **Maths**                                   | LaTeX statements                                                                                           |
-| *_Elsewhere_*                               | Some pre-existing templating or macro language, typically with some constructs starting with `{#` or `{{`. |
-
-<br>
-
-
-!!! Warning "Expected behaviors in case of failure"
-
-    1. If the statement does not fit Jinja2 syntax, a syntax error
-       will be displayed in the rendered page.
-
-    2. If mkdocs-macros mistakenly tries to interprets a syntactically
-    valid Jinja2 statement
-    containing a variable,
-    the most likely result is that **it will "eat" that statement**:
-    since it cannot make any sense of it, 
-    **it will silently replace it with an empty string**.
-
-    1. If the statement looks like a macro (callable, with arguments),
-       an error and traceback will be displayed in the page.
-
-!!! Note
-    This question of accidental rendering is covered generally in the Jinja2 documentation as
-    [escaping](https://jinja.palletsprojects.com/en/2.11.x/templates/?highlight=raw#escaping). 
-    
-    Here we need to help **mkdocs-macros** clearly distinguish
-    between  **two types of Jinja2 statements**:
-    
-    1. **Documentation statements**, 
-       which must appear as-is in the final HTML pages,
-       and therefore **must not** be interpreted by mkdocs-macros.
-    2. **Actionable Jinja2 statements**: calls to variables or macros, etc.,
-       which mkdocs-macros **must** replace by their equivalent.
-
-
-### Special Cases
-
-#### Code Blocks Containing Similar Languages
-
-With MkDocs, this situation typically occurs when the website 
-is documenting an application that relies on a 
-"[djangolike/jinjalike language](https://medium.com/@i5ar/template-languages-a7b362971cbc)" like:
-
-- Django Template Language
-- Jinja2 (Python)
-- Nunjucks (Javascript)
-- Twig (PHP)
-- ...
-
-This may also happen for pages that documents
-[Ansible](https://ansible-docs.readthedocs.io/zh/stable-2.0/rst/intro.html) directives, which often contain
-[variables expressed in a Jinja2 syntax](https://ansible-docs.readthedocs.io/zh/stable-2.0/rst/playbooks_variables.html#using-variables-about-jinja2).
-
-
-#### Snippets Containing LaTeX
-
-With the plug-in enabled, LaTeX snippets 
-would fail to build because {{?}} will trigger the interpretation
-of a Jinja2 macro (since `{{` and `}}` are markers).LaTeX snippets
-
-For example, the following LaTeX snippet is used to draw a table:
-
-    ```LaTeX
-    \begin{tabular}{|ccc|}
-        \hline
-        2   & 9     & 4\\
-        7   & \multicolumn{2}{c|} {\multirow{2}*{{?}}} \\
-        6   &       &\\
-        \hline
-    \end{tabular}
-    ```
-
-
-### Two Essential Notes
-
-!!! Warning
-    Fencing Jinja2 statements parts as blocks of code
-    with the markdown convention
-    (using three backticks or three tildes) **will not prevent**
-    their interpretation, because this macros plugin intentionally ignores them.
-
-    This is to allow advanced use cases where the content of the code block
-    must be computed on the fly.
-
-!!! Note "No Risk of intereference of Jinja2 statements with HTML Rendering"
-
-    There is, of course, a **third use of Jinja2 statements**:
-    MkDocs also use them in templates to render HTML pages. **Fortunately,
-    we can safely ignore that fact.**
-
-    **There is in principle no risk that MkDocs will accidentally
-    interpret any Jinja2 statements in markdown pages, during the HTML
-    rendering process**.
-
-    The reason is that **MkDocs contains a safety**: **it automatically
-    escapes symbols such as '\{'**, which could have a meaning for the later
-    rendering in HTML (which also uses Jinja2 templates). 
- 
-    Here we are trying to solve a different problem:
-    **how to avoid interpretation** of Jinja2 statements
-    **by mkdocs-macros**,
-    so that **they actually appear in the HTML output**?
-
-### Solutions
-
-#### Solution 1: Exclude a page from the rendering process
-
-_From version 0.5.7_
-
-!!! Tip
-    This solution is a quick fix, if you are "migrating"
-    a pre-existing mkdocs project under mkdocs-macros, and
-    some markdown pages fail, or do not display correctly.
-
-    This will leave more time to implement the next solutions.
-
-
-In the header of the markdown page, indicate that the markdown should
-be used "as-is" (no rendering of mkdocs-macros),
-by setting the `ignore_macros` meta-data key to the `true`value.
-
-```yaml
----
-# YAML header
-ignore_macros: true
----
-```
-
-Any other value than `true` (or an absence of this key), will be interpreted
-as a `false` value.
-
-
-#### Solution 2: Snippets as jinja2 strings (one-liners)
-
-This hack works for simple one-line snippets.
-Suppose you want to prevent the
-string `{{ 2 + 2 }}` from being interpreted. It would be sufficient to treat
-it as if it was a string in jinja2.
-
-    {{ "{{ 2 + 2 }}" }}
-
-You could also use expressions that contain the double quote symbol,
-but in this case you must bracket them with simple quotes:
-
-    {{ '{{ "Hello world" }}' }}
-
-!!!Warning
-    Triple quotes (`"""`) around strings are not allowed in Jinja2, so this
-    hack cannot be used for multiline statements.
-
-#### Solution 3: Explicitly marking the snippets as 'raw'
-
-The standard solution is to isolate each snippet of code that should not
-be interpreted, using the standard jinja2 `raw` directive,
-which exists for that purpose:
-
-    {% raw %}
-    - task: "create a directory
-      file:
-        path: "{{ folder_path }}"
-        state: directory
-        recurse: true
-    {% endraw %}
-
-#### Solution 4: Altering the syntax of jinja2 for mkdocs-macros
-
-Sometimes the introduction of mkdocs-macros comes late in the chain, and the
-existing pages already contain a lot of Jinja2 statements that are
-should appear in the final HTML pages: escaping all of them
-would not really be an option.
-
-Or else, you do not wish to bother the writers of markdown pages
-with the obligation of escaping Jinja2 statements.
-
-!!! Tip "Solution"
-    Rather than refactoring all the existing markdown pages to fence
-    those Jinja2 statements,
-    it may be preferable to alter the markers for variables or blocks
-    used in mkdocs-macros.
-
-For example, you may want to replace the curly brackets by square ones,
-like this:
-
-    # This is a title
-
-    It costs [[ unit_price ]].
-
-    [[% if unit_price > 5 %]]
-    This is expensive!
-    [[% endif %]]
-
-To obtain this result, simply add the following parameters in the
-`macros` section. There are two parameters for code blocks (start and
-end) and two for variables (start and end).
-
-      - macros:
-          j2_block_start_string: '[[%'
-          j2_block_end_string: '%]]'
-          j2_variable_start_string: '[['
-          j2_variable_end_string: ']]'
-
-You may, of course, chose the combination that best suits your needs.
-
-!!! Warning "Caution 1: You are walking out of the beaten path."
-    Altering the standard markers used in jinja2 has far-reaching consequences,
-    because it will oblige you henceforth use a new form for templates,
-    which is specific to your project. When reading this
-    documentation, you will have to mentally convert all the examples.
-
-!!! Warning "Caution 2: Use with discretion"
-    Errors in defining these new markers, or some
-    accidental combinations of markers may have unpredictable
-    consequences. **Use with discretion, and at your own risk**. In case
-    of trouble, please do not expect help from the maintainers of this
-    plugin.
-
-
 
 Including snippets in pages
 ---------------------------------
diff --git a/webdoc/docs/pages.md b/webdoc/docs/pages.md
index 2a21e60..59f1b82 100644
--- a/webdoc/docs/pages.md
+++ b/webdoc/docs/pages.md
@@ -190,7 +190,7 @@ Which can be called (within the page) as:
 Conditionals, loops, etc.
 -------------------------
 
-With the macros plugin, you may use the [conditional](https://jinja.palletsprojects.com/en/2.11.x/templates/#if)
+With the macros plugin, you may use the [conditional](https://jinja.palletsprojects.com/en/3.0.x/templates/#if)
 statement of Jinja2, e.g.
 
 ``` {.jinja2}
@@ -205,7 +205,7 @@ _Second version_
 You may produce Markdown or any mix of Markdown, HTML, css
 and even javascript that you wish.
 
-Similarly, you could use [for loops](https://jinja.palletsprojects.com/en/2.11.x/templates/#for):
+Similarly, you could use [for loops](https://jinja.palletsprojects.com/en/3.0.x/templates/#for):
 
 ``` {.jinja2}
 ### List of users
diff --git a/webdoc/docs/rendering.md b/webdoc/docs/rendering.md
new file mode 100644
index 0000000..c84c333
--- /dev/null
+++ b/webdoc/docs/rendering.md
@@ -0,0 +1,289 @@
+Controlling the rendering of pages
+==================================
+
+!!! Tip "Migrations to mkdocs-macros"
+    This page may be useful for **large mkdocs projects**
+    that have decided to adopt mkdocs-macros at a later
+    stage of their existence.
+
+
+## Issue
+
+### Introduction
+
+The most frequent issue, when adding the mkdocs-macros plugin to an
+existing mkdocs project, is some markdown pages 
+may not be rendered correctly,
+or cause a syntax error, or some other error.
+
+The reason is that, by default, when the Jinja2 template engine in the **macro plugin** 
+encouters any text that has the standard markers (typically starting with `{%`} or
+`{{`) this will cause a conflict:
+it will try to interpret that text as a macro
+and fail to behave properly. 
+
+The most likely places where this can occur are the following:
+
+| Location in Markdown file (Block or Inline) | Description                                                                                                |
+| ------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| **Code**                                    | Documented Jinja2 statements (or similar syntax), LaTeX                                                    |
+| **Maths**                                   | LaTeX statements                                                                                           |
+| *_Elsewhere_*                               | Some pre-existing templating or macro language, typically with some constructs starting with `{#` or `{{`. |
+
+<br>
+
+
+!!! Warning "Expected behaviors in case of failure"
+
+    1. If the statement does not fit Jinja2 syntax, a syntax error
+       will be displayed in the rendered page.
+
+    2. If mkdocs-macros mistakenly tries to interprets a syntactically
+    valid Jinja2 statement containing a variable,
+    the most likely result is the page will fail (you can change
+    this behavior with the [`on_undefined` parameter in the config file](../troubleshooting#what-happens-if-a-variable-is-undefined)).
+
+    3. If the statement looks like a macro (callable, with arguments),
+       an error and traceback will be displayed in the page.
+
+!!! Note
+    This question of accidental rendering is covered generally in the Jinja2 documentation as
+    [escaping](https://jinja.palletsprojects.com/en/2.11.x/templates/?highlight=raw#escaping). 
+    
+    Here we need to help **mkdocs-macros** clearly distinguish
+    between  **two types of Jinja2 statements**:
+    
+    1. **Documentation statements**, 
+       which must appear as-is in the final HTML pages,
+       and therefore **must not** be interpreted by mkdocs-macros.
+    2. **Actionable Jinja2 statements**: calls to variables or macros, etc.,
+       which mkdocs-macros **must** replace by their equivalent.
+
+
+### Special Cases
+
+#### Code Blocks Containing Similar Languages
+
+With MkDocs, this situation typically occurs when the website 
+is documenting an application that relies on a 
+"[djangolike/jinjalike language](https://medium.com/@i5ar/template-languages-a7b362971cbc)" like:
+
+- Django Template Language
+- Jinja2 (Python)
+- Nunjucks (Javascript)
+- Twig (PHP)
+- ...
+
+This may also happen for pages that documents
+[Ansible](https://ansible-docs.readthedocs.io/zh/stable-2.0/rst/intro.html) directives, which often contain
+[variables expressed in a Jinja2 syntax](https://ansible-docs.readthedocs.io/zh/stable-2.0/rst/playbooks_variables.html#using-variables-about-jinja2).
+
+
+#### Snippets Containing LaTeX
+
+With the plug-in enabled, LaTeX snippets 
+would fail to build because {{?}} will trigger the interpretation
+of a Jinja2 macro (since `{{` and `}}` are markers).LaTeX snippets
+
+For example, the following LaTeX snippet is used to draw a table:
+
+    ```LaTeX
+    \begin{tabular}{|ccc|}
+        \hline
+        2   & 9     & 4\\
+        7   & \multicolumn{2}{c|} {\multirow{2}*{{?}}} \\
+        6   &       &\\
+        \hline
+    \end{tabular}
+    ```
+
+
+### Two Cautions
+
+!!! Warning
+    Fencing Jinja2 statements parts as blocks of code
+    with the markdown convention
+    (using three backticks or three tildes) **will not prevent**
+    their interpretation, because this macros plugin intentionally ignores them.
+
+    This is to allow advanced use cases where the content of the code block
+    must be computed on the fly.
+
+!!! Note "No Risk of intereference of Jinja2 statements with HTML Rendering"
+
+    There is, of course, a **third use of Jinja2 statements**:
+    MkDocs also use them in templates to render HTML pages. **Fortunately,
+    we can safely ignore that fact.**
+
+    **There is in principle no risk that MkDocs will accidentally
+    interpret any Jinja2 statements in markdown pages, during the HTML
+    rendering process**.
+
+    The reason is that **MkDocs contains a safety**: **it automatically
+    escapes symbols such as '\{'**, which could have a meaning for the later
+    rendering in HTML (which also uses Jinja2 templates). 
+ 
+    Here we are trying to solve a different problem:
+    **how to avoid interpretation** of Jinja2 statements
+    **by mkdocs-macros**,
+    so that **they actually appear in the HTML output**?
+
+## Solutions
+
+### Solution 1 (Opt-out): Exclude one page from the rendering process
+
+_From version 0.5.7_
+
+!!! Tip "Quick fix"
+    This solution is a quick fix, if you are "migrating"
+    a pre-existing mkdocs project under mkdocs-macros, and
+    some markdown pages fail, or do not display correctly.
+
+    This will leave more time to implement the next solutions.
+
+
+In the header of the markdown page, indicate that the markdown should
+be used "as-is" (no rendering of mkdocs-macros),
+by setting the `ignore_macros` meta-data key to the `true`value.
+
+
+```yaml
+---
+# YAML header
+render_macros: false
+---
+```
+
+Any other value than `true` (or an absence of this key), will be interpreted
+as a `false` value.
+
+_From version 1.0.0_
+This directive is also accepted, though it is now deprecated:
+
+```yaml
+---
+# YAML header
+ignore_macros: true
+---
+```
+
+
+
+### Solution 2 (Opt-in): Specify which pages must be rendered
+
+_From version 1.0.0_
+
+!!! Tip "Large preexisting projects"
+    If you already have a large mkdocs project and have several
+    problematic pages, or do not wish to control
+    the rendering of all pages, this solution may be for you.
+
+The **opt-in** solution consists of changing the defaut behavior of 
+mkdocs-macros: no pages will be rendered (no macros interpreted)
+unless this is specifically requested in the page's header.
+
+To change the default behavior, set the `render_by_default` parameter
+to false in the config file (mkdocs.yml):
+
+```yaml
+plugins:
+  - search
+  - macros:
+      render_by_default: false
+```
+
+To render a specific page:
+
+```yaml
+---
+# YAML header
+render_macros: true
+---
+```
+
+mkdocs-macros will _not_ attempt to render the other pages.
+
+### Solution 3: Snippets as jinja2 strings (one-liners)
+
+This hack works for simple one-line snippets.
+Suppose you want to prevent the
+string `{{ 2 + 2 }}` from being interpreted. It would be sufficient to treat
+it as if it was a string in jinja2.
+
+    {{ "{{ 2 + 2 }}" }}
+
+You could also use expressions that contain the double quote symbol,
+but in this case you must bracket them with simple quotes:
+
+    {{ '{{ "Hello world" }}' }}
+
+!!!Warning
+    Triple quotes (`"""`) around strings are not allowed in Jinja2, so this
+    hack cannot be used for multiline statements.
+
+### Solution 4: Explicitly marking the snippets as 'raw'
+
+The standard solution is to isolate each snippet of code that should not
+be interpreted, using the standard jinja2 `raw` directive,
+which exists for that purpose:
+
+    {% raw %}
+    - task: "create a directory
+      file:
+        path: "{{ folder_path }}"
+        state: directory
+        recurse: true
+    {% endraw %}
+
+### Solution 5: Altering the syntax of jinja2 for mkdocs-macros
+
+Sometimes the introduction of mkdocs-macros comes late in the chain, and the
+existing pages already contain a lot of Jinja2 statements that are
+should appear in the final HTML pages: escaping all of them
+would not really be an option.
+
+Or else, you do not wish to bother the writers of markdown pages
+with the obligation of escaping Jinja2 statements.
+
+!!! Tip "Solution"
+    Rather than refactoring all the existing markdown pages to fence
+    those Jinja2 statements,
+    it may be preferable to alter the markers for variables or blocks
+    used in mkdocs-macros.
+
+For example, you may want to replace the curly brackets by square ones,
+like this:
+
+    # This is a title
+
+    It costs [[ unit_price ]].
+
+    [[% if unit_price > 5 %]]
+    This is expensive!
+    [[% endif %]]
+
+To obtain this result, simply add the following parameters in the
+`macros` section. There are two parameters for code blocks (start and
+end) and two for variables (start and end).
+
+      - macros:
+          j2_block_start_string: '[[%'
+          j2_block_end_string: '%]]'
+          j2_variable_start_string: '[['
+          j2_variable_end_string: ']]'
+
+You may, of course, chose the combination that best suits your needs.
+
+!!! Warning "Caution 1: You are walking out of the beaten path."
+    Altering the standard markers used in jinja2 has far-reaching consequences,
+    because it will oblige you henceforth use a new form for templates,
+    which is specific to your project. When reading this
+    documentation, you will have to mentally convert all the examples.
+
+!!! Warning "Caution 2: Use with discretion"
+    Errors in defining these new markers, or some
+    accidental combinations of markers may have unpredictable
+    consequences. **Use with discretion, and at your own risk**. In case
+    of trouble, please do not expect help from the maintainers of this
+    plugin.
+
diff --git a/webdoc/mkdocs.yml b/webdoc/mkdocs.yml
index 8567485..77ae430 100644
--- a/webdoc/mkdocs.yml
+++ b/webdoc/mkdocs.yml
@@ -23,6 +23,7 @@ nav:
       - "Writing modules": macros.md
       - Writing pluglets: pluglets.md
       - "Advanced usage": advanced.md
+      - Controlling page rendering: rendering.md 
     - Faq:
       - "Tips and Tricks": tips.md
       - "Troubleshooting": troubleshooting.md