mkdocs: add mkdocs-macros-plugin

bd808 · bd808 · commit a2f95f36bf8b · 2021-11-01T17:08:35.000-06:00
Add the macros plugin which enables using jinja2 in markdown source
files and provides hooks to inject variables, macros, and filters into
the jinja2 rendering context.

This plugin is injected into the mkdocs plugin list before mdpo which
means that mdpo sees the output of macros when collecting translation
units from the English source. This will allow us to use macros to
generate translation units, but comes with a side effect that some
output may break mdpo. A really easy example of this is that adding
a `{{ macros_info() }}` block produces output which causes mdpo's
initialization code to fall into a recursion loop which eventually
crashes mkdocs.
diff --git a/macros/__init__.py b/macros/__init__.py
@@ -0,0 +1,24 @@
+# Copyright (c) 2021 Wikimedia Foundation and contributors.
+# All Rights Reserved.
+#
+# This file is part of Wikimedia Developer Portal.
+#
+# Wikimedia Developer Portal is free software: you can redistribute it and/or
+# modify it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or (at your
+# option) any later version.
+#
+# Wikimedia Developer Portal is distributed in the hope that it will be
+# useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
+# Public License for more details.
+#
+# You should have received a copy of the GNU General Public License along with
+# Wikimedia Developer Portal.  If not, see <http://www.gnu.org/licenses/>.
+
+def define_env(env):
+    """Setup local variables, macros, and filters for mkdocs-macros-plugin."""
+
+    @env.macro
+    def say_hello(s):
+        return "Hello {}".format(s)
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -57,6 +57,7 @@ markdown_extensions:
 plugins:
   - search:
       lang: en
+  - macros
   - mdpo:
       locale_dir: locale
       lc_messages: true
diff --git a/poetry.lock b/poetry.lock
diff --git a/pyproject.toml b/pyproject.toml
@@ -12,6 +12,7 @@ python = "^3.7"
 mkdocs = "^1.2.3"
 mkdocs-mdpo-plugin = "^0.0.16"
 mkdocs-material = "^7.3.4"
+mkdocs-macros-plugin = "^0.6.0"
 
 [tool.poetry.dev-dependencies]
 
