mkdocs-macros 1.5.0: modules, hidden delimiters, strict builds (2026-11-01)
Question: can one Markdown file read as plain Markdown on GitHub (macros hidden in HTML comments) while the MkDocs
site renders the macros from a Python module that imports repo packages (reactions.director), and fail the build
on any macro error?
Sources: mkdocs-macros-plugin source at tag v1.5.0 (MP/ = https://github.com/fralau/mkdocs-macros-plugin/blob/v1.5.0/,
commit 0536f4d), its docs (RTD/ = https://mkdocs-macros-plugin.readthedocs.io/en/latest/, built from MP/webdoc/docs/),
Jinja 3.1.6 source (J/ = https://github.com/pallets/jinja/blob/3.1.6/src/jinja2/) and API docs
(https://jinja.palletsprojects.com/en/stable/api/), PyPI JSON, and test builds in a scratch venv (mkdocs 1.6.1,
mkdocs-macros-plugin 1.5.0, Jinja 3.1.6, mkdocs-same-dir 0.1.5, Python 3.12), all read or run 2026-11-01.
Answers
Section titled “Answers”- A
main.pybesidemkdocs.ymlwithdefine_env(env); resolved against the config file’s dir, notdocs_dir. The project root is not put onsys.pathfor amain.pyfile: under themkdocsconsole scriptimport reactions.directorfails, and the plugin swallows that ImportError as “No default modulemainfound” (open issue #285). Fix:sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))at the top ofmain.py(or runpython -m mkdocs, or install the package). j2_block_start_string,j2_block_end_string,j2_variable_start_string,j2_variable_end_string(since 0.4.0, 2020),j2_comment_start_string,j2_comment_end_string(released in 1.2.0; the docs say 1.0.7).<!--{%/%}-->,<!--{{/}}-->,<!--{#/#}-->work (tested). Jinja only requires the three start strings to differ.- Default is lax: a macro error renders an error page and logs a WARNING;
--strictturns that into “Aborted with 1 warnings” (exit 1).on_error_fail: trueexits 100 on its own. But the defaulton_undefined: keepprints an undefined variable as{{ name }}with no warning, so--strictpasses; seton_undefined: strict. render_by_default: true(default) renders every page;render_macros: falsein front matter always wins; withrender_by_default: falseonly pages withrender_macros: true(orforce_render_paths) render.- Yes: the whole page source is one Jinja template, fenced code included. With default delimiters
${{ secrets.X }}fails the page ('secrets' is undefined). With the<!--{{delimiters it passes through untouched. - No ordering issue: macros, search and same-dir share no event. same-dir 0.1.5 now depends on
properdocsand pinsmkdocs<=1.6.1; withdocs_dir: .it copies non-Markdown files in subfolders (e.g.reactions/*.py) into the site.
Findings
Section titled “Findings”-
Module loading. Options
module_name(defaultmain) andmodules(installed “pluglets”) (MP/mkdocs_macros/plugin.py#L119-L155; RTD/#configuration-of-the-plugin). The module is looked up inproject_dir= dirname ofconfig_file_path(MP/mkdocs_macros/plugin.py#L243-L247); “a path relative to the directory of the config file” is allowed, e.g.module_name: include/source_code(RTD/macros/#local-module). A.pyfile is loaded withspec_from_file_location+exec_module, with nosys.pathchange; only a package directory inserts its parent dir intosys.path(MP/mkdocs_macros/util.py#L173-L206, changed in 1.5.0 for #278, MP/CHANGELOG.md#L7-L9). The plugin callsmodule.define_env(env)(plus optionalon_pre_page_macros,on_post_page_macros,on_post_build), and raises NameError if none exist (MP/mkdocs_macros/plugin.py#L498-L557). Indefine_env,env.variables['x'] = ...(orenv.variables.x) and the@env.macro/@env.filterdecorators register names (RTD/macros/#the-define_env-function). Modules load last inon_config, afterextra:andinclude_yaml, so they win (MP/mkdocs_macros/plugin.py#L742-L781). -
The swallowed import error.
_load_moduleswraps the import anddefine_envcall inexcept ImportError; for the default namemainit only logs INFO “No default modulemainfound” and carries on (MP/mkdocs_macros/plugin.py#L584-L599). A ModuleNotFoundError raised bymain.pyitself hits that branch. Open issue: https://github.com/fralau/mkdocs-macros-plugin/issues/285 (2026-04-09). Reproduced:mkdocs buildfrom the project dir printedsys.path[0]= the venv’sbin, the INFO line, then failed only later on'table' is undefined. Python puts the script’s dir first onsys.path, or the cwd for-m module(https://docs.python.org/3/library/sys_path_init.html), sopython -m mkdocs buildfrom the repo root imported it. Thesys.path.insertat the top ofmain.pyworked under both (__file__is set byspec_from_file_location). -
Delimiter options. Every non-empty
j2_*option is passed tojinja2.Environmentwith the prefix stripped (MP/mkdocs_macros/plugin.py#L828-L846). Docs: RTD/rendering/#solution-5-altering-the-syntax-of-jinja2-for-mkdocs-macros (“New in 1.0.7: parametersj2_comment_start_stringandj2_comment_end_string”; the maintainers warn they will not help with custom markers). History: block/variable markers in commit ac912e0 (2020-02-22), first tag v0.4.0; comment markers in #208 (2024-02-17), first tag v1.2.0 and listed under 1.2.0 in MP/CHANGELOG.md#L29-L37. Conflict: the docs say 1.0.7, the changelog and tags say 1.2.0; either way 1.5.0 has them.j2_extensionsis new in 1.4.1 (MP/CHANGELOG.md#L11-L13). -
Jinja constraints.
_environment_config_checkassertsblock_start_string != variable_start_string != comment_start_string(J/environment.py#L126-L141). As written it checks block≠variable and variable≠comment, not block≠comment. The lexer orders the start tokens by length, longest first (J/lexer.py#L213-L245), so a shared<!--{prefix is fine. Parameter list: https://jinja.palletsprojects.com/en/stable/api/#jinja2.Environment. -
Hidden-delimiter test (passed
--strict). With the six<!--{…/…}-->options:Value: <!--{{ table.stop }}-->→Value: nod;<!--{# hidden #}-->→ nothing; a<!--{% for k, v in table.items() %}-->…<!--{% endfor %}-->list rendered; a fence containing${{ secrets.X }},{{ not_jinja }}and{% raw %}came out verbatim; a plain<!-- note -->stayed a comment. GitHub hides HTML comments (https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#hiding-content-with-comments). Caveat (inferred from the GFM spec, not tested on github.com): a line that starts with<!--opens an HTML block that runs to the line containing-->(https://github.github.com/gfm/#html-blocks, condition 2). So on GitHub, Markdown after a macro at the start of a line (<!--{{ x }}--> **bold**) is passed through as raw HTML, and**bold**is not rendered. Keep macros mid-line or alone on their line. MkDocs is unaffected (the comment is gone before Markdown runs; tested). On GitHub the value is simply missing, so the sentence has to read without it. -
Error behaviour (
render, MP/mkdocs_macros/plugin.py#L697-L718). Any exception during rendering is formatted into an error page (MP/mkdocs_macros/errors.py#L10-L25) and logged at WARNING through themkdocs.plugins.*logger (MP/mkdocs_macros/util.py#L33, #L67-L86), which MkDocs--strictcounts. Withon_error_fail: trueit callsexit(100)(ERROR_MACRO). Docs: RTD/troubleshooting/#instructing-mkdocs-macros-to-fail-in-case-of-error, RTD/troubleshooting/#instructing-mkdocs-to-fail-in-case-of-any-warning, RTD/advanced/ (“From version 1.1.2”). Test results (exit code):page defaults --stricton_error_failmacro raises 0, error page, 1 WARNING 1, “Aborted with 1 warnings in strict mode!” 100 Jinja syntax error 0, error page 1 100 (same path) undefined nope0, prints {{ nope }}, no warning0 0 undefined nope.x0, error page 1 100 undefined nope,on_undefined: strict0, error page 1 100 -
on_undefinedmapskeep→DebugUndefined (default),silent→Undefined,strict→StrictUndefined,lax→LaxUndefined (MP/mkdocs_macros/plugin.py#L67-L81, #L828-L832; RTD/troubleshooting/#what-happens-if-a-variable-is-undefined). DebugUndefined prints a hard-coded{{ name }}whatever the custom delimiters (J/runtime.py#L1007-L1036), so with<!--{{delimiters a typo shows up on the site as literal{{ name }}.silentgives a blank, also without a warning (tested). For CI:on_undefined: strictplus--strictoron_error_fail: true. -
Opt-in/opt-out.
render_by_default(bool, default true) (MP/mkdocs_macros/plugin.py#L128). Inrender: front matterrender_macros: falsereturns the page unrendered before anything else, even when forced. Ifrender_by_defaultis false, a page renders only withrender_macros: trueor aforce_render_pathsmatch (gitwildmatch, relative to docs_dir). The front-matter values also become template variables (MP/mkdocs_macros/plugin.py#L664-L693). The oldignore_macrosfront-matter key raises ValueError (RTD/rendering/#solution-1-opt-out-exclude-one-page-from-the-rendering-process, #solution-2-opt-in-specify-which-pages-must-be-rendered). -
Whole page, code fences included.
on_page_markdownrenders the full Markdown source string as one template; the page title is rendered too if it contains a start marker (MP/mkdocs_macros/plugin.py#L935-L980). The docs say it outright: fencing “will not prevent their interpretation, because this macros plugin intentionally ignores them” (RTD/rendering/#two-cautions). Test with default delimiters: a fenced${{ secrets.X }}→UndefinedError: 'secrets' is undefined, WARNING,--strictexit 1. A fenced${{ github.ref }}without--strict→ exit 0 with an error page shipped. Escapes are{% raw %},render_macros: false, or other delimiters (RTD/rendering/#solutions). -
Plugin order. MkDocs calls each event in
plugins:order unless a plugin setsevent_priority(https://github.com/mkdocs/mkdocs/blob/1.6.1/docs/dev-guide/plugins.md, “Event Priorities”); none of the three sets one. Macros uses on_config, on_pre_build, on_nav, on_serve, on_page_markdown, on_post_build; same-dir onlyon_filesplus a monkeypatch ofDir.post_validationin__init__; search uses on_config, on_pre_build, on_page_context, on_post_build (mkdocs/contrib/search/init.py#L65-L95). Search indexes the rendered page, so it sees macro output. Tested withdocs_dir: .,- search,- same-dir,- macrosin both orders: identical sites,README.md→index.htmlwith macros rendered,v=nodinsearch_index.json. RTD/#declaration-of-the-macros-plugin: listsearchexplicitly onceplugins:exists. No macros or same-dir issue mentions the other (GitHub issue search). -
same-dir 0.1.5 side notes (https://github.com/oprypin/mkdocs-same-dir, PyPI). It requires
mkdocs<=1.6.1,>=1.2andproperdocs>=1.6.5(released 2026-04-17). Run from themkdocsexecutable, it prints a stderr banner “MkDocs may break support for all existing plugins…”, silenced byDISABLE_MKDOCS_2_WARNING=true; that banner did not count as a--strictwarning. Itson_filesdrops non-Markdown files at the docs root (somain.pyis not published) but keeps everything in subfolders: the test site shippedreactions/__init__.pyandreactions/director.py. Use MkDocsexclude_docsfor code folders. -
Release. PyPI
mkdocs-macros-pluginlatest is 1.5.0, uploaded 2025-11-13T08:08:53Z; 1.5.0’s only fix is package import outside the source dir (#278) (https://pypi.org/pypi/mkdocs-macros-plugin/json; MP/CHANGELOG.md#L7-L9).
noggin v0.2.26-6-g09bf9b7 · 09bf9b7