From 5ca40eb9ae951dc40538b688d2b355a84396d7cf Mon Sep 17 00:00:00 2001 From: "dependabot-preview[bot]" <27856297+dependabot-preview[bot]@users.noreply.github.com> Date: Mon, 14 Sep 2020 08:13:26 +0000 Subject: [PATCH 1/7] Bump css-loader from 4.2.2 to 4.3.0 Bumps [css-loader](https://github.com/webpack-contrib/css-loader) from 4.2.2 to 4.3.0. - [Release notes](https://github.com/webpack-contrib/css-loader/releases) - [Changelog](https://github.com/webpack-contrib/css-loader/blob/master/CHANGELOG.md) - [Commits](https://github.com/webpack-contrib/css-loader/compare/v4.2.2...v4.3.0) Signed-off-by: dependabot-preview[bot] --- package-lock.json | 38 +++++++++++++++++++++++++------------- package.json | 2 +- 2 files changed, 26 insertions(+), 14 deletions(-) diff --git a/package-lock.json b/package-lock.json index c77e81cad..df0c76669 100644 --- a/package-lock.json +++ b/package-lock.json @@ -2581,9 +2581,9 @@ } }, "css-loader": { - "version": "4.2.2", - "resolved": "https://registry.npmjs.org/css-loader/-/css-loader-4.2.2.tgz", - "integrity": "sha512-omVGsTkZPVwVRpckeUnLshPp12KsmMSLqYxs12+RzM9jRR5Y+Idn/tBffjXRvOE+qW7if24cuceFJqYR5FmGBg==", + "version": "4.3.0", + "resolved": "https://registry.npmjs.org/css-loader/-/css-loader-4.3.0.tgz", + "integrity": "sha512-rdezjCjScIrsL8BSYszgT4s476IcNKt6yX69t0pHjJVnPUTDpn4WfIpDQTN3wCJvUvfsz/mFjuGOekf3PY3NUg==", "dev": true, "requires": { "camelcase": "^6.0.0", @@ -2596,14 +2596,20 @@ "postcss-modules-scope": "^2.2.0", "postcss-modules-values": "^3.0.0", "postcss-value-parser": "^4.1.0", - "schema-utils": "^2.7.0", + "schema-utils": "^2.7.1", "semver": "^7.3.2" }, "dependencies": { + "@types/json-schema": { + "version": "7.0.6", + "resolved": "https://registry.npmjs.org/@types/json-schema/-/json-schema-7.0.6.tgz", + "integrity": "sha512-3c+yGKvVP5Y9TYBEibGNR+kLtijnj7mYrXRg+WpFb2X9xm04g/DXYkfg4hmzJQosc9snFNUPkbYIhu+KAm6jJw==", + "dev": true + }, "ajv": { - "version": "6.12.4", - "resolved": "https://registry.npmjs.org/ajv/-/ajv-6.12.4.tgz", - "integrity": "sha512-eienB2c9qVQs2KWexhkrdMLVDoIQCz5KSeLxwg9Lzk4DOfBtIK9PQwwufcsn1jjGuf9WZmqPMbGxOzfcuphJCQ==", + "version": "6.12.5", + "resolved": "https://registry.npmjs.org/ajv/-/ajv-6.12.5.tgz", + "integrity": "sha512-lRF8RORchjpKG50/WFf8xmg7sgCLFiYNNnqdKflk63whMQcWR5ngGjiSXkL9bjxy6B2npOK2HSMN49jEBMSkag==", "dev": true, "requires": { "fast-deep-equal": "^3.1.1", @@ -2612,6 +2618,12 @@ "uri-js": "^4.2.2" } }, + "ajv-keywords": { + "version": "3.5.2", + "resolved": "https://registry.npmjs.org/ajv-keywords/-/ajv-keywords-3.5.2.tgz", + "integrity": "sha512-5p6WTN0DdTGVQk6VjcEju19IgaHudalcfabD7yhDGeA6bcQnmL+CpveLJq/3hvfwd1aof6L386Ougkx6RfyMIQ==", + "dev": true + }, "camelcase": { "version": "6.0.0", "resolved": "https://registry.npmjs.org/camelcase/-/camelcase-6.0.0.tgz", @@ -2656,14 +2668,14 @@ "dev": true }, "schema-utils": { - "version": "2.7.0", - "resolved": "https://registry.npmjs.org/schema-utils/-/schema-utils-2.7.0.tgz", - "integrity": "sha512-0ilKFI6QQF5nxDZLFn2dMjvc4hjg/Wkg7rHd3jK6/A4a1Hl9VFdQWvgB1UMGoU94pad1P/8N7fMcEnLnSiju8A==", + "version": "2.7.1", + "resolved": "https://registry.npmjs.org/schema-utils/-/schema-utils-2.7.1.tgz", + "integrity": "sha512-SHiNtMOUGWBQJwzISiVYKu82GiV4QYGePp3odlY1tuKO7gPtphAT5R/py0fA6xtbgLL/RvtJZnU9b8s0F1q0Xg==", "dev": true, "requires": { - "@types/json-schema": "^7.0.4", - "ajv": "^6.12.2", - "ajv-keywords": "^3.4.1" + "@types/json-schema": "^7.0.5", + "ajv": "^6.12.4", + "ajv-keywords": "^3.5.2" } }, "semver": { diff --git a/package.json b/package.json index bf3be142a..5281e8f12 100644 --- a/package.json +++ b/package.json @@ -59,7 +59,7 @@ "@types/webpack-assets-manifest": "^3.0.1", "autoprefixer": "9.8.6", "copy-webpack-plugin": "^6.1.0", - "css-loader": "^4.2.2", + "css-loader": "^4.3.0", "event-hooks-webpack-plugin": "^2.1.7", "expose-loader": "^1.0.0", "github-types": "^1.0.0", From 556ebe8d579701a19a34b10a438fbe64b31b7890 Mon Sep 17 00:00:00 2001 From: "dependabot-preview[bot]" <27856297+dependabot-preview[bot]@users.noreply.github.com> Date: Mon, 14 Sep 2020 08:14:03 +0000 Subject: [PATCH 2/7] Bump @primer/octicons from 10.1.0 to 11.0.0 Bumps [@primer/octicons](https://github.com/primer/octicons) from 10.1.0 to 11.0.0. - [Release notes](https://github.com/primer/octicons/releases) - [Changelog](https://github.com/primer/octicons/blob/master/CHANGELOG.md) - [Commits](https://github.com/primer/octicons/compare/v10.1.0...v11.0.0) Signed-off-by: dependabot-preview[bot] --- package-lock.json | 6 +++--- package.json | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/package-lock.json b/package-lock.json index df0c76669..21a8b37c8 100644 --- a/package-lock.json +++ b/package-lock.json @@ -306,9 +306,9 @@ } }, "@primer/octicons": { - "version": "10.1.0", - "resolved": "https://registry.npmjs.org/@primer/octicons/-/octicons-10.1.0.tgz", - "integrity": "sha512-oXfV0uIe7I4cb3vUzBPlPZGL5SQ3+joyyRcmk28aJiGFySl8brzL0MJC63RahiNEnIFrL3D5BRVgz5ZGGuHCOg==", + "version": "11.0.0", + "resolved": "https://registry.npmjs.org/@primer/octicons/-/octicons-11.0.0.tgz", + "integrity": "sha512-aMM2n7dl4ToEqQH9ZWQ8M8alGCoGsRk2k5hT5h3KXd54YFKte1twhJDvyQjIjjxqggNh5NUfyuqTOv6MPCVSKQ==", "dev": true, "requires": { "object-assign": "^4.1.1" diff --git a/package.json b/package.json index 5281e8f12..cea48a0b8 100644 --- a/package.json +++ b/package.json @@ -44,7 +44,7 @@ "devDependencies": { "@fortawesome/fontawesome-free": "^5.14.0", "@mdi/svg": "^5.5.55", - "@primer/octicons": "^10.1.0", + "@primer/octicons": "^11.0.0", "@types/clipboard": "^2.0.1", "@types/copy-webpack-plugin": "^6.0.0", "@types/escape-html": "1.0.0", From 51993e529f64e946ffefff02658569b811870911 Mon Sep 17 00:00:00 2001 From: "dependabot-preview[bot]" <27856297+dependabot-preview[bot]@users.noreply.github.com> Date: Mon, 14 Sep 2020 08:14:39 +0000 Subject: [PATCH 3/7] Bump stylelint from 13.7.0 to 13.7.1 Bumps [stylelint](https://github.com/stylelint/stylelint) from 13.7.0 to 13.7.1. - [Release notes](https://github.com/stylelint/stylelint/releases) - [Changelog](https://github.com/stylelint/stylelint/blob/master/CHANGELOG.md) - [Commits](https://github.com/stylelint/stylelint/compare/13.7.0...13.7.1) Signed-off-by: dependabot-preview[bot] --- package-lock.json | 12 ++++++------ package.json | 2 +- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/package-lock.json b/package-lock.json index 21a8b37c8..0bb891b0d 100644 --- a/package-lock.json +++ b/package-lock.json @@ -9027,9 +9027,9 @@ "dev": true }, "stylelint": { - "version": "13.7.0", - "resolved": "https://registry.npmjs.org/stylelint/-/stylelint-13.7.0.tgz", - "integrity": "sha512-1wStd4zVetnlHO98VjcHQbjSDmvcA39smkZQMct2cf+hom40H0xlQNdzzbswoG/jGBh61/Ue9m7Lu99PY51O6A==", + "version": "13.7.1", + "resolved": "https://registry.npmjs.org/stylelint/-/stylelint-13.7.1.tgz", + "integrity": "sha512-qzqazcyRxrSRdmFuO0/SZOJ+LyCxYy0pwcvaOBBnl8/2VfHSMrtNIE+AnyJoyq6uKb+mt+hlgmVrvVi6G6XHfQ==", "dev": true, "requires": { "@stylelint/postcss-css-in-js": "^0.37.2", @@ -9083,9 +9083,9 @@ }, "dependencies": { "ajv": { - "version": "6.12.4", - "resolved": "https://registry.npmjs.org/ajv/-/ajv-6.12.4.tgz", - "integrity": "sha512-eienB2c9qVQs2KWexhkrdMLVDoIQCz5KSeLxwg9Lzk4DOfBtIK9PQwwufcsn1jjGuf9WZmqPMbGxOzfcuphJCQ==", + "version": "6.12.5", + "resolved": "https://registry.npmjs.org/ajv/-/ajv-6.12.5.tgz", + "integrity": "sha512-lRF8RORchjpKG50/WFf8xmg7sgCLFiYNNnqdKflk63whMQcWR5ngGjiSXkL9bjxy6B2npOK2HSMN49jEBMSkag==", "dev": true, "requires": { "fast-deep-equal": "^3.1.1", diff --git a/package.json b/package.json index cea48a0b8..662a191a1 100644 --- a/package.json +++ b/package.json @@ -77,7 +77,7 @@ "rimraf": "^3.0.2", "sass": "^1.26.10", "sass-loader": "^10.0.2", - "stylelint": "^13.7.0", + "stylelint": "^13.7.1", "stylelint-config-rational-order": "^0.1.2", "stylelint-config-standard": "^20.0.0", "stylelint-order": "^4.1.0", From c1f59cf2bab240a23f219dcd28522c606f5c80fe Mon Sep 17 00:00:00 2001 From: "dependabot-preview[bot]" <27856297+dependabot-preview[bot]@users.noreply.github.com> Date: Mon, 14 Sep 2020 08:15:14 +0000 Subject: [PATCH 4/7] Bump @types/node from 14.6.4 to 14.10.1 Bumps [@types/node](https://github.com/DefinitelyTyped/DefinitelyTyped/tree/HEAD/types/node) from 14.6.4 to 14.10.1. - [Release notes](https://github.com/DefinitelyTyped/DefinitelyTyped/releases) - [Commits](https://github.com/DefinitelyTyped/DefinitelyTyped/commits/HEAD/types/node) Signed-off-by: dependabot-preview[bot] --- package-lock.json | 6 +++--- package.json | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/package-lock.json b/package-lock.json index 0bb891b0d..e09db5752 100644 --- a/package-lock.json +++ b/package-lock.json @@ -505,9 +505,9 @@ "dev": true }, "@types/node": { - "version": "14.6.4", - "resolved": "https://registry.npmjs.org/@types/node/-/node-14.6.4.tgz", - "integrity": "sha512-Wk7nG1JSaMfMpoMJDKUsWYugliB2Vy55pdjLpmLixeyMi7HizW2I/9QoxsPCkXl3dO+ZOVqPumKaDUv5zJu2uQ==", + "version": "14.10.1", + "resolved": "https://registry.npmjs.org/@types/node/-/node-14.10.1.tgz", + "integrity": "sha512-aYNbO+FZ/3KGeQCEkNhHFRIzBOUgc7QvcVNKXbfnhDkSfwUv91JsQQa10rDgKSTSLkXZ1UIyPe4FJJNVgw1xWQ==", "dev": true }, "@types/normalize-package-data": { diff --git a/package.json b/package.json index 662a191a1..e8e30a702 100644 --- a/package.json +++ b/package.json @@ -52,7 +52,7 @@ "@types/html-minifier": "^4.0.0", "@types/lunr": "^2.3.3", "@types/mini-css-extract-plugin": "^0.9.1", - "@types/node": "^14.6.4", + "@types/node": "^14.10.1", "@types/ramda": "^0.27.14", "@types/resize-observer-browser": "^0.1.3", "@types/webpack": "^4.41.22", From de13197b7d11026e241c28b99ab21ed83123cafd Mon Sep 17 00:00:00 2001 From: "dependabot-preview[bot]" <27856297+dependabot-preview[bot]@users.noreply.github.com> Date: Mon, 14 Sep 2020 08:19:53 +0000 Subject: [PATCH 5/7] Bump @types/ramda from 0.27.14 to 0.27.17 Bumps [@types/ramda](https://github.com/DefinitelyTyped/DefinitelyTyped/tree/HEAD/types/ramda) from 0.27.14 to 0.27.17. - [Release notes](https://github.com/DefinitelyTyped/DefinitelyTyped/releases) - [Commits](https://github.com/DefinitelyTyped/DefinitelyTyped/commits/HEAD/types/ramda) Signed-off-by: dependabot-preview[bot] --- package-lock.json | 12 ++++++------ package.json | 2 +- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/package-lock.json b/package-lock.json index e09db5752..185c17928 100644 --- a/package-lock.json +++ b/package-lock.json @@ -529,9 +529,9 @@ "dev": true }, "@types/ramda": { - "version": "0.27.14", - "resolved": "https://registry.npmjs.org/@types/ramda/-/ramda-0.27.14.tgz", - "integrity": "sha512-vbw/VAtEJeSJ6Z61QT+epirlnBeJiJIO7ndK1BJ0fKswnfbiTNga/jBG6R3OnBaFYx+UJv6Iv7ZfWDFSsSzNqA==", + "version": "0.27.17", + "resolved": "https://registry.npmjs.org/@types/ramda/-/ramda-0.27.17.tgz", + "integrity": "sha512-AHVwr1YdFdxeabfC1g34ZuJ61dKOcfdXlG+sqGUweD+5VrD6A9emwmc2OZY+N8CdEKdwl29hwvtTMSJ6ZVVsiQ==", "dev": true, "requires": { "ts-toolbelt": "^6.3.3" @@ -10392,9 +10392,9 @@ } }, "ts-toolbelt": { - "version": "6.13.39", - "resolved": "https://registry.npmjs.org/ts-toolbelt/-/ts-toolbelt-6.13.39.tgz", - "integrity": "sha512-VD/rJ6+NGFA7AK2KWmGzLifrqA060M9o7+R2BxJtLBlwmfEaGdqGeyUPRDKhMZPMgpT/JMQ6+X+/ppaZNzuhvw==", + "version": "6.15.5", + "resolved": "https://registry.npmjs.org/ts-toolbelt/-/ts-toolbelt-6.15.5.tgz", + "integrity": "sha512-FZIXf1ksVyLcfr7M317jbB67XFJhOO1YqdTcuGaq9q5jLUoTikukZ+98TPjKiP2jC5CgmYdWWYs0s2nLSU0/1A==", "dev": true }, "tsconfig-paths": { diff --git a/package.json b/package.json index e8e30a702..795bc75e3 100644 --- a/package.json +++ b/package.json @@ -53,7 +53,7 @@ "@types/lunr": "^2.3.3", "@types/mini-css-extract-plugin": "^0.9.1", "@types/node": "^14.10.1", - "@types/ramda": "^0.27.14", + "@types/ramda": "^0.27.17", "@types/resize-observer-browser": "^0.1.3", "@types/webpack": "^4.41.22", "@types/webpack-assets-manifest": "^3.0.1", From d7c28f93195352541e444ba5f54a377ca24002fa Mon Sep 17 00:00:00 2001 From: "dependabot-preview[bot]" <27856297+dependabot-preview[bot]@users.noreply.github.com> Date: Mon, 14 Sep 2020 08:24:55 +0000 Subject: [PATCH 6/7] Bump mini-css-extract-plugin from 0.11.0 to 0.11.2 Bumps [mini-css-extract-plugin](https://github.com/webpack-contrib/mini-css-extract-plugin) from 0.11.0 to 0.11.2. - [Release notes](https://github.com/webpack-contrib/mini-css-extract-plugin/releases) - [Changelog](https://github.com/webpack-contrib/mini-css-extract-plugin/blob/master/CHANGELOG.md) - [Commits](https://github.com/webpack-contrib/mini-css-extract-plugin/compare/v0.11.0...v0.11.2) Signed-off-by: dependabot-preview[bot] --- package-lock.json | 6 +++--- package.json | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/package-lock.json b/package-lock.json index 185c17928..dfe499138 100644 --- a/package-lock.json +++ b/package-lock.json @@ -6215,9 +6215,9 @@ "dev": true }, "mini-css-extract-plugin": { - "version": "0.11.0", - "resolved": "https://registry.npmjs.org/mini-css-extract-plugin/-/mini-css-extract-plugin-0.11.0.tgz", - "integrity": "sha512-dVWGuWJlQw2lZxsxBI3hOsoxg1k3DruLR0foHQLSkQMfk+qLJbv9dUk8fjmjWQKN9ef2n54ehA2FjClAsQhrWQ==", + "version": "0.11.2", + "resolved": "https://registry.npmjs.org/mini-css-extract-plugin/-/mini-css-extract-plugin-0.11.2.tgz", + "integrity": "sha512-h2LknfX4U1kScXxH8xE9LCOqT5B+068EAj36qicMb8l4dqdJoyHcmWmpd+ueyZfgu/POvIn+teoUnTtei2ikug==", "dev": true, "requires": { "loader-utils": "^1.1.0", diff --git a/package.json b/package.json index 795bc75e3..e9b01a920 100644 --- a/package.json +++ b/package.json @@ -69,7 +69,7 @@ "imagemin-webpack-plugin": "^2.4.2", "material-design-color": "^2.3.2", "material-shadows": "^3.0.1", - "mini-css-extract-plugin": "^0.11.0", + "mini-css-extract-plugin": "^0.11.2", "postcss-inline-svg": "^4.1.0", "postcss-loader": "^3.0.0", "postcss-svgo": "^4.0.2", From 1f93e3d1064a87e5ab551c4ee0b2bcc8e6152bad Mon Sep 17 00:00:00 2001 From: Laurent Franceschetti Date: Wed, 16 Sep 2020 09:53:48 +0200 Subject: [PATCH 7/7] Add reference page for variables and macros (#1917) --- docs/reference/variables-macros.md | 332 +++++++++++++++++++++++++++++ mkdocs.yml | 1 + 2 files changed, 333 insertions(+) create mode 100644 docs/reference/variables-macros.md diff --git a/docs/reference/variables-macros.md b/docs/reference/variables-macros.md new file mode 100644 index 000000000..205224ea3 --- /dev/null +++ b/docs/reference/variables-macros.md @@ -0,0 +1,332 @@ +--- +template: overrides/main.html +--- + +# Variables and Macros + +The power of the Markdown language comes from its simplicity and +visual clarity. Its downside is that it far more limited than HTML. +That is the reason why Markdown extensions have been developed, +such as [Footnotes](../Footnotes) or [Admonition](../Admonition) +(for notes and tips). + +Sometimes, however, one wishes to add more customization +to Markdown pages, to perform tasks that are +specific to the documentation project. +This is the purpose of **variables** and **macros**, provided +by the [macros plugin](https://github.com/fralau/mkdocs_macros_plugin). + +!!! Note "Example" + + ``` + The unit price of product A is {{ unit_price }} EUR. + The sale price of {{ no }} units is {{ price(no, unit_price) }} EUR. + ``` + + If you defined a variable `no`w with a value of 50, + a variable `unit_price` with a value of 10, + and a macro `price()` (which multiplies the two), this could translate into: + + ``` + The unit price of product A is 10.00 EUR, + and the sale price of 50 units is 500.00 EUR. + ``` + + +Those who have used **wikis** engines (user-editable websites) +in the past are probably already familiar with those notions. + +!!!Tip + You may also use this + plugin to add **buttons** or other advanced functionality + (e.g. pulling data from a database) that is ordinarily + not provided by Markdown or one of its extensions. + + + +## Configuration + +The [macros plugin](https://github.com/fralau/mkdocs_macros_plugin) +makes it easier for contributors of an MkDocs website to produce richer and more beautiful pages. It enriches pages with calls to variables and macros. + + +!!! Note + This plugin has been tested to work with the **Material** theme. + It is also compatible with most other themes. + + +See the [installations instructions](https://mkdocs-macros-plugin.readthedocs.io/en/latest/#installation) for the plugin. + + +In order to make it work with your MkDocs project, +declare it in the config file: + +```yaml +plugins: + - search + - macros +``` + + +!!!Tip + The recommended way to check that the plugin works properly is to add the following line in one of the pages of your site + (typically `index.md`): + + ``` + {{ macros_info() }} + ``` + + If the plugin is properly installed, this will display + a test page with lots of information, especially predefined + variables and macros. + + +## Usage + +### Variables + +**Variables** are names with an attached value +(Markdown, HTML, ...), which can be reused anywhere in the pages. +Changing the value of the variable, will +change the text displayed, in all markdown pages +where this variable is called; this is useful for consistency. + + + +#### Predefined Variables + +With the macros plugin, a large set of predefined variables +are available out of the box, e.g. : + +Example | Description +--- | --- +`{{ config.site_name }}` | main title of the website +`{{ environment.system }}`| name of the OS +`{{ page.title }}` | title of the page +`{{ git.short_commit}} ({{ git.date}}) by {{ git.author}}` | **git information** (if applicable) + + +!!! Tip "Discoverability" + To explore the possibilities, just insert the + following code into one of the Markdown pages: + + ``` + {{ macros_info() }} + ``` + +#### Defining Variables + +All variables defined under `extra` in your config file become +available: + +```yaml +extra: + price: 12.50 + company: + name: Acme + address: .... + website: www.acme.com +``` + +This becomes available as, e.g.: + +```html +The price of the product is {{ price }}. + +See [more information on the website]({{ company.website }}). + +See more information on the website. +``` + +### Macros + +**Macros** are Python functions that return a value (Markdown, HTML...) +which depends on something else. + +A macro may have arguments, +or depend on conditions that change every time MkDocs +is run again (e.g. time or version number, etc.). + +Writing a macro is very easy: it requires only basic knowledge of Python, +and clear idea of what string result (Markdown, HTML, ...) +you want to produce. + +!!! Note + In principle the result must be a string, + but it could be _any type or class_ + as long it is translatable into a string. + + +#### Location of the Macros' Code + +By default, your macros are defined in a `main.py` file, +which is located in website's project directory +(generally beside the `mkdocs.yml` file). +You may [change that location and name](https://mkdocs-macros-plugin.readthedocs.io/en/latest/python/#location-of-the-module). + +#### Example 1: Arithmetics + +Imagine you want to calculate the cost of a batch, with +the unit price and the no of items, plus a 10% shipping costs: + +``` +This will cost {{ total_price(4, 12.50)}} dollars. +``` + +Which will be translated into: + +``` +This will cost 55 dollars. +``` + +But if `unit_price` and `quantity` have been defined under `extra`: + +```yaml +extra: + quantity: 4 + unit_price: 12.50 +``` + +``` +This will cost {{ total_price(quantity, unit_price)}} dollars. +``` + +??? Tip "Module content" + The module will look as follows: + + ```python + """ + Basic example of a Mkdocs-macros module + """ + + import math + + def define_env(env): + """ + This is the hook for defining macros + """ + + @env.macro + def total_price(quantity, unit_price): + "Calculate the price plus shipping costs + price = quantity * unit_price + shipping_costs = price * 10% + return price + shipping_costs + ``` + +#### Guidelines + +1. All you need to define is a `define_env(env)` function. + +2. To declare a Python function as a macro, just precede it by the +`@env.macro` decorator. +It will appear in the documentation produced by `{{ macros_info() }}` + +3. You may define as many macros as needed under `define_env()`. + +4. Write a macro's docstring from the viewpoint of the users who will + use it (it will be displayed in the macro's description). + +#### Example 2: Creating a Button + +This function is alternative, more flexible way to generate a button +(see [Buttons](../buttons#adding-buttons)): + +In your markdown page: + +``` +{{ button('Try this', 'https://your.website.com/page') }} +``` + +Result: + + + +[Try this](https://your.website.com/page){: .md-button } + + +??? Tip "Module content" + + In your Python module: + + ```python + def define_env(env): + """ + This is the hook for defining macros + """ + # Optional: a special function for making relative urls point to root + fix_url = env.variables.fix_url + + @env.macro + def button(label, url): + "Add a button" + url = fix_url(url) + HTML = """%s""" + return HTML % (url, label) + ``` + + + + +## Advanced Usage: Jinja2 Constructs + +The macros plugin relies on the [Jinja2](https://jinja.palletsprojects.com/en/2.11.x/templates/) template engine. + +This makes the facilities of that template engine available +within a Markdown page. + + + +!!! Note + Not that this is distinct from the standard, low-level use of Jinja2 by + MkDocs to convert the Markdown pages into HTML. + In principle this will **not** interfere with it. + +### Conditions and Loops +Most of what is described in its documentation, +including constructs such as + +- [conditions](https://jinja.palletsprojects.com/en/2.11.x/templates/#if): + `{% if ... %}` +- [loops](https://jinja.palletsprojects.com/en/2.11.x/templates/#for): + `{% for ... %} ` + + +will work out of the box. + +!!! Tip + Instead of using Jinja2 constructs to generate pure HTML + as in the examples shown, + you could use them to generate Markdown, + or whichever mix of Markdown, HTML, CSS + or even Javascript that might be required for your needs. + +### Filters + +Jinja2's [built-in filters](https://jinja.palletsprojects.com/en/2.11.x/templates/#list-of-builtin-filters) are available e.g. : + +`{{ "HELLO WORLD" | lower }}` results in `hello world` + +You may [write your own filters in the Python module](https://mkdocs-macros-plugin.readthedocs.io/en/latest/python/#defining-macros-and-filters-as-well-as-variables), +using the `@env.filter` decorator. + +### Including External Files + +Quite aside from variables and macros, you may include external files +containing snippets (typically, Markdown files). + +You may use the include directive from jinja2, directly in your markdown code e.g.: + + ## Paragraph + {% include 'snippet.md' %} + +Including another markdown file will therefore execute the macros. + +By default, the relative path for included files starts from `docs`, +but [this can be changed](https://mkdocs-macros-plugin.readthedocs.io/en/latest/advanced/#changing-the-directory-of-the-includes). + +## More Information on the Macros Plugin + +* [Main documentation page](https://mkdocs-macros-plugin.readthedocs.io/en/latest/) +* [Including git information in a page](https://mkdocs-macros-plugin.readthedocs.io/en/latest/git_info/) +* [Writing macros and filters](https://mkdocs-macros-plugin.readthedocs.io/en/latest/python/) diff --git a/mkdocs.yml b/mkdocs.yml index 8245583eb..27026050e 100755 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -178,6 +178,7 @@ nav: - Lists: reference/lists.md - MathJax: reference/mathjax.md - Meta tags: reference/meta-tags.md + - Variables and macros: reference/variables-macros.md - Changelog: - Release notes: changelog.md - Upgrading: upgrading.md