markdown-macros-extension 0.1.0__tar.gz

markdown_macros_extension-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BarCar (https://github.com/barcar)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

markdown_macros_extension-0.1.0/PKG-INFO

@@ -0,0 +1,91 @@
+Metadata-Version: 2.4
+Name: markdown-macros-extension
+Version: 0.1.0
+Summary: Python-Markdown extension: MkDocs-Macros–style Jinja2 templating (variables, macros, filters) with YAML front matter for Zensical and MkDocs
+Author: BarCar
+License: MIT
+Project-URL: Documentation, https://github.com/barcar/markdown-macros#readme
+Project-URL: Repository, https://github.com/barcar/markdown-macros
+Keywords: markdown,frontmatter,yaml,zensical,mkdocs,macros
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Text Processing :: Markup
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: markdown>=3.4
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: jinja2>=3.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: zensical; extra == "docs"
+Dynamic: license-file
+
+# Markdown Macros
+
+[![Deploy docs to GitHub Pages](https://github.com/barcar/markdown-macros/actions/workflows/pages.yml/badge.svg)](https://github.com/barcar/markdown-macros/actions/workflows/pages.yml)
+
+**Author:** [BarCar](https://github.com/barcar) · **Repository:** [github.com/barcar/markdown-macros](https://github.com/barcar/markdown-macros)
+
+A **Python-Markdown extension** that brings [MkDocs Macros](https://mkdocs-macros-plugin.readthedocs.io/)–style **Jinja2 templating** to any Markdown pipeline: variables (config + YAML front matter), **macros**, and **filters**. Works with [Zensical](https://zensical.org), MkDocs, or plain Python—without the MkDocs plugin.
+
+## Features
+
+- **Variables** from config, YAML front matter, or `include_yaml`
+- **Macros and filters** via `define_env(env)` in a Python module (same API as MkDocs Macros)
+- **YAML front matter** parsed and exposed as `md.Meta` / `md.front_matter`
+
+## Installation
+
+```bash
+pip install markdown-macros-extension
+```
+
+Requires: `markdown>=3.4`, `pyyaml>=6.0`, `jinja2>=3.0`.
+
+## Quick example
+
+```python
+import markdown
+from markdown_macros import MacrosExtension
+
+text = """---
+title: My Page
+---
+
+# {{ title }}
+
+The answer is {{ 6 * 7 }}.
+"""
+md = markdown.Markdown(extensions=[MacrosExtension()])
+html = md.convert(text)  # title and 42 rendered
+```
+
+In Zensical or MkDocs, add `markdown_macros` to your Markdown extensions and optionally set `module_name`, `variables`, `include_yaml`, etc. See the [documentation](https://barcar.github.io/markdown-macros/) for configuration, usage, and the full API.
+
+**Compatibility:** API-aligned with the [MkDocs Macros plugin](https://mkdocs-macros-plugin.readthedocs.io/) (variables, macros, filters, `define_env`); see [Compatibility](https://barcar.github.io/markdown-macros/compatibility/) in the docs.
+
+## Documentation
+
+**Online:** [Documentation](https://barcar.github.io/markdown-macros/) (GitHub Pages).
+
+To build the docs locally:
+
+```bash
+pip install -e ".[docs]"
+zensical serve
+```
+
+## License
+
+MIT License. See [LICENSE](LICENSE).

markdown_macros_extension-0.1.0/README.md

@@ -0,0 +1,58 @@
+# Markdown Macros
+
+[![Deploy docs to GitHub Pages](https://github.com/barcar/markdown-macros/actions/workflows/pages.yml/badge.svg)](https://github.com/barcar/markdown-macros/actions/workflows/pages.yml)
+
+**Author:** [BarCar](https://github.com/barcar) · **Repository:** [github.com/barcar/markdown-macros](https://github.com/barcar/markdown-macros)
+
+A **Python-Markdown extension** that brings [MkDocs Macros](https://mkdocs-macros-plugin.readthedocs.io/)–style **Jinja2 templating** to any Markdown pipeline: variables (config + YAML front matter), **macros**, and **filters**. Works with [Zensical](https://zensical.org), MkDocs, or plain Python—without the MkDocs plugin.
+
+## Features
+
+- **Variables** from config, YAML front matter, or `include_yaml`
+- **Macros and filters** via `define_env(env)` in a Python module (same API as MkDocs Macros)
+- **YAML front matter** parsed and exposed as `md.Meta` / `md.front_matter`
+
+## Installation
+
+```bash
+pip install markdown-macros-extension
+```
+
+Requires: `markdown>=3.4`, `pyyaml>=6.0`, `jinja2>=3.0`.
+
+## Quick example
+
+```python
+import markdown
+from markdown_macros import MacrosExtension
+
+text = """---
+title: My Page
+---
+
+# {{ title }}
+
+The answer is {{ 6 * 7 }}.
+"""
+md = markdown.Markdown(extensions=[MacrosExtension()])
+html = md.convert(text)  # title and 42 rendered
+```
+
+In Zensical or MkDocs, add `markdown_macros` to your Markdown extensions and optionally set `module_name`, `variables`, `include_yaml`, etc. See the [documentation](https://barcar.github.io/markdown-macros/) for configuration, usage, and the full API.
+
+**Compatibility:** API-aligned with the [MkDocs Macros plugin](https://mkdocs-macros-plugin.readthedocs.io/) (variables, macros, filters, `define_env`); see [Compatibility](https://barcar.github.io/markdown-macros/compatibility/) in the docs.
+
+## Documentation
+
+**Online:** [Documentation](https://barcar.github.io/markdown-macros/) (GitHub Pages).
+
+To build the docs locally:
+
+```bash
+pip install -e ".[docs]"
+zensical serve
+```
+
+## License
+
+MIT License. See [LICENSE](LICENSE).

markdown_macros_extension-0.1.0/markdown_macros/__init__.py

@@ -0,0 +1,15 @@
+"""
+Markdown Macros: MkDocs-Macros–style extension for Python-Markdown.
+
+Jinja2 templating with variables (config + YAML front matter), macros, and
+filters. Parses --- YAML --- front matter and exposes md.Meta / md.front_matter.
+Use define_env(env) in a module for macros/filters/variables.
+"""
+
+from markdown_macros.front_matter import FrontMatterExtension
+from markdown_macros.macros import MacrosExtension, make_extension
+
+# Python-Markdown discovers extensions via makeExtension (camelCase)
+makeExtension = make_extension
+
+__all__ = ["FrontMatterExtension", "MacrosExtension", "make_extension", "makeExtension"]

markdown_macros_extension-0.1.0/markdown_macros/front_matter.py

@@ -0,0 +1,106 @@
+"""
+YAML Front Matter preprocessor for Python-Markdown.
+
+Strips the leading --- YAML --- block from the source and stores parsed data
+in md.Meta (Python-Markdown style: lowercase keys, list-of-strings values)
+and md.front_matter (full parsed dict for nested structures).
+
+Compatible with Zensical and MkDocs Macros: runs only at the Markdown layer;
+no Jinja2 or plugin logic. When MkDocs Macros is used, it can consume
+page-level metadata; this extension ensures front matter is available as md.Meta
+for the rest of the pipeline.
+"""
+
+import re
+from markdown import Extension
+from markdown.preprocessors import Preprocessor
+
+try:
+    import yaml
+except ImportError:
+    yaml = None
+
+# Match --- at start of document, then content until next --- (YAML style only for now)
+FRONT_MATTER_RE = re.compile(
+    r"^---\s*\r?\n([\s\S]*?)\r?\n---\s*\r?\n",
+    re.MULTILINE,
+)
+
+
+def _meta_from_dict(data):
+    """Convert parsed YAML dict to Python-Markdown Meta format: lowercase keys, list values."""
+    meta = {}
+    if not isinstance(data, dict):
+        return meta
+    for key, value in data.items():
+        k = key.lower().strip()
+        if isinstance(value, list):
+            meta[k] = [str(v) for v in value]
+        elif value is None:
+            meta[k] = [""]
+        else:
+            meta[k] = [str(value)]
+    return meta
+
+
+class FrontMatterPreprocessor(Preprocessor):
+    """Preprocessor that strips YAML front matter and stores it on the Markdown instance."""
+
+    def __init__(self, md, config):
+        super().__init__(md)
+        self.config = config
+
+    def run(self, lines):
+        text = "\n".join(lines)
+        match = FRONT_MATTER_RE.match(text)
+        if not match:
+            # Ensure Meta and front_matter exist for downstream (e.g. themes, MkDocs)
+            if not hasattr(self.md, "Meta") or self.md.Meta is None:
+                self.md.Meta = {}
+            if not hasattr(self.md, "front_matter") or self.md.front_matter is None:
+                self.md.front_matter = {}
+            return lines
+
+        raw_block = match.group(1).strip()
+        if yaml is not None:
+            try:
+                data = yaml.safe_load(raw_block)
+                if data is None:
+                    data = {}
+                if not isinstance(data, dict):
+                    data = {"content": data}
+            except Exception:
+                data = {}
+        else:
+            data = {}
+
+        # Expose for Python-Markdown and downstream (e.g. MkDocs page.meta)
+        self.md.Meta = getattr(self.md, "Meta", None) or {}
+        self.md.Meta.update(_meta_from_dict(data))
+        # Full structure for themes/plugins that expect nested data
+        self.md.front_matter = data
+
+        # Return remaining markdown (without the front matter block)
+        rest = text[match.end() :]
+        return rest.split("\n")
+
+
+class FrontMatterExtension(Extension):
+    """Python-Markdown extension that parses YAML front matter and exposes it as md.Meta and md.front_matter."""
+
+    def __init__(self, **kwargs):
+        # No config options; declare empty config so base Extension.setConfig behaves correctly.
+        self.config = {}
+        super().__init__(**kwargs)
+
+    def extendMarkdown(self, md):
+        md.registerExtension(self)
+        md.preprocessors.register(
+            FrontMatterPreprocessor(md, self.getConfigs()),
+            "front_matter",
+            priority=25,  # Run early, before most other preprocessors (higher = first)
+        )
+
+
+def make_extension(**kwargs):
+    return FrontMatterExtension(**kwargs)

markdown_macros_extension-0.1.0/markdown_macros/macros.py

@@ -0,0 +1,323 @@
+"""
+MkDocs-Macros–style extension for Python-Markdown.
+
+Treats the document as a Jinja2 template: parses YAML front matter for
+page-level variables, merges with config variables and optional module
+(macros/filters/variables via define_env(env)), then renders the body.
+Exposes md.Meta and md.front_matter for downstream use.
+"""
+
+import importlib.util
+import logging
+import re
+from pathlib import Path
+
+from markdown import Extension
+from markdown.preprocessors import Preprocessor
+
+try:
+    import jinja2
+except ImportError:
+    jinja2 = None
+
+try:
+    import yaml
+except ImportError:
+    yaml = None
+
+logger = logging.getLogger("markdown_macros")
+
+FRONT_MATTER_RE = re.compile(
+    r"^---\s*\r?\n([\s\S]*?)\r?\n---\s*\r?\n",
+    re.MULTILINE,
+)
+
+
+def _meta_from_dict(data):
+    """Convert dict to Python-Markdown Meta: lowercase keys, list values."""
+    meta = {}
+    if not isinstance(data, dict):
+        return meta
+    for key, value in data.items():
+        k = key.lower().strip()
+        if isinstance(value, list):
+            meta[k] = [str(v) for v in value]
+        elif value is None:
+            meta[k] = [""]
+        else:
+            meta[k] = [str(value)]
+    return meta
+
+
+class MacroEnv:
+    """Minimal env object for define_env(env) compatibility with MkDocs Macros."""
+
+    def __init__(self):
+        self.variables = {}
+        self._macros = {}
+        self._filters = {}
+
+    def macro(self, fn=None, name=None):
+        """Register a macro. Use as @env.macro or env.macro(func) or env.macro(func, 'name')."""
+        if fn is None:
+            return lambda f: self.macro(f, name)
+        self._macros[name or fn.__name__] = fn
+        return fn
+
+    def filter(self, fn=None, name=None):
+        """Register a filter. Use as @env.filter or env.filter(func)."""
+        if fn is None:
+            return lambda f: self.filter(f, name)
+        self._filters[name or fn.__name__] = fn
+        return fn
+
+
+def _load_module(module_name, project_root=None):
+    """Load a module by name (e.g. 'main') and return (variables, macros, filters) from define_env."""
+    root = Path(project_root or ".").resolve()
+    for candidate in [root / f"{module_name}.py", root / module_name / "__init__.py"]:
+        if candidate.exists():
+            spec = importlib.util.spec_from_file_location(module_name, candidate)
+            if spec and spec.loader:
+                mod = importlib.util.module_from_spec(spec)
+                spec.loader.exec_module(mod)
+                if hasattr(mod, "define_env"):
+                    env = MacroEnv()
+                    mod.define_env(env)
+                    return env.variables, env._macros, env._filters
+            break
+    try:
+        mod = __import__(module_name)
+        if hasattr(mod, "define_env"):
+            env = MacroEnv()
+            mod.define_env(env)
+            return env.variables, env._macros, env._filters
+    except ImportError:
+        pass
+    return {}, {}, {}
+
+
+def _load_pluglets(module_names):
+    """Load pluglet modules by package name; return merged (variables, macros, filters)."""
+    all_vars = {}
+    all_macros = {}
+    all_filters = {}
+    for name in module_names or []:
+        name = (name or "").strip()
+        if not name:
+            continue
+        try:
+            mod = importlib.import_module(name)
+            if hasattr(mod, "define_env"):
+                env = MacroEnv()
+                mod.define_env(env)
+                all_vars.update(env.variables)
+                all_macros.update(env._macros)
+                all_filters.update(env._filters)
+        except ImportError as e:
+            logger.warning("markdown_macros: could not load pluglet %r: %s", name, e)
+    return all_vars, all_macros, all_filters
+
+
+def _load_one_yaml(path, project_root=None):
+    """Load a single YAML file; return dict or None."""
+    if not yaml:
+        return None
+    root = Path(project_root or ".").resolve()
+    p = root / path if not Path(path).is_absolute() else Path(path)
+    if not p.exists():
+        return None
+    try:
+        with open(p, encoding="utf-8") as f:
+            data = yaml.safe_load(f)
+        return data if isinstance(data, dict) else None
+    except Exception:
+        return None
+
+
+def _merge_include_yaml(include_yaml, project_root, variables):
+    """
+    Merge include_yaml into variables.
+    include_yaml can be: list of paths (flat merge) or dict of key -> path (merge under key).
+    """
+    if not include_yaml:
+        return
+    if isinstance(include_yaml, dict):
+        for key, path in include_yaml.items():
+            data = _load_one_yaml(path, project_root)
+            if data is not None:
+                variables[key] = data
+    else:
+        for path in include_yaml:
+            data = _load_one_yaml(path, project_root)
+            if isinstance(data, dict):
+                variables.update(data)
+
+
+class MacrosPreprocessor(Preprocessor):
+    """Parse front matter, build Jinja2 context, render body."""
+
+    def __init__(self, md, config):
+        super().__init__(md)
+        self.config = config
+
+    def run(self, lines):
+        text = "\n".join(lines)
+        project_root = self.config.get("project_root") or "."
+        verbose = self.config.get("verbose", False)
+
+        # 1) Parse and strip front matter
+        match = FRONT_MATTER_RE.match(text)
+        if match:
+            raw_block = match.group(1).strip()
+            if yaml:
+                try:
+                    data = yaml.safe_load(raw_block)
+                    if data is None:
+                        data = {}
+                    if not isinstance(data, dict):
+                        data = {"content": data}
+                except Exception:
+                    data = {}
+            else:
+                data = {}
+            self.md.Meta = getattr(self.md, "Meta", None) or {}
+            self.md.Meta.update(_meta_from_dict(data))
+            self.md.front_matter = data
+            body = text[match.end() :]
+        else:
+            self.md.Meta = getattr(self.md, "Meta", None) or {}
+            if not hasattr(self.md, "front_matter") or self.md.front_matter is None:
+                self.md.front_matter = {}
+            body = text
+
+        # render_by_default: if False, only render when front matter has render_macros: true
+        render_by_default = self.config.get("render_by_default", True)
+        page_render_macros = self.md.front_matter.get("render_macros")
+        if not render_by_default and not page_render_macros:
+            if verbose:
+                logger.debug("markdown_macros: skipping Jinja2 (render_by_default=False, no render_macros)")
+            return body.split("\n")
+
+        # 2) Build context: config variables + include_yaml + module + pluglets + front matter
+        variables = dict(self.config.get("variables") or {})
+        _merge_include_yaml(
+            self.config.get("include_yaml"),
+            project_root,
+            variables,
+        )
+        module_name = (self.config.get("module_name") or "").strip()
+        if module_name:
+            if verbose:
+                logger.debug("markdown_macros: loading module %r", module_name)
+            mod_vars, macros, filters = _load_module(module_name, project_root)
+            variables.update(mod_vars)
+            variables.update(macros)
+        else:
+            macros = {}
+            filters = {}
+        # Pluglets (preinstalled modules)
+        pluglet_names = self.config.get("modules") or []
+        if pluglet_names:
+            if verbose:
+                logger.debug("markdown_macros: loading pluglets %s", pluglet_names)
+            pv, pm, pf = _load_pluglets(pluglet_names)
+            variables.update(pv)
+            if not module_name:
+                macros = {}
+                filters = {}
+            macros.update(pm)
+            filters.update(pf)
+        if match:
+            variables.update(self.md.front_matter)
+
+        if not jinja2:
+            return body.split("\n")
+
+        # 3) Build Jinja2 environment
+        include_dir = self.config.get("include_dir") or ""
+        include_dir_path = (Path(project_root) / include_dir).resolve() if include_dir else None
+        env_kw = {
+            "block_start_string": self.config.get("j2_block_start_string") or "{%",
+            "block_end_string": self.config.get("j2_block_end_string") or "%}",
+            "variable_start_string": self.config.get("j2_variable_start_string") or "{{",
+            "variable_end_string": self.config.get("j2_variable_end_string") or "}}",
+        }
+        comment_start = self.config.get("j2_comment_start_string")
+        comment_end = self.config.get("j2_comment_end_string")
+        if comment_start is not None:
+            env_kw["comment_start_string"] = comment_start
+        if comment_end is not None:
+            env_kw["comment_end_string"] = comment_end
+        on_undefined = self.config.get("on_undefined", "keep")
+        if on_undefined == "strict":
+            env_kw["undefined"] = jinja2.StrictUndefined
+        j2_extensions = self.config.get("j2_extensions") or []
+        if j2_extensions:
+            env_kw["extensions"] = list(j2_extensions)
+        if include_dir_path and include_dir_path.exists():
+            env_kw["loader"] = jinja2.FileSystemLoader(str(include_dir_path))
+        env = jinja2.Environment(**env_kw)
+        env.filters.update(filters)
+
+        # MkDocs Macros compatibility: expand Jinja2 in the YAML "title" field (plugin exception since 1.0.2)
+        title_val = variables.get("title")
+        if isinstance(title_val, str) and ("{{" in title_val or "{%" in title_val):
+            try:
+                title_template = env.from_string(title_val)
+                variables["title"] = title_template.render(**variables)
+                self.md.front_matter["title"] = variables["title"]
+                self.md.Meta["title"] = [variables["title"]]
+            except Exception:
+                pass
+
+        try:
+            if verbose:
+                logger.debug("markdown_macros: rendering template")
+            template = env.from_string(body)
+            rendered = template.render(**variables)
+        except Exception as e:
+            if self.config.get("on_error_fail", False):
+                raise
+            if verbose:
+                logger.debug("markdown_macros: render error (swallowing): %s", e)
+            rendered = body
+        return rendered.split("\n")
+
+
+class MacrosExtension(Extension):
+    """Python-Markdown extension: Jinja2 templating with variables, macros, and filters (MkDocs-Macros style)."""
+
+    def __init__(self, **kwargs):
+        self.config = {
+            "variables": [{}, "Global variables merged into Jinja2 context"],
+            "module_name": ["", "Python module name (e.g. main) with define_env(env)"],
+            "modules": [[], "List of pluglet package names (e.g. mkdocs_macros_plugin.include)"],
+            "include_yaml": [[], "Paths to YAML files (list) or key: path (dict) to merge into variables"],
+            "include_dir": ["", "Directory for {% include 'file' %} (relative to project_root)"],
+            "project_root": [".", "Project root for resolving module, YAML, and include_dir paths"],
+            "render_by_default": [True, "If False, only render when front matter has render_macros: true"],
+            "on_error_fail": [False, "If True, raise on Jinja2 error instead of returning unchanged body"],
+            "on_undefined": ["keep", "Undefined vars: 'keep' (leave/empty) or 'strict' (raise)"],
+            "verbose": [False, "Log debug messages"],
+            "j2_block_start_string": ["{%", "Jinja2 block start"],
+            "j2_block_end_string": ["%}", "Jinja2 block end"],
+            "j2_variable_start_string": ["{{", "Jinja2 variable start"],
+            "j2_variable_end_string": ["}}", "Jinja2 variable end"],
+            "j2_comment_start_string": [None, "Jinja2 comment start (default {#)"],
+            "j2_comment_end_string": [None, "Jinja2 comment end (default #})"],
+            "j2_extensions": [[], "List of Jinja2 extension names or classes"],
+        }
+        super().__init__(**kwargs)
+
+    def extendMarkdown(self, md):
+        md.registerExtension(self)
+        md.preprocessors.register(
+            MacrosPreprocessor(md, self.getConfigs()),
+            "macros",
+            priority=20,
+        )
+
+
+def make_extension(**kwargs):
+    return MacrosExtension(**kwargs)

markdown_macros_extension-0.1.0/markdown_macros_extension.egg-info/PKG-INFO

@@ -0,0 +1,91 @@
+Metadata-Version: 2.4
+Name: markdown-macros-extension
+Version: 0.1.0
+Summary: Python-Markdown extension: MkDocs-Macros–style Jinja2 templating (variables, macros, filters) with YAML front matter for Zensical and MkDocs
+Author: BarCar
+License: MIT
+Project-URL: Documentation, https://github.com/barcar/markdown-macros#readme
+Project-URL: Repository, https://github.com/barcar/markdown-macros
+Keywords: markdown,frontmatter,yaml,zensical,mkdocs,macros
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Text Processing :: Markup
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: markdown>=3.4
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: jinja2>=3.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: zensical; extra == "docs"
+Dynamic: license-file
+
+# Markdown Macros
+
+[![Deploy docs to GitHub Pages](https://github.com/barcar/markdown-macros/actions/workflows/pages.yml/badge.svg)](https://github.com/barcar/markdown-macros/actions/workflows/pages.yml)
+
+**Author:** [BarCar](https://github.com/barcar) · **Repository:** [github.com/barcar/markdown-macros](https://github.com/barcar/markdown-macros)
+
+A **Python-Markdown extension** that brings [MkDocs Macros](https://mkdocs-macros-plugin.readthedocs.io/)–style **Jinja2 templating** to any Markdown pipeline: variables (config + YAML front matter), **macros**, and **filters**. Works with [Zensical](https://zensical.org), MkDocs, or plain Python—without the MkDocs plugin.
+
+## Features
+
+- **Variables** from config, YAML front matter, or `include_yaml`
+- **Macros and filters** via `define_env(env)` in a Python module (same API as MkDocs Macros)
+- **YAML front matter** parsed and exposed as `md.Meta` / `md.front_matter`
+
+## Installation
+
+```bash
+pip install markdown-macros-extension
+```
+
+Requires: `markdown>=3.4`, `pyyaml>=6.0`, `jinja2>=3.0`.
+
+## Quick example
+
+```python
+import markdown
+from markdown_macros import MacrosExtension
+
+text = """---
+title: My Page
+---
+
+# {{ title }}
+
+The answer is {{ 6 * 7 }}.
+"""
+md = markdown.Markdown(extensions=[MacrosExtension()])
+html = md.convert(text)  # title and 42 rendered
+```
+
+In Zensical or MkDocs, add `markdown_macros` to your Markdown extensions and optionally set `module_name`, `variables`, `include_yaml`, etc. See the [documentation](https://barcar.github.io/markdown-macros/) for configuration, usage, and the full API.
+
+**Compatibility:** API-aligned with the [MkDocs Macros plugin](https://mkdocs-macros-plugin.readthedocs.io/) (variables, macros, filters, `define_env`); see [Compatibility](https://barcar.github.io/markdown-macros/compatibility/) in the docs.
+
+## Documentation
+
+**Online:** [Documentation](https://barcar.github.io/markdown-macros/) (GitHub Pages).
+
+To build the docs locally:
+
+```bash
+pip install -e ".[docs]"
+zensical serve
+```
+
+## License
+
+MIT License. See [LICENSE](LICENSE).

markdown_macros_extension-0.1.0/markdown_macros_extension.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+LICENSE
+README.md
+pyproject.toml
+markdown_macros/__init__.py
+markdown_macros/front_matter.py
+markdown_macros/macros.py
+markdown_macros_extension.egg-info/PKG-INFO
+markdown_macros_extension.egg-info/SOURCES.txt
+markdown_macros_extension.egg-info/dependency_links.txt
+markdown_macros_extension.egg-info/entry_points.txt
+markdown_macros_extension.egg-info/requires.txt
+markdown_macros_extension.egg-info/top_level.txt
+tests/test_front_matter.py
+tests/test_macros.py

markdown_macros_extension-0.1.0/markdown_macros_extension.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

markdown_macros_extension-0.1.0/markdown_macros_extension.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[markdown.extensions]
+markdown_macros = markdown_macros:MacrosExtension

markdown_macros_extension-0.1.0/markdown_macros_extension.egg-info/requires.txt

@@ -0,0 +1,10 @@
+markdown>=3.4
+pyyaml>=6.0
+jinja2>=3.0
+
+[dev]
+pytest>=7
+pytest-cov
+
+[docs]
+zensical

markdown_macros_extension-0.1.0/markdown_macros_extension.egg-info/top_level.txt

@@ -0,0 +1 @@
+markdown_macros

markdown_macros_extension-0.1.0/pyproject.toml

@@ -0,0 +1,51 @@
+[build-system]
+requires = ["setuptools>=61", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "markdown-macros-extension"
+version = "0.1.0"
+description = "Python-Markdown extension: MkDocs-Macros–style Jinja2 templating (variables, macros, filters) with YAML front matter for Zensical and MkDocs"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.8"
+authors = [{ name = "BarCar" }]
+keywords = ["markdown", "frontmatter", "yaml", "zensical", "mkdocs", "macros"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Text Processing :: Markup",
+]
+dependencies = [
+    "markdown>=3.4",
+    "pyyaml>=6.0",
+    "jinja2>=3.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7",
+    "pytest-cov",
+]
+docs = [
+    "zensical",
+]
+
+[project.entry-points."markdown.extensions"]
+markdown_macros = "markdown_macros:MacrosExtension"
+
+[project.urls]
+Documentation = "https://github.com/barcar/markdown-macros#readme"
+Repository = "https://github.com/barcar/markdown-macros"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["markdown_macros*"]

markdown_macros_extension-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

markdown_macros_extension-0.1.0/tests/test_front_matter.py

@@ -0,0 +1,75 @@
+"""Tests for the Front Matter extension."""
+
+import markdown
+from markdown_macros import FrontMatterExtension
+
+
+def test_parses_yaml_front_matter():
+    text = """---
+title: My Page
+description: A short summary
+tags:
+  - blog
+  - docs
+---
+
+# Hello
+
+Content here.
+"""
+    md = markdown.Markdown(extensions=[FrontMatterExtension()])
+    html = md.convert(text)
+
+    assert "title" in md.Meta
+    assert md.Meta["title"] == ["My Page"]
+    assert md.Meta["description"] == ["A short summary"]
+    assert md.Meta["tags"] == ["blog", "docs"]
+
+    assert md.front_matter["title"] == "My Page"
+    assert md.front_matter["description"] == "A short summary"
+    assert md.front_matter["tags"] == ["blog", "docs"]
+
+    assert "<h1>Hello</h1>" in html
+    assert "---" not in html
+    assert "title:" not in html
+
+
+def test_no_front_matter():
+    text = "# No front matter\n\nJust content."
+    md = markdown.Markdown(extensions=[FrontMatterExtension()])
+    html = md.convert(text)
+
+    assert getattr(md, "Meta", {}) == {} or md.Meta == {}
+    assert getattr(md, "front_matter", {}) == {} or md.front_matter == {}
+    assert "<h1>No front matter</h1>" in html
+
+
+def test_front_matter_extension_alone_sets_meta_and_front_matter():
+    """FrontMatterExtension only: no Jinja2; md.Meta and md.front_matter are set."""
+    text = """---
+title: Solo
+count: 1
+---
+
+# Body
+"""
+    md = markdown.Markdown(extensions=[FrontMatterExtension()])
+    html = md.convert(text)
+    assert md.Meta.get("title") == ["Solo"]
+    assert md.Meta.get("count") == ["1"]
+    assert md.front_matter.get("title") == "Solo"
+    assert md.front_matter.get("count") == 1
+    assert "Body" in html
+
+
+def test_extension_by_name():
+    text = """---
+key: value
+---
+
+Body.
+"""
+    html = markdown.markdown(text, extensions=["markdown_macros"])
+    # Extension runs when loaded by name; we can't easily get md.Meta from markdown()
+    # so just ensure no crash and body is present
+    assert "Body" in html

markdown_macros_extension-0.1.0/tests/test_macros.py

@@ -0,0 +1,136 @@
+"""Tests for the Macros (Jinja2) extension."""
+
+import markdown
+from markdown_macros import MacrosExtension
+
+
+def test_include_yaml_list(tmp_path):
+    """Variables from include_yaml (list of paths) are in context."""
+    vars_file = tmp_path / "vars.yaml"
+    vars_file.write_text("from_yaml: loaded\nkey2: value2\n", encoding="utf-8")
+    text = "Result: {{ from_yaml }} and {{ key2 }}."
+    md = markdown.Markdown(
+        extensions=[
+            MacrosExtension(
+                include_yaml=[str(vars_file)],
+                project_root=str(tmp_path),
+            )
+        ]
+    )
+    html = md.convert(text)
+    assert "loaded" in html
+    assert "value2" in html
+
+
+def test_include_yaml_dict(tmp_path):
+    """Variables from include_yaml (dict key→path) are nested under key."""
+    data_file = tmp_path / "data.yaml"
+    data_file.write_text("nested: value\n", encoding="utf-8")
+    text = "Result: {{ data.nested }}."
+    md = markdown.Markdown(
+        extensions=[
+            MacrosExtension(
+                include_yaml={"data": str(data_file)},
+                project_root=str(tmp_path),
+            )
+        ]
+    )
+    html = md.convert(text)
+    assert "value" in html
+
+
+def test_front_matter_as_variables():
+    text = """---
+title: My Page
+price: 42
+---
+
+# {{ title }}
+
+Price is {{ price }}.
+"""
+    md = markdown.Markdown(extensions=[MacrosExtension()])
+    html = md.convert(text)
+    assert "My Page" in html
+    assert "42" in html
+    assert "{{" not in html
+    assert md.front_matter["title"] == "My Page"
+    assert md.front_matter["price"] == 42
+
+
+def test_config_variables():
+    text = "Unit price: {{ unit_price }}."
+    md = markdown.Markdown(
+        extensions=[MacrosExtension(variables={"unit_price": 10})]
+    )
+    html = md.convert(text)
+    assert "10" in html
+    assert "{{" not in html
+
+
+def test_no_jinja2_leave_unchanged():
+    text = "No variables here."
+    md = markdown.Markdown(extensions=[MacrosExtension()])
+    html = md.convert(text)
+    assert "No variables here" in html
+
+
+def test_render_by_default_false_skips_without_render_macros():
+    text = """---
+title: Page
+---
+
+# {{ title }}
+"""
+    md = markdown.Markdown(
+        extensions=[MacrosExtension(render_by_default=False)]
+    )
+    html = md.convert(text)
+    # Without render_macros: true, Jinja2 is skipped
+    assert "{{ title }}" in html
+    assert md.front_matter["title"] == "Page"
+
+
+def test_render_by_default_false_renders_when_render_macros_true():
+    text = """---
+title: Page
+render_macros: true
+---
+
+# {{ title }}
+"""
+    md = markdown.Markdown(
+        extensions=[MacrosExtension(render_by_default=False)]
+    )
+    html = md.convert(text)
+    assert "Page" in html
+    assert "{{ title }}" not in html
+
+
+def test_title_field_jinja2_expansion():
+    """MkDocs Macros compatibility: title in front matter can contain Jinja2."""
+    text = """---
+title: Page for {{ product_name }}
+product_name: Widget
+---
+
+# {{ title }}
+
+Content.
+"""
+    md = markdown.Markdown(extensions=[MacrosExtension()])
+    html = md.convert(text)
+    assert "Page for Widget" in html
+    assert md.front_matter["title"] == "Page for Widget"
+    assert "{{" not in html
+
+
+def test_on_undefined_strict_raises():
+    import pytest
+    text = "Hello {{ missing }}"
+    # on_error_fail=True so the UndefinedError propagates
+    md = markdown.Markdown(
+        extensions=[MacrosExtension(on_undefined="strict", on_error_fail=True)]
+    )
+    with pytest.raises(Exception):
+        md.convert(text)