diff --git a/docs/reference/abbreviations.md b/docs/reference/abbreviations.md
index 7e0e7f51b..9398c3b10 100644
--- a/docs/reference/abbreviations.md
+++ b/docs/reference/abbreviations.md
@@ -73,7 +73,7 @@ and embed them into any other file.
_Example_:
-=== "docs/path/to/a/page.md"
+=== "docs/page.md"
```` markdown
The HTML specification is maintained by the W3C.
diff --git a/docs/reference/icons-emojis.md b/docs/reference/icons-emojis.md
index 47a9e0771..e7c225458 100644
--- a/docs/reference/icons-emojis.md
+++ b/docs/reference/icons-emojis.md
@@ -5,9 +5,9 @@ template: overrides/main.html
# Icons + Emojis
One of the best features of Material for MkDocs is the possibility to use [more
-than _7.000 icons_][1] and _thousands of emojis_ in your project documentation
-with practically zero additional effort. Furthermore, custom icons can be used
-in `mkdocs.yml`, documents and templates.
+than 7.000 icons][1] and thousands of emojis in your project documentation
+with practically zero additional effort. Furthermore, custom icons can be added
+and used in `mkdocs.yml`, documents and templates.
## Configuration
diff --git a/docs/reference/meta-tags.md b/docs/reference/meta-tags.md
index 82cbddcf1..2d7950906 100644
--- a/docs/reference/meta-tags.md
+++ b/docs/reference/meta-tags.md
@@ -77,6 +77,8 @@ extra:
## Customization
+### Custom meta tags
+
In order to add `meta` tags to your document, you can [extend the theme][7] and
simply [override the `extrahead` block][8] with the respective tags, e.g. to set
policies for search engines:
diff --git a/docs/reference/variables-macros.md b/docs/reference/variables-macros.md
deleted file mode 100644
index 205224ea3..000000000
--- a/docs/reference/variables-macros.md
+++ /dev/null
@@ -1,332 +0,0 @@
----
-template: overrides/main.html
----
-
-# Variables and Macros
-
-The power of the Markdown language comes from its simplicity and
-visual clarity. Its downside is that it far more limited than HTML.
-That is the reason why Markdown extensions have been developed,
-such as [Footnotes](../Footnotes) or [Admonition](../Admonition)
-(for notes and tips).
-
-Sometimes, however, one wishes to add more customization
-to Markdown pages, to perform tasks that are
-specific to the documentation project.
-This is the purpose of **variables** and **macros**, provided
-by the [macros plugin](https://github.com/fralau/mkdocs_macros_plugin).
-
-!!! Note "Example"
-
- ```
- The unit price of product A is {{ unit_price }} EUR.
- The sale price of {{ no }} units is {{ price(no, unit_price) }} EUR.
- ```
-
- If you defined a variable `no`w with a value of 50,
- a variable `unit_price` with a value of 10,
- and a macro `price()` (which multiplies the two), this could translate into:
-
- ```
- The unit price of product A is 10.00 EUR,
- and the sale price of 50 units is 500.00 EUR.
- ```
-
-
-Those who have used **wikis** engines (user-editable websites)
-in the past are probably already familiar with those notions.
-
-!!!Tip
- You may also use this
- plugin to add **buttons** or other advanced functionality
- (e.g. pulling data from a database) that is ordinarily
- not provided by Markdown or one of its extensions.
-
-
-
-## Configuration
-
-The [macros plugin](https://github.com/fralau/mkdocs_macros_plugin)
-makes it easier for contributors of an MkDocs website to produce richer and more beautiful pages. It enriches pages with calls to variables and macros.
-
-
-!!! Note
- This plugin has been tested to work with the **Material** theme.
- It is also compatible with most other themes.
-
-
-See the [installations instructions](https://mkdocs-macros-plugin.readthedocs.io/en/latest/#installation) for the plugin.
-
-
-In order to make it work with your MkDocs project,
-declare it in the config file:
-
-```yaml
-plugins:
- - search
- - macros
-```
-
-
-!!!Tip
- The recommended way to check that the plugin works properly is to add the following line in one of the pages of your site
- (typically `index.md`):
-
- ```
- {{ macros_info() }}
- ```
-
- If the plugin is properly installed, this will display
- a test page with lots of information, especially predefined
- variables and macros.
-
-
-## Usage
-
-### Variables
-
-**Variables** are names with an attached value
-(Markdown, HTML, ...), which can be reused anywhere in the pages.
-Changing the value of the variable, will
-change the text displayed, in all markdown pages
-where this variable is called; this is useful for consistency.
-
-
-
-#### Predefined Variables
-
-With the macros plugin, a large set of predefined variables
-are available out of the box, e.g. :
-
-Example | Description
---- | ---
-`{{ config.site_name }}` | main title of the website
-`{{ environment.system }}`| name of the OS
-`{{ page.title }}` | title of the page
-`{{ git.short_commit}} ({{ git.date}}) by {{ git.author}}` | **git information** (if applicable)
-
-
-!!! Tip "Discoverability"
- To explore the possibilities, just insert the
- following code into one of the Markdown pages:
-
- ```
- {{ macros_info() }}
- ```
-
-#### Defining Variables
-
-All variables defined under `extra` in your config file become
-available:
-
-```yaml
-extra:
- price: 12.50
- company:
- name: Acme
- address: ....
- website: www.acme.com
-```
-
-This becomes available as, e.g.:
-
-```html
-The price of the product is {{ price }}.
-
-See [more information on the website]({{ company.website }}).
-
-See more information on the website.
-```
-
-### Macros
-
-**Macros** are Python functions that return a value (Markdown, HTML...)
-which depends on something else.
-
-A macro may have arguments,
-or depend on conditions that change every time MkDocs
-is run again (e.g. time or version number, etc.).
-
-Writing a macro is very easy: it requires only basic knowledge of Python,
-and clear idea of what string result (Markdown, HTML, ...)
-you want to produce.
-
-!!! Note
- In principle the result must be a string,
- but it could be _any type or class_
- as long it is translatable into a string.
-
-
-#### Location of the Macros' Code
-
-By default, your macros are defined in a `main.py` file,
-which is located in website's project directory
-(generally beside the `mkdocs.yml` file).
-You may [change that location and name](https://mkdocs-macros-plugin.readthedocs.io/en/latest/python/#location-of-the-module).
-
-#### Example 1: Arithmetics
-
-Imagine you want to calculate the cost of a batch, with
-the unit price and the no of items, plus a 10% shipping costs:
-
-```
-This will cost {{ total_price(4, 12.50)}} dollars.
-```
-
-Which will be translated into:
-
-```
-This will cost 55 dollars.
-```
-
-But if `unit_price` and `quantity` have been defined under `extra`:
-
-```yaml
-extra:
- quantity: 4
- unit_price: 12.50
-```
-
-```
-This will cost {{ total_price(quantity, unit_price)}} dollars.
-```
-
-??? Tip "Module content"
- The module will look as follows:
-
- ```python
- """
- Basic example of a Mkdocs-macros module
- """
-
- import math
-
- def define_env(env):
- """
- This is the hook for defining macros
- """
-
- @env.macro
- def total_price(quantity, unit_price):
- "Calculate the price plus shipping costs
- price = quantity * unit_price
- shipping_costs = price * 10%
- return price + shipping_costs
- ```
-
-#### Guidelines
-
-1. All you need to define is a `define_env(env)` function.
-
-2. To declare a Python function as a macro, just precede it by the
-`@env.macro` decorator.
-It will appear in the documentation produced by `{{ macros_info() }}`
-
-3. You may define as many macros as needed under `define_env()`.
-
-4. Write a macro's docstring from the viewpoint of the users who will
- use it (it will be displayed in the macro's description).
-
-#### Example 2: Creating a Button
-
-This function is alternative, more flexible way to generate a button
-(see [Buttons](../buttons#adding-buttons)):
-
-In your markdown page:
-
-```
-{{ button('Try this', 'https://your.website.com/page') }}
-```
-
-Result:
-
-
-
-[Try this](https://your.website.com/page){: .md-button }
-
-
-??? Tip "Module content"
-
- In your Python module:
-
- ```python
- def define_env(env):
- """
- This is the hook for defining macros
- """
- # Optional: a special function for making relative urls point to root
- fix_url = env.variables.fix_url
-
- @env.macro
- def button(label, url):
- "Add a button"
- url = fix_url(url)
- HTML = """%s"""
- return HTML % (url, label)
- ```
-
-
-
-
-## Advanced Usage: Jinja2 Constructs
-
-The macros plugin relies on the [Jinja2](https://jinja.palletsprojects.com/en/2.11.x/templates/) template engine.
-
-This makes the facilities of that template engine available
-within a Markdown page.
-
-
-
-!!! Note
- Not that this is distinct from the standard, low-level use of Jinja2 by
- MkDocs to convert the Markdown pages into HTML.
- In principle this will **not** interfere with it.
-
-### Conditions and Loops
-Most of what is described in its documentation,
-including constructs such as
-
-- [conditions](https://jinja.palletsprojects.com/en/2.11.x/templates/#if):
- `{% if ... %}`
-- [loops](https://jinja.palletsprojects.com/en/2.11.x/templates/#for):
- `{% for ... %} `
-
-
-will work out of the box.
-
-!!! Tip
- Instead of using Jinja2 constructs to generate pure HTML
- as in the examples shown,
- you could use them to generate Markdown,
- or whichever mix of Markdown, HTML, CSS
- or even Javascript that might be required for your needs.
-
-### Filters
-
-Jinja2's [built-in filters](https://jinja.palletsprojects.com/en/2.11.x/templates/#list-of-builtin-filters) are available e.g. :
-
-`{{ "HELLO WORLD" | lower }}` results in `hello world`
-
-You may [write your own filters in the Python module](https://mkdocs-macros-plugin.readthedocs.io/en/latest/python/#defining-macros-and-filters-as-well-as-variables),
-using the `@env.filter` decorator.
-
-### Including External Files
-
-Quite aside from variables and macros, you may include external files
-containing snippets (typically, Markdown files).
-
-You may use the include directive from jinja2, directly in your markdown code e.g.:
-
- ## Paragraph
- {% include 'snippet.md' %}
-
-Including another markdown file will therefore execute the macros.
-
-By default, the relative path for included files starts from `docs`,
-but [this can be changed](https://mkdocs-macros-plugin.readthedocs.io/en/latest/advanced/#changing-the-directory-of-the-includes).
-
-## More Information on the Macros Plugin
-
-* [Main documentation page](https://mkdocs-macros-plugin.readthedocs.io/en/latest/)
-* [Including git information in a page](https://mkdocs-macros-plugin.readthedocs.io/en/latest/git_info/)
-* [Writing macros and filters](https://mkdocs-macros-plugin.readthedocs.io/en/latest/python/)
diff --git a/docs/reference/variables.md b/docs/reference/variables.md
new file mode 100644
index 000000000..8b8414aa9
--- /dev/null
+++ b/docs/reference/variables.md
@@ -0,0 +1,99 @@
+---
+template: overrides/main.html
+---
+
+# Variables
+
+Macros and variables are powerful tools to parametrize Markdown files, as they
+allow to perform Jinja templating directly from Markdown. This is especially
+useful to include technical data from other files and add central variables via
+`mkdocs.yml`.
+
+## Configuration
+
+### Macros
+
+The [macros][1] plugin adds support to reference variables and call macros and
+supports Jinja templating directly from Markdown. It can be installed with
+`pip`:
+
+```
+pip install mkdocs-macros-plugin
+```
+
+Then, add the following to `mkdocs.yml`:
+
+``` yaml
+plugins:
+ - macros
+```
+
+ [1]: https://github.com/fralau/mkdocs_macros_plugin
+
+## Usage
+
+### Using predefined variables
+
+A set of predefined variables is enabled by default and can be used from
+Markdown, including data from `mkdocs.yml`. More specifically, predefined
+variables fall into the following categories:
+
+- `config.*`: configuration parameters from `mkdocs.yml`
+- `page.*`: metadata and content of current page
+- `navigation.*`: list of all pages and sections
+- `environment.*`: underlying operating system
+- `git.*`: git-related information, if available
+
+_Example_:
+
+``` markdown
+Welcome to {{ config.site_name }}!
+```
+
+_Result_:
+
+``` markdown
+Welcome to Material for MkDocs!
+```
+
+A list of all predefined variables can be printed with:
+
+```
+{{ macros_info() }}
+```
+
+### Using custom variables
+
+All data defined under `extra` in `mkdocs.yml` is automatically exposed as a
+variable and can be used from the template. This enables centralized parameter
+storage and management.
+
+_Example_:
+
+=== "docs/page.md"
+
+ ```` markdown
+ The unit price is {{ unit.price }}
+ ````
+
+=== "mkdocs.yml"
+
+ ``` yaml
+ extra:
+ unit:
+ price: 12.50
+ ```
+
+_Result_:
+
+The unit price is 12.50.
+
+## Customization
+
+### Custom macros
+
+The [macros][1] plugin allows to define custom macros which can then be used
+from Markdown files. See the [official documentation][2] for more information
+how to define custom macros.
+
+ [2]: https://mkdocs-macros-plugin.readthedocs.io/en/latest/python/
diff --git a/docs/setup/adding-a-git-repository.md b/docs/setup/adding-a-git-repository.md
index aff39a97c..ad5a2e2f4 100644
--- a/docs/setup/adding-a-git-repository.md
+++ b/docs/setup/adding-a-git-repository.md
@@ -93,7 +93,7 @@ behavior can be changed by setting [`edit_uri`][9] in `mkdocs.yml`:
edit_uri: ""
```
- [5]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html#L299-L308
+ [5]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html#L302-L311
[6]: https://github.com/
[7]: https://about.gitlab.com/
[8]: https://bitbucket.org/
diff --git a/mkdocs.yml b/mkdocs.yml
index ce5edbe7e..0648a848b 100755
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -180,7 +180,7 @@ nav:
- Lists: reference/lists.md
- MathJax: reference/mathjax.md
- Meta tags: reference/meta-tags.md
- - Variables and macros: reference/variables-macros.md
+ - Variables: reference/variables.md
- Changelog:
- Release notes: changelog.md
- Upgrading: upgrading.md