Package: mkdocs-macros-plugin
Unleash the power of MkDocs with variables and macros:open_file_folder:Used by > 2K repositories on Github🥇 Listed asHigh-Quality Pluginmkdocs-macros-pluginis a general-purpose plugin forMkDocsthat usesvariablesandmacros(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 themkdocs-macro documentationon Read the Docs.Overviewmkdocs-macros-pluginis a plugin that makes it easier for contributors
of anMkDocswebsite to produce richer and more beautiful pages. It transforms the markdown pages
intojinja2templates
that usevariables, calls tomacrosand customfilters.You can also partially replace MkDocs plugins with mkdocs-macros modules,
andpluglets(pre-installed modules).Using variablesYou 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 aprice()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 beHTML 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 byJinja2 templatessuch
as conditions ({% if ... %}) and loops ({% for ... %}).Defining variablesRegularvariablescan be defined in five ways:NoValidityFor whomDescription1.globaldesigner of the websitein themkdocs.ymlfile, under theextraheading2.globalcontributorin external yaml definition files3.globalprogrammerin amain.pyfile (Python), by adding them to a dictionary4.local (page)writerin the YAML header of each Markdown page5.local (page)writerwith a{%set variable = value %}statementIn addition, predefined objects are provided (local and global), typically
for the environment, project, page, git information, etc.Macros and filtersSimilarly programmers can define their ownmacrosandfilters,
as Python functions in themain.pyfile,
which the users will then be able to
use without much difficulty, as jinja2 directives in the markdown page.InstallationPrerequisitesPython version > 3.7MkDocs version >= 1.0
(compatible with post 1.5 versions)Standard installationpip install mkdocs-macros-plugin"Manual installation"To install the package, download it and run:pip install .
# or...
python setup.py installDevelopment/test installationTo install the extra dependencies required for testing the package, run:pip install "mkdocs-macros-plugin[test]"Declaration of pluginDeclare the plugin in the filemkdocs.yml:plugins:-search-macrosNote:If you have nopluginsentry 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.Check that it worksThe 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 sayinfo.md):{{ macros_info() }}In the terminal, restart the environment:> mkdocs serveYou 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.Using plugletsWhat are pluglets?Plugletsare 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 throughPyPI.How to add a pluglet to an mkdocs project?Install it:pipinstall<pluglet_name>Declare it in the project's config (mkdocs.yml) file:plugins:-search-macros:modules:-<pluglet_name>How to write a pluglet?See instructions in the documentation.A sample pluglet can be found inmkdocs-test (github).