Document 1.0.2 (macros in the title of the page)

CHANGELOG.md

@@ -4,7 +4,15 @@ 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, 2024-04-23
+## 1.0.2, 2023-07-02
+* Added: it is now possible to use macros in page titles, in the
+    nav section of the yaml file, or in the level 1 titles; 
+    the macros are correctly interpreted in the navigation part
+    of the page.
+
+## 1.0.1, 2023-05-25
+
+## 1.0.0-alpha, 2023-04-23
 
 * Improved user guide, with introduction of two new pages:
     "Controlling macro rendering" and "Post production".

mkdocs_macros/plugin.py

@@ -18,8 +18,6 @@
 from mkdocs.config.config_options import Type as PluginType
 from mkdocs.plugins import BasePlugin
 from mkdocs.structure.pages import Page
-from mkdocs.structure.nav import Section
-from mkdocs.utils import get_markdown_title
 
 from mkdocs_macros.errors import format_error
 from mkdocs_macros.context import define_env
@@ -661,20 +659,6 @@ def on_nav(self, nav, config, files):
         Capture the nav and files objects so they can be used by
         templates.
         """
-        # Render also the navigation items, so that macros are interpreted
-        # also in navigation
-        # solution to issue #144
-        def render_nav(nav):
-            for nav_item in nav:
-                try:
-                    nav_item.title = self.render(nav_item.title)
-                except AttributeError:
-                    # not title in pre-page navigation, do nothing
-                    pass
-                if isinstance(nav_item, Section): 
-                    # for second, third level titles
-                    render_nav(nav_item.children)
-        render_nav(nav)
         # nav has useful properties like 'pages' and 'items'
         # see: https://github.com/mkdocs/mkdocs/blob/master/mkdocs/structure/nav.py
         self.variables['navigation'] = nav
@@ -738,9 +722,9 @@ def on_page_markdown(self, markdown, page, config,
                 markdown=self.markdown,
                 # page=page,
             )
-            # HACK: convert macros in the title from render (if exists)
+            # Convert macros in the title from render (if exists)
             # to answer 144
-            page.title = self.render(page.title)
+            page.title = self.render(markdown=page.title)
 
             # execute the post-macro functions in the various modules
             for func in self.post_macro_functions:

setup.py

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

webdoc/docs/tips.md

@@ -1,6 +1,33 @@
 Tips and Tricks
 ===============
 
+Can I use macros in page titles?
+--------------------------------
+_New in 1.0.2_
+
+Yes. You can use a macro in the title of the page in:
+
+1. The `nav` section of the config file 
+1. As the metadata `title` in the yaml header of the page.
+1. Directly as the header 1 of the page, e.g.  
+`#Environment at {{unit_price}}"`.
+
+For example, in `nav`section of the config file,
+e.g. 
+
+```yaml
+nav:
+    - Home: index.md
+    - Environment at {{ unit_price}}: environment.md
+    - Second:
+        - Also for {{ unit_price}}: other.md
+    - Not interpreted: literal.md
+```
+
+!!! Note "Rendering"
+    The macros in the title are rendered _just after_ those in the markdown
+    file. Hence they benefit from the whole context (variables, functions, filters) available in the page.
+
 How can I get the project's document directory?
 -------------------------------------