Insert suggestion to use MkDocs-Macros for variables and macros

  - bump version number

Author: fralau

pyproject.toml

@@ -3,21 +3,14 @@ name = "mkdocs-mermaid2-plugin"
 
 # This version number is the REFERENCE for the rest of the project,
 # particularly for update_pypi.sh
-version = "1.2.2"
+version = "1.2.3"
 
 description = "A MkDocs plugin for including mermaid graphs in markdown sources"
 readme = "README.md"
 license = { text = "MIT" }
 requires-python = ">=3.8"
-authors = [
-    { name = "Laurent Franceschetti"},
-]
-keywords = [
-    "markdown",
-    "mermaid",
-    "mkdocs",
-    "python",
-]
+authors = [{ name = "Laurent Franceschetti" }]
+keywords = ["markdown", "mermaid", "mkdocs", "python"]
 classifiers = [
     "Development Status :: 5 - Production/Stable",
     "Intended Audience :: Developers",
@@ -42,17 +35,10 @@ dependencies = [
 packages = { find = { exclude = ["*.tests"] } }
 
 [project.optional-dependencies]
-test = [
-    "mkdocs-macros-test",
-    "mkdocs-material",
-    "packaging",
-    "requests-html",
-]
+test = ["mkdocs-macros-test", "mkdocs-material", "packaging", "requests-html"]
 
 [project.entry-points."mkdocs.plugins"]
 mermaid2 = "mermaid2.plugin:MarkdownMermaidPlugin"
 
 [project.urls]
 Homepage = "https://github.com/fralau/mkdocs-mermaid2-plugin"
-
-

webdoc/docs/tips.md

@@ -1,6 +1,64 @@
 # Tips and Tricks
 
 
+## Using variables and macros in diagrams (MkDocs-Macros)
+
+What if your diagrams contain a repetitive string, like the URL of a website?
+
+Instead of writing:
+
+```
+graph TD;
+    Platform-->Gaming;
+    click Gaming "http://127.0.0.1:8000/Gaming/";
+```
+
+You might want to use a **variable**:
+
+```
+graph TD;
+    Platform-->Gaming;
+    click Gaming "{{ my_website }}/Gaming/";
+```
+
+With the variable defined in your project's config file:
+
+```yaml
+extra:
+  my_website: http://127.0.0.1:8000
+```
+
+
+In this way, you will be able to change that value whenenever you need it.
+
+To do that, you would have to use the [Mkdocs-Macros plugin](https://mkdocs-macros-plugin.readthedocs.io/).
+
+
+
+This requires [installing the plugin](https://mkdocs-macros-plugin.readthedocs.io/en/latest/#standard-installation), and declaring it in the config file.
+
+!!! Caution
+    Variables are **not** part of the Mermaid specification. The Macros plugin simply expands the variables in the
+    Markdown page, so that the result is a standard Mermaid diagram.
+
+    The same variables can be used in any part of the page, outside of Mermaid diagrams.
+
+
+Declare the plugins in the config file, in that order:
+
+```yaml
+plugins:
+    - search
+    - macros
+    - mermaid2
+```
+
+!!! Tip "Using macros to generate diagrams"
+    If you can program in Python, you could go further than that: you could use a Python module (`main.py`) to define
+    [**macros** (functions)](https://mkdocs-macros-plugin.readthedocs.io/en/latest/macros/)
+    that produce hyperlinks or pieces of diagrams from data,
+    or even complete diagrams from a source file.
+
 
 ## Setting the security level to "loose"