Giter Club home page Giter Club logo

mkdocs_macros_plugin's Introduction

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

License: MIT PyPI

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.

Regular variables can be defined in four ways:

  1. global (for designers of the website): in the mkdocs.yml file, under the extra heading
  2. global(for contributors): in external yaml definition files
  3. global (for programmers): in a main.py file (Python), by adding them to a dictionary
  4. local (for contributors): in the markdown file, with a {%set variable = value %} statement

Similarly programmers can define 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.

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.

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:

python setup.py install

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.

mkdocs_macros_plugin's People

Contributors

bomberus avatar fralau avatar jsoucheiron avatar mlenkeit avatar mriedem avatar sebastienwarin avatar

Watchers

 avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.