📂 Used by > 2K repositories on Github
🥇 Listed as High-Quality Plugin
mkdocs-macros-plugin is a general-purpose plugin for MkDocs
that uses variables and macros (functions) to automate tasks, and produce richer and more beautiful pages.
The unit price of product A is {{ unit_price }} EUR.
Taking the standard discount into account,
the sale price of 50 units is {{ price(unit_price, 50) }} EUR.View the mkdocs-macro documentation on Read the Docs.
mkdocs-macros-plugin is a plugin that makes it easier for contributors of an MkDocs website to produce richer and more beautiful pages. It transforms the markdown pages into jinja2 templates that use variables, calls to macros and custom filters.
You can also partially replace MkDocs plugins with mkdocs-macros modules, and pluglets (pre-installed modules).
You can leverage the power of Python in markdown thanks to jinja2 by writing this :
The unit price of product A is {{ unit_price }} EUR.
Taking the standard discount into account,
the sale price of 50 units is {{ price(unit_price, 50) }} EUR.If you defined a price() function, this could translate into:
The unit price of product A is 10.00 EUR.
Taking the standard discount into account,
the sale price of 50 units is 450.00 EUR.
The result of a macro can be HTML code: this makes macros especially useful to make custom extensions to the syntax of markdown, such as buttons, calls to email, embedding YouTube videos, etc.
It is possible to use the wide range of facilities provided by
Jinja2 templates such
as conditions ({% if ... %}) and loops ({% for ... %}).
Regular variables can be defined in five ways:
| No | Validity | For whom | Description |
|---|---|---|---|
| 1. | global | designer of the website | in the mkdocs.yml file, under the extra heading |
| 2. | global | contributor | in external yaml definition files |
| 3. | global | programmer | in a main.py file (Python), by adding them to a dictionary |
| 4. | local (page) | writer | in the YAML header of each Markdown page |
| 5. | local (page) | writer | with a {%set variable = value %} statement |
In addition, predefined objects are provided (local and global), typically for the environment, project, page, git information, etc.
Similarly programmers can define their own macros and filters,
as Python functions in the main.py file,
which the users will then be able to
use without much difficulty, as jinja2 directives in the markdown page.
- Python version > 3.7
- MkDocs version >= 1.0 (compatible with post 1.5 versions)
pip install mkdocs-macros-plugin
To install the package, download it and run:
pip install .
# or...
python setup.py install
To install the extra dependencies required for testing the package, run:
pip install "mkdocs-macros-plugin[test]"
Declare the plugin in the file mkdocs.yml:
plugins:
- search
- macrosNote: If you have no
pluginsentry in your config file yet, you should also add thesearchplugin. If nopluginsentry is set, MkDocs enablessearchby default; but if you use it, then you have to declare it explicitly.
By default, undefined variables are printed to the page as-is. If you wish for a page to fail on undefined variables, you should use the below configuration instead:
plugins:
- search
- macros
on_undefined: strictFor details and more options, see the documentation.
The recommended way to check that the plugin works properly is to add the
following command in one of the pages of your site (let's say info.md):
{{ macros_info() }}
In the terminal, restart the environment:
> mkdocs serve
You will notice that additional information now appears in the terminal:
INFO - Building documentation...
[macros] Macros arguments: {'module_name': 'main', 'include_yaml': [], 'j2_block_start_string': '', 'j2_block_end_string': '', 'j2_variable_start_string': '', 'j2_variable_end_string': ''}
Within the browser (e.g. http://127.0.0.1:8000/info), you should see a description of the plugin's environment:
If you see it that information, you should be all set.
Give a good look at the General List, since it gives you an overview of what you can do out of the box with the macros plugin.
The other parts give you more detailed information.
Pluglets are small, easy-to-write programs that use mkdocs-macro's foundation to offer services to mkdocs projects, which would normally be offered by plugins.
Pluglets are Python packages, which can be hosted on github, and distributed through PyPI.
Install it:
pip install <pluglet_name>Declare it in the project's config (mkdocs.yml) file:
plugins:
- search
- macros:
modules:
- <pluglet_name> See instructions in the documentation.
A sample pluglet can be found in mkdocs-test (github).
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent