mmp

mkdocs-macros-plugin

Create richer and more beautiful pages in MkDocs, by using variables and calls to macros in the markdown code.

Showing:

Popularity

Downloads/wk

0

GitHub Stars

120

Maintenance

Last Commit

20d ago

Contributors

16

Package

Dependencies

8

License

MIT

Categories

Readme

mkdocs-macros-plugin: Unleash the power of MkDocs with variables and macros

License: MIT Language PyPI Github macros

Overview

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).

Using variables

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 ... %}).

Defining variables

Regular variables can be defined in five ways:

NoValidityFor whomDescription
1.globaldesigner of the websitein the mkdocs.yml file, under the extra heading
2.globalcontributorin external yaml definition files
3.globalprogrammerin a main.py file (Python), by adding them to a dictionary
4.local (page)writerin the YAML header of each Markdown page
5.local (page)writerwith a {%set variable = value %} statement

In addition, predefined objects are provided (local and global), typically for the environment, project, page, git information, etc.

Macros and filters

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.

Installation

Prerequisites

  • Python version > 3.5
  • MkDocs version >= 1.0 (it should work > 0.17 (it should be compatible with post 1.0 versions)

Standard installation

pip install mkdocs-macros-plugin

"Manual installation"

To install the package, download it and run:

pip install .
# or...
python setup.py install

Development/test installation

To install the extra dependencies required for testing the package, run:

pip install "mkdocs-macros-plugin[test]"

Declaration of plugin

Declare the plugin in the the file mkdocs.yml:

plugins:
    - search
    - macros

Note: If you have no plugins entry in your config file yet, you should also add the search plugin. If no plugins entry is set, MkDocs enables search by default; but if you use it, then you have to declare it explicitly.

Check that it works

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 plugins environment:

macros_info()

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 pluglets

What are pluglets?

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.

### How to add a pluglet to an mkdocs project?

Install it:

pip install <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 in mkdocs-test (github).

Rate & Review

Great Documentation0
Easy to Use0
Performant0
Highly Customizable0
Bleeding Edge0
Responsive Maintainers0
Poor Documentation0
Hard to Use0
Slow0
Buggy0
Abandoned0
Unwelcoming Community0
100
No reviews found
Be the first to rate

Alternatives

No alternatives found

Tutorials

No tutorials found
Add a tutorial