{
    "info": {
        "author": "Laurent Franceschetti",
        "author_email": "info@settlenext.com",
        "bugtrack_url": null,
        "classifiers": [
            "Development Status :: 5 - Production/Stable",
            "Intended Audience :: Developers",
            "Intended Audience :: Information Technology",
            "License :: OSI Approved :: MIT License",
            "Programming Language :: Python",
            "Programming Language :: Python :: 3.5",
            "Programming Language :: Python :: 3 :: Only"
        ],
        "description": "# mkdocs-macros-plugin: Unleash the power of MkDocs with variables and macros\n\n\n<!-- To update, run the following command: markdown-toc -i README.md -->\n\n<!-- toc -->\n\n- [Overview](#overview)\n- [Context and purpose](#context-and-purpose)\n  * [Sources of inspiration](#sources-of-inspiration)\n    + [mkdocs-markdownextradata (rosscdh)](#mkdocs-markdownextradata-rosscdh)\n    + [jinja2: variables can also be Python callables](#jinja2-variables-can-also-be-python-callables)\n    + [Macros in Wiki engines](#macros-in-wiki-engines)\n  * [Use Case: Overcoming the Intrinsic Limitations of Markdown Syntax](#use-case-overcoming-the-intrinsic-limitations-of-markdown-syntax)\n    + [Solution 1: Markdown extensions](#solution-1-markdown-extensions)\n    + [Solution 2: Custom HTML Code](#solution-2-custom-html-code)\n    + [Solution 3: Enter Macros](#solution-3-enter-macros)\n- [Installation](#installation)\n  * [Prerequisites](#prerequisites)\n  * [Procedure](#procedure)\n- [How to use it](#how-to-use-it)\n  * [Defining variables in the configuration file](#defining-variables-in-the-configuration-file)\n  * [Defining variables and macros in Python code](#defining-variables-and-macros-in-python-code)\n  * [Location of the module](#location-of-the-module)\n  * [Content of the module](#content-of-the-module)\n  * [Defining local variables and macros within the markdown page](#defining-local-variables-and-macros-within-the-markdown-page)\n    + [Variables](#variables)\n    + [Macros and other templating tools](#macros-and-other-templating-tools)\n\n<!-- tocstop -->\n\n## Overview\n**mkdocs-macros-plugin** is a plugin to make it easier for the contributors\nto a [MkDocs](mkdocs-macros-plugin) website to make richer and more beautiful\npages, by using **variables** and calls to **macros** in the markdown code.\n\nRegular **variables** can be defined in three ways:\n\n  1. global (for contributors): in the `mkdocs.yml` file,\n  under the 'extra' heading\n  1. global (for programmers): in a `main.py` file (Python),\n  by adding them to a dictionary\n  1. local (for contributors): in the markdown file, with a `{%set variable = value %}`\n statement\n\n\nSimilarly programmers can define **macros**, as Python functions in the `main.py` file, which the users will then be able to\nuse without much difficulty inside of the Python code.\n\nWith these two tools, you could write e.g.:\n\n```markdown\nThe unit price of product A is {{ unit_price }} EUR.\nTaking the standard discount into account,\nthe sale price of 50 units is {{ price(unit_price, 50) }} EUR.\n```\n\nWhich could translate into:\n\n```\nThe unit price of product A is 10.00 EUR.\nTaking the standard discount into account,\nthe sale price of 50 units is 450.00 EUR.\n```\n\n> The result of a macro can be **HTML code**:\nthis makes macros especially useful\nto make custom extensions to the syntax of markdown.\n\nIn reality, it is possible to use the full range of facilities of\n[Jinja2 templates](http://jinja.pocoo.org/docs/2.10/templates/).\n\n\n\n## Context and purpose\n\n### Sources of inspiration\n\n#### mkdocs-markdownextradata (rosscdh)\nThe idea for that extension came to me after I saw the excellent plugin\n[mkdocs-markdownextradata](https://github.com/rosscdh/mkdocs-markdownextradata-plugin) created by rosscdh, which takes metadata data\nfrom the `mkdocs.yml` file,  and allows you to insert them\nwith double curly brackets:\n\n```\nThe price of the item is {{price}}.\n```\n\nHis concept of using the [jinja2](http://jinja.pocoo.org/docs/2.10/)\ntemplating engine for that purpose was  simple and beautiful:\nall it took for this plugin was a few lines of code.\n\n\n#### jinja2: variables can also be Python callables\n\nAnd then I discovered that the creators of jinja2,\nin their great wisdom (thanks also to them!),\nhad decided to support *any* kind of Python variables,\n*including the callables*, typically functions, e.g.:\n\n```\nThe price of the item is {{calculate(2, 7.4)}}.\n```\n\nThey did not think it was worth more a few words,\nbut it was a diamond in plain sight.\n\n**Oh yeah?** So let's support them also in the markdown pages of MkDocs!\n\n#### Macros in Wiki engines\n> **The idea of using 'macros' to speed up the process of writing web pages\nis in fact rather old**.\n\nMost wiki engines,\nwhich also rely on some [markup](http://wiki.c2.com/?MarkupLanguage)\nlanguage, had the same problems of enriching the presentation of the pages,\nat the turn of the year 2000.\nIn response, they often implemented macros in one form or another\n(in mediawiki, they were confusingly called [templates](https://www.mediawiki.org/wiki/Help:Templates)).\nAnd in many cases, these wiki engines relied on the double-curly-braces syntax.\n\nAfter all, a **static website generator** can be defined as a wiki whose\nonline editing features have been removed, to make it \"wiki-wikier\"!\n\n\n### Use Case: Overcoming the Intrinsic Limitations of Markdown Syntax\n\n[MkDocs](https://www.mkdocs.org/) is a powerful and simple\ntool for generating websites. Pages are based on markdown, which is simple by design. The downside is that the expressiveness of markdown is\nnecessarily limited.\n\nWhat do you do if you want to enrich your web with new features like buttons,\nfancy images, etc. without messing up with templates?\n\n\n#### Solution 1: Markdown extensions\n\nIn order to express more things with it, the standard recourse is to extend\nmarkdown through standard\n[markdown extensions](https://python-markdown.github.io/extensions/).\nAdding extensions is straightforward, as they\ncan be directly activated through the `mkdocs.yml`configuration file\nof the website e.g.:\n\n```YAML\nmarkdown_extensions:\n    - footnotes\n```\n\n(If they are non-standard, you just have to install them first on your\nmachine.)\n\nThe problem is, however, that there will *always* be *something* specific\nyou will want to do, for which there is no markdown extension available.\nOr the extension will be too complicated, or not quite what you wanted.\n\nFurthermore, the are limitations to the number of possible extensions,\nbecause extending the grammar of markdown is always a little tricky and\ncan create incompabilities with the standard syntax or other extensions.\n\n#### Solution 2: Custom HTML Code\nIf don't have an extension, the standard recourse\nis to write some pure HTML within your markdown,\nwhich may also contain some\ncss code (especially if you are using css that\nis specific to your theme or website), e.g.:\n\n```HTML\nHere is my code:\n\n<a class='button' href=\"http:your.website.com/page\">Try this</a>\n```\n\nThe combination of HTML and css works well and can solve a wide range of issues.\n\nBut it will soon become tedious, if you have to type\nthe same code again and again with some variations;\nand if you want to change something to the\ncall (typically the css class), you will then have to manually change\n*all* instances of that code, with all the related risks.\nThis solution doesn't scale.\n\n#### Solution 3: Enter Macros\nWhat if you had a **macro** instead, that would allow you to write\nthe above HTML as:\n\n```\n{{button('Try this', 'http:your.website.com/page')}}\n```\n\n... that call was translated into the proper HTML?\n\n**That would be something you could teach to a person who can\nalready write markdown, without the need for them to get involved\nin *any* css or HTML!**\n\nAnd, what's more,\nyou could *easily* (as a programmer) write your own new macro in Python,\n whenever you needed one?\n\nA **macro** is, simply stated, a *Python function* that takes a few arguments\nand returns a string. It could contain all the logic you want; it could\nbe as simple as the example above, or as sophisticated as making a query from\na database and formatting the results as markdown.\n\nAll of this becomes possible, thanks to **mkdocs-macros-plugin**!\n\n\n\n\n\n\n## Installation\n\n### Prerequisites\n\n  - Python version > 3.5\n  - MkDocs version > 0.17 (compatible with post 1.0 versions)\n\n### Standard installation\n```\npip install mkdocs-macros-plugin\n```\n\n### \"Manual installation\"\nTo install the package, download it and run:\n\n```python\npython setup.py install\n```\n\n### Declaration of plugin\nDeclare the plugin in the the file `mkdocs.yml`:\n\n```yaml\nplugins:\n    - search\n    - macros\n```\n\n> **Note:** If you have no `plugins` entry in your config file yet,\nyou should also add the `search` plugin.\nIf no `plugins` entry is set, MkDocs enables `search` by default; but\nif you use it, then you have to declare it explicitly.\n\n\n## How to use it\n\n\n\n### Defining variables in the configuration file\n\nTo easily and quickly define custom variables, declare them in you `mkdocs.yml`\nfile:\n\n```yaml\nextra:\n    price: 12.50\n    company:\n        name: Acme\n        address: ....\n        website: www.acme.com\n```\n\nIn your markdown file:\n\n```markdown\nThe price of the product is {{ price }}.\n\nSee [more information on the website]({{ company.website }}).\n\nSee <a href=\"{{ company.website }}\">more information on the website</a>.\n```\n\n\n\n### Defining variables and macros in Python code\n\n### Location of the module\nPython code must go into a `main.py` file in the main website's directory\n(beside the `mkdocs.yml` file).\n\n>In can also be a package (i.e. a `main` directory),\nas long as the `declare_variables` function is accessible.\n\nIf you wish, you can change the name of that module by adding a\n`python_module` parameter to the `mkdocs.yml` file\n(no need to add the `.py` suffix):\n\n```yaml\npython_module: source_code\n```\n\n\n### Content of the module\nAs a first step, you need declare a hook function\ncalled `declare_variables`, with two arguments:\n\n   - `variables`: the dictionary that will contain your variables.\n   - `macro`: a decorator function that you can use to declare a Python\nfunction as a Jinja2 callable ('macro' for MkDocs).\n\n\n\nThe example should be self-explanatory:\n\n```python\ndef declare_variables(variables, macro):\n    \"\"\"\n    This is the hook for the functions\n\n    - variables: the dictionary that contains the variables\n    - macro: a decorator function, to declare a macro.\n    \"\"\"\n\n    variables['baz'] = \"John Doe\"\n\n    @macro\n    def bar(x):\n        return (2.3 * x) + 7\n\n\n\n    # If you wish, you can  declare a macro with a different name:\n    def f(x):\n        return x * x\n\n    macro(f, 'barbaz')\n\n    # or to export some predefined function\n    import math\n    macro(math.floor) # will be exported as 'floor'\n\n```\n\nHere is the code for the `button` function:\n\n```\n@macro\ndef button(label, url):\n    \"Add a button\"\n    url = fix_url(url)\n    HTML = \"\"\"<a class='button' href=\"%s\">%s</a>\"\"\"\n    return HTML % (url, label)\n```\n\n\nYour **registration** of variables or macros for MkDocs\nshould be done inside that\nhook function. On the other hand, nothing prevents you from making imports or\ndeclarations **outside** of this function.\n\n> **Note:** You can export a wide range of objects, and their attributes\nremain accessible (see [more information](http://jinja.pocoo.org/docs/2.10/templates/#variables))\n\n\n\n\n### Defining local variables and macros within the markdown page\n\nIf you really need a variable or macro that needs to remain **local**\nto the markdown page,\nyou can use a standard Jinja2 declaration.\n\n#### Variables\nVariables can be defined with the `set` keyword, e.g.:\n\n```jinja2\n{% set acme = 'Acme Company Ltd' %}\n\nPlease buy the great products from {{ acme }}!\n```\n\n#### Macros and other templating tools\n> In fact, you can do\n[all the fancy footwork you want with Jinja2](http://jinja.pocoo.org/docs/2.10/templates/),\nincluding defining pure Jina2 macros, conditionals and for loops!\n\nHere is an example of macro, from the official Jinja2 documentation:\n\n```jinja2\n{% macro input(name, value='', type='text', size=20) -%}\n    <input type=\"{{ type }}\" name=\"{{ name }}\" value=\"{{\n        value|e }}\" size=\"{{ size }}\">\n{%- endmacro %}\n```\n\nWhich can be called (within the page) as:\n\n```jinja2\n<p>{{ input('username') }}</p>\n<p>{{ input('password', type='password') }}</p>\n```\n\n\n> Only remember that you don't need to define any header, footer or navigation,\nas this is already taken care of by MkDocs.\nAlso, all definitions will remain **local** to the page.\n",
        "description_content_type": "",
        "docs_url": null,
        "download_url": "",
        "downloads": {
            "last_day": -1,
            "last_month": -1,
            "last_week": -1
        },
        "home_page": "https://github.com/fralau/mkdocs_macros_plugin",
        "keywords": "mkdocs python markdown macros",
        "license": "MIT",
        "maintainer": "",
        "maintainer_email": "",
        "name": "mkdocs-macros-plugin",
        "package_url": "https://pypi.org/project/mkdocs-macros-plugin/",
        "platform": "",
        "project_url": "https://pypi.org/project/mkdocs-macros-plugin/",
        "project_urls": {
            "Homepage": "https://github.com/fralau/mkdocs_macros_plugin"
        },
        "release_url": "https://pypi.org/project/mkdocs-macros-plugin/0.2.4/",
        "requires_dist": null,
        "requires_python": "",
        "summary": "Unleash the power of MkDocs with macros and variables",
        "version": "0.2.4"
    },
    "last_serial": 4261667,
    "releases": {
        "0.1.1": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "a5d9af5a61669d9d29ca22020d7ac38e",
                    "sha256": "36a3daeece67128e10a7034bc00d6d70ace5dd0a8593f299bfe8d4ea91478c35"
                },
                "downloads": -1,
                "filename": "mkdocs-macros-plugin-0.1.1.tar.gz",
                "has_sig": false,
                "md5_digest": "a5d9af5a61669d9d29ca22020d7ac38e",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 10625,
                "upload_time": "2018-09-11T13:44:39",
                "url": "https://files.pythonhosted.org/packages/d8/c2/24aa588d6dcc1e7dc9cce2b93e996022f79d93e209080a76b70001efdad4/mkdocs-macros-plugin-0.1.1.tar.gz"
            }
        ],
        "0.2.3": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "e869839065d63cf061579ad439c8e9ab",
                    "sha256": "cd4cbbc7776b6d5c5f938e0bf022fa2912b44e239bcf5022b5a9c6829ec83f43"
                },
                "downloads": -1,
                "filename": "mkdocs-macros-plugin-0.2.3.tar.gz",
                "has_sig": false,
                "md5_digest": "e869839065d63cf061579ad439c8e9ab",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 10768,
                "upload_time": "2018-09-11T14:56:45",
                "url": "https://files.pythonhosted.org/packages/11/4b/2f3e0927b063568ab4a6741dc5513951fd28dbe77a8ce8745123ff7bc847/mkdocs-macros-plugin-0.2.3.tar.gz"
            }
        ],
        "0.2.4": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "3749900f3a9b5233439c149d7975135a",
                    "sha256": "0574afaa3c7ca2c5428314743cb963a7f49698387cb709b04b85500370d87cef"
                },
                "downloads": -1,
                "filename": "mkdocs-macros-plugin-0.2.4.tar.gz",
                "has_sig": false,
                "md5_digest": "3749900f3a9b5233439c149d7975135a",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 10766,
                "upload_time": "2018-09-11T15:02:54",
                "url": "https://files.pythonhosted.org/packages/c2/d0/3d75fdb990591cc810dd7c9e10d321648c3da25309da97b018bcf07a864a/mkdocs-macros-plugin-0.2.4.tar.gz"
            }
        ]
    },
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "3749900f3a9b5233439c149d7975135a",
                "sha256": "0574afaa3c7ca2c5428314743cb963a7f49698387cb709b04b85500370d87cef"
            },
            "downloads": -1,
            "filename": "mkdocs-macros-plugin-0.2.4.tar.gz",
            "has_sig": false,
            "md5_digest": "3749900f3a9b5233439c149d7975135a",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": null,
            "size": 10766,
            "upload_time": "2018-09-11T15:02:54",
            "url": "https://files.pythonhosted.org/packages/c2/d0/3d75fdb990591cc810dd7c9e10d321648c3da25309da97b018bcf07a864a/mkdocs-macros-plugin-0.2.4.tar.gz"
        }
    ]
}