From 79e06cac0b8e071b494c64d8a84906b33dc4d1a1 Mon Sep 17 00:00:00 2001
From: bs-jena <32900380+bs-jena@users.noreply.github.com>
Date: Sat, 31 Oct 2020 15:11:56 +0100
Subject: [PATCH] Added documentation on using variables in snippets (#2006)

* variables do not work in snippets included using Snippets extension
* workaround: use macros plugin to define snippets (as described here https://mkdocs-macros-plugin.readthedocs.io/en/latest/advanced/#including-snippets-in-pages)
---
 docs/reference/variables.md | 64 +++++++++++++++++++++++++++++++++++++
 1 file changed, 64 insertions(+)

diff --git a/docs/reference/variables.md b/docs/reference/variables.md
index 62be9897a..5056e36f6 100644
--- a/docs/reference/variables.md
+++ b/docs/reference/variables.md
@@ -88,6 +88,70 @@ _Result_:
 
 The unit price is 12.50.
 
+### Using variables in snippets
+
+You may want to use variables in snippets, for example, when describing the same procedure in multiple contexts where only one piece of information differs. This does not work with snippets that are included using the [Snippets](../abbreviations.md#snippets) extension. Instead, you can use the [macros](#macros) plugin for defining snippets.
+
+To this end, add the snippet location using the `include_dir` parameter to the plugin's configuration in `mkdocs.yml`, for example:
+
+```
+plugins:
+    - search
+    - macros:
+        include_dir: snippets
+```
+
+In your Markdown file, you call the snippets like
+
+```markdown
+{% include 'snip.md' %}
+```
+
+This example illustrates the behavior:
+
+=== "snippets/snip.md"
+
+    _Code_
+
+    ```markdown
+    Here goes the variable: {{ page.meta.variables.number }}
+    ```
+
+=== "docs/page1.md"
+
+    _Code_
+
+    ```markdown
+    ---
+    variables:
+        number: 500
+    ---
+
+    {% include 'snip.md' %}
+    ```
+
+    _Result_
+
+    Here goes the variable: 500
+
+=== "docs/page2.md"
+
+    _Code_
+
+    ```markdown
+    ---
+    variables:
+        number: 1000
+    ---
+
+    {% include 'snip.md' %}
+    ```
+
+    _Result_
+
+    Here goes the variable: 1000
+
+
 ## Customization
 
 ### Custom macros