markwright 0.1.0__tar.gz → 0.2.0__tar.gz

{markwright-0.1.0 → markwright-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: markwright
-Version: 0.1.0
+Version: 0.2.0
 Summary: Python-Markdown extensions ported from DigitalOcean's do-markdownit
 Keywords: markdown,python-markdown,do-markdownit,mkdocs,hugo
 Author: Mason Egger
@@ -26,11 +26,11 @@ Description-Content-Type: text/markdown
 
 # markwright
 
-A Python port of DigitalOcean's [`do-markdownit`](https://github.com/digitalocean/do-markdownit) JavaScript library.
+markwright is a set of [Python-Markdown](https://python-markdown.github.io/) extensions plus a companion command-line tool, `mw`, for author-friendly markdown: highlighted text, labeled code fences, and a set of media embeds.
+Use the extensions in any tool built on Python-Markdown (including [MkDocs](https://www.mkdocs.org/), Flask, or a plain script), or the `mw` pipeline in toolchains that are not, like Hugo.
 
-These are [Python-Markdown](https://python-markdown.github.io/) extensions that bring DigitalOcean's markdown syntax (highlighted text, labeled code fences, and a set of media embeds) to any tool built on Python-Markdown, including [MkDocs](https://www.mkdocs.org/), Flask, or a plain script.
-The port maintains compatibility with the original `do-markdownit` HTML output, so rendered pages match what DigitalOcean produces.
-A bundled command-line tool, `mw`, runs the same extensions as pre and post filters around any renderer, so the syntax also works in toolchains that are not built on Python-Markdown, like Hugo.
+The author-facing syntax and HTML output are derived from DigitalOcean's [`do-markdownit`](https://github.com/digitalocean/do-markdownit), so rendered pages match what DigitalOcean produces.
+markwright ports those extensions to Python-Markdown and adds its own pieces on top, most notably the `mw` CLI, which runs the same extensions as pre and post filters around any renderer.
 
 Full documentation and a live demo: https://masonegger.github.io/markwright/
 
@@ -139,8 +139,12 @@ mw pre < in.md | your-renderer | mw post > out.html
 - `mw pre` expands the embeds and extracts fence directives into an `mw-fence` comment.
 - `mw post` applies the fence styling, resolves the highlights, and injects each embed script once.
 - `mw render` runs the full pipeline in one shot for callers without their own renderer.
+- `mw config` prints the resolved configuration and the source of each value.
 - `mw list` prints every extension and the stages it provides.
 
+Which extensions run, and how each is tuned, come from a `markwright.toml` (or a `[tool.markwright]` table in `pyproject.toml`) that the CLI discovers by walking up from the current directory.
+See the [configuration docs](https://masonegger.github.io/markwright/config/).
+
 Your renderer must pass raw HTML and HTML comments through.
 Hugo is a worked, tested example: see the [Hugo guide](https://masonegger.github.io/markwright/integrations/hugo/).
 The full command and flag reference is in the [CLI docs](https://masonegger.github.io/markwright/cli/).

{markwright-0.1.0 → markwright-0.2.0}/README.md

@@ -1,10 +1,10 @@
 # markwright
 
-A Python port of DigitalOcean's [`do-markdownit`](https://github.com/digitalocean/do-markdownit) JavaScript library.
+markwright is a set of [Python-Markdown](https://python-markdown.github.io/) extensions plus a companion command-line tool, `mw`, for author-friendly markdown: highlighted text, labeled code fences, and a set of media embeds.
+Use the extensions in any tool built on Python-Markdown (including [MkDocs](https://www.mkdocs.org/), Flask, or a plain script), or the `mw` pipeline in toolchains that are not, like Hugo.
 
-These are [Python-Markdown](https://python-markdown.github.io/) extensions that bring DigitalOcean's markdown syntax (highlighted text, labeled code fences, and a set of media embeds) to any tool built on Python-Markdown, including [MkDocs](https://www.mkdocs.org/), Flask, or a plain script.
-The port maintains compatibility with the original `do-markdownit` HTML output, so rendered pages match what DigitalOcean produces.
-A bundled command-line tool, `mw`, runs the same extensions as pre and post filters around any renderer, so the syntax also works in toolchains that are not built on Python-Markdown, like Hugo.
+The author-facing syntax and HTML output are derived from DigitalOcean's [`do-markdownit`](https://github.com/digitalocean/do-markdownit), so rendered pages match what DigitalOcean produces.
+markwright ports those extensions to Python-Markdown and adds its own pieces on top, most notably the `mw` CLI, which runs the same extensions as pre and post filters around any renderer.
 
 Full documentation and a live demo: https://masonegger.github.io/markwright/
 
@@ -113,8 +113,12 @@ mw pre < in.md | your-renderer | mw post > out.html
 - `mw pre` expands the embeds and extracts fence directives into an `mw-fence` comment.
 - `mw post` applies the fence styling, resolves the highlights, and injects each embed script once.
 - `mw render` runs the full pipeline in one shot for callers without their own renderer.
+- `mw config` prints the resolved configuration and the source of each value.
 - `mw list` prints every extension and the stages it provides.
 
+Which extensions run, and how each is tuned, come from a `markwright.toml` (or a `[tool.markwright]` table in `pyproject.toml`) that the CLI discovers by walking up from the current directory.
+See the [configuration docs](https://masonegger.github.io/markwright/config/).
+
 Your renderer must pass raw HTML and HTML comments through.
 Hugo is a worked, tested example: see the [Hugo guide](https://masonegger.github.io/markwright/integrations/hugo/).
 The full command and flag reference is in the [CLI docs](https://masonegger.github.io/markwright/cli/).

{markwright-0.1.0 → markwright-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "markwright"
-version = "0.1.0"
+version = "0.2.0"
 description = "Python-Markdown extensions ported from DigitalOcean's do-markdownit"
 readme = "README.md"
 requires-python = ">=3.11"

{markwright-0.1.0 → markwright-0.2.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "markwright"
-version = "0.1.0"
+version = "0.2.0"
 description = "Python-Markdown extensions ported from DigitalOcean's do-markdownit"
 readme = "README.md"
 authors = [

markwright-0.2.0/src/markwright/cli.py

@@ -0,0 +1,245 @@
+# ABOUTME: Command-line entry point for the mw markwright pipeline tool.
+# Builds the argparse parser and dispatches list/pre/post/render; --version reports the package version.
+
+from __future__ import annotations
+
+import argparse
+import sys
+from importlib.metadata import version
+from pathlib import Path
+
+import markdown
+
+from markwright import config, registry
+from markwright.config import Config, ConfigError
+
+
+def _package_version() -> str:
+    """Return the installed markwright distribution version.
+
+    :returns: The version string for the ``markwright`` distribution.
+    """
+    return version("markwright")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Construct the ``mw`` argument parser with its subcommands.
+
+    :returns: A parser exposing ``--version`` and the ``list`` subcommand.
+    """
+    parser = argparse.ArgumentParser(prog="mw", description="markwright Markdown pipeline CLI.")
+    parser.add_argument("--version", action="version", version=f"mw {_package_version()}")
+    subparsers = parser.add_subparsers(dest="command")
+    subparsers.add_parser("list", help="List registered extensions and the stages each provides.")
+    pre_parser = subparsers.add_parser("pre", help="Expand markwright source directives read from stdin.")
+    _add_selection_flags(pre_parser)
+    post_parser = subparsers.add_parser("post", help="Post-process rendered HTML read from stdin.")
+    _add_selection_flags(post_parser)
+    post_parser.add_argument("--warn", action="store_true", help="Report skipped markers to stderr.")
+    render_parser = subparsers.add_parser("render", help="Render Markdown from stdin to final HTML.")
+    _add_selection_flags(render_parser)
+    config_parser = subparsers.add_parser("config", help="Print the resolved configuration and each value's source.")
+    _add_selection_flags(config_parser)
+    return parser
+
+
+def _add_selection_flags(subparser: argparse.ArgumentParser) -> None:
+    """Add the shared ``--config`` and ``--exclude`` selection flags to a subparser.
+
+    :param subparser: The subcommand parser to extend.
+    """
+    subparser.add_argument("--config", default=None, help="Load configuration from PATH, bypassing discovery.")
+    subparser.add_argument("--exclude", action="append", default=[], help="Drop the named extension (repeatable).")
+
+
+def _run_list() -> int:
+    """Print each registered extension and its available stages.
+
+    :returns: Always ``0``.
+    """
+    for name, stages in registry.describe():
+        print(f"{name}: {', '.join(stages)}")
+    return 0
+
+
+def _resolve(args: argparse.Namespace) -> tuple[Config, list[str]] | None:
+    """Load config and resolve the active extension names, reporting failures to stderr.
+
+    Selection resolves from config (``enable`` allowlist or ``disable`` denylist) with the
+    repeatable CLI ``--exclude`` applied on top. A config error or an unknown extension name
+    is reported to stderr and yields ``None`` so the caller returns exit code ``2``.
+
+    :param args: Parsed arguments carrying ``config`` and ``exclude``.
+    :returns: The resolved config and selected extension names, or ``None`` on failure.
+    """
+    explicit_path = Path(args.config) if args.config else None
+    try:
+        resolved_config = config.load_config(explicit_path, Path.cwd())
+    except ConfigError as config_error:
+        print(config_error, file=sys.stderr)
+        return None
+    use = list(resolved_config.enable) if resolved_config.enable is not None else []
+    exclude = [*resolved_config.disable, *args.exclude]
+    try:
+        names = registry.select_extensions(use, exclude)
+    except ValueError as selection_error:
+        print(selection_error, file=sys.stderr)
+        return None
+    return resolved_config, names
+
+
+def _extension_configs(resolved_config: Config, names: list[str]) -> dict[str, dict[str, object]]:
+    """Assemble ``markdown.Markdown`` extension configs from the resolved config.
+
+    Each selected ``markwright.*`` extension with a per-extension option table contributes
+    it, alongside the fixed ``pymdownx.highlight`` entry that keeps language classes on.
+
+    :param resolved_config: The resolved config carrying per-extension option dicts.
+    :param names: The selected extension names.
+    :returns: A mapping of extension name to its option dict.
+    """
+    configs: dict[str, dict[str, object]] = {"pymdownx.highlight": {"pygments_lang_class": True}}
+    for name in names:
+        options = resolved_config.options.get(name)
+        if options:
+            configs[f"markwright.{name}"] = options
+    return configs
+
+
+def _run_pre(args: argparse.Namespace) -> int:
+    """Expand source directives from stdin and write the result to stdout.
+
+    :param args: Parsed arguments carrying ``config`` and ``exclude``.
+    :returns: ``0`` on success, ``2`` if config fails to load or a name is unknown.
+    """
+    resolved = _resolve(args)
+    if resolved is None:
+        return 2
+    resolved_config, names = resolved
+    sys.stdout.write(registry.run_pre(sys.stdin.read(), names, resolved_config.options))
+    return 0
+
+
+def _run_post(args: argparse.Namespace) -> int:
+    """Post-process HTML from stdin and write the result to stdout.
+
+    :param args: Parsed arguments carrying ``config``, ``exclude``, and ``warn``.
+    :returns: ``0`` on success, ``2`` if config fails to load or a name is unknown.
+    """
+    resolved = _resolve(args)
+    if resolved is None:
+        return 2
+    _, names = resolved
+    warnings: list[str] | None = [] if args.warn else None
+    rendered_html = registry.run_post(sys.stdin.read(), names, warnings)
+    sys.stdout.write(rendered_html)
+    if warnings is not None:
+        for warning in warnings:
+            print(warning, file=sys.stderr)
+    return 0
+
+
+def _run_render(args: argparse.Namespace) -> int:
+    """Render Markdown from stdin to final HTML using the in-process stack.
+
+    Builds a ``markdown.Markdown`` instance configured with ``pymdownx.superfences``
+    and ``pymdownx.highlight`` plus the selected ``markwright.*`` extensions, mirroring
+    the site stack so fence and highlight render correctly.
+
+    :param args: Parsed arguments carrying ``config`` and ``exclude``.
+    :returns: ``0`` on success, ``2`` if config fails to load or a name is unknown.
+    """
+    resolved = _resolve(args)
+    if resolved is None:
+        return 2
+    resolved_config, names = resolved
+    instance = markdown.Markdown(
+        extensions=["pymdownx.superfences", "pymdownx.highlight", *(f"markwright.{name}" for name in names)],
+        extension_configs=_extension_configs(resolved_config, names),
+    )
+    sys.stdout.write(instance.convert(sys.stdin.read()))
+    return 0
+
+
+def _extension_status(name: str, resolved_config: Config, excluded: list[str]) -> tuple[str, str]:
+    """Report whether an extension is on or off and where that decision came from.
+
+    Precedence matches selection: a CLI ``--exclude`` wins, then a config ``enable`` allowlist
+    or ``disable`` denylist, then the all-on default.
+
+    :param name: The extension name.
+    :param resolved_config: The resolved config.
+    :param excluded: Names passed to ``--exclude``.
+    :returns: An ``(status, source)`` pair, ``status`` being ``"on"`` or ``"off"``.
+    """
+    config_source = str(resolved_config.source_path) if resolved_config.source_path is not None else "default"
+    if name in excluded:
+        return "off", "--exclude"
+    if resolved_config.enable is not None:
+        return ("on" if name in resolved_config.enable else "off"), config_source
+    if name in resolved_config.disable:
+        return "off", config_source
+    return "on", "default"
+
+
+def _format_config(resolved_config: Config, excluded: list[str]) -> list[str]:
+    """Format the resolved configuration and value sources as printable lines.
+
+    :param resolved_config: The resolved config.
+    :param excluded: Names passed to ``--exclude``.
+    :returns: Output lines for ``mw config``, one per rendered value.
+    """
+    lines = ["extensions:"]
+    for name in registry.EXTENSION_NAMES:
+        status, source = _extension_status(name, resolved_config, excluded)
+        lines.append(f"  {name}: {status} ({source})")
+    warn_source = resolved_config.sources.get("warn", "default")
+    lines.append(f"warn: {str(resolved_config.warn).lower()} ({warn_source})")
+    if resolved_config.options:
+        lines.append("options:")
+        for extension_name, option_table in resolved_config.options.items():
+            source = resolved_config.sources.get(extension_name, "default")
+            lines.append(f"  {extension_name}: {option_table} ({source})")
+    else:
+        lines.append("options: none")
+    return lines
+
+
+def _run_config(args: argparse.Namespace) -> int:
+    """Print the resolved configuration and the source of each value.
+
+    :param args: Parsed arguments carrying ``config`` and ``exclude``.
+    :returns: ``0`` on success, ``2`` if config fails to load or a name is unknown.
+    """
+    resolved = _resolve(args)
+    if resolved is None:
+        return 2
+    resolved_config, _ = resolved
+    for line in _format_config(resolved_config, args.exclude):
+        print(line)
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Parse ``argv`` and dispatch to the selected subcommand.
+
+    :param argv: Argument vector, or ``None`` to read from ``sys.argv``.
+    :returns: Process exit code (``0`` success, ``2`` usage error).
+    """
+    parser = build_parser()
+    try:
+        args = parser.parse_args(argv)
+    except SystemExit as exit_error:
+        return exit_error.code if isinstance(exit_error.code, int) else 2
+    if args.command == "list":
+        return _run_list()
+    if args.command == "pre":
+        return _run_pre(args)
+    if args.command == "post":
+        return _run_post(args)
+    if args.command == "render":
+        return _run_render(args)
+    if args.command == "config":
+        return _run_config(args)
+    parser.print_usage()
+    return 2

{markwright-0.1.0 → markwright-0.2.0}/src/markwright/codepen.py

@@ -6,6 +6,7 @@ from __future__ import annotations
 import html
 import re
 import urllib.parse
+from collections.abc import Mapping
 
 from markdown import Markdown
 from markdown.extensions import Extension
@@ -115,13 +116,14 @@ def _render_match(line: str) -> str | None:
     )
 
 
-def expand_source(text: str) -> str:
+def expand_source(text: str, options: Mapping[str, object] | None = None) -> str:
     """Expand standalone CodePen embed lines to embed HTML in raw source.
 
     Used by the ``mw pre`` CLI stage. Unlike the preprocessor, this emits the
     HTML inline without any Python-Markdown stash placeholder.
 
     :param text: The source text.
+    :param options: Ignored; accepted so the registry calls every pre stage with one signature.
     :returns: The text with standalone CodePen embeds replaced by HTML.
     """
     return "\n".join(_render_match(line) or line for line in text.split("\n"))

markwright-0.2.0/src/markwright/config.py

@@ -0,0 +1,220 @@
+# ABOUTME: Config discovery, TOML parsing, validation, and the resolved Config object.
+# Owns the markwright.toml / [tool.markwright] tuning surface; no dependency on cli.
+
+from __future__ import annotations
+
+import tomllib
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from markwright.registry import EXTENSION_NAMES
+
+_TOP_LEVEL_KEYS: frozenset[str] = frozenset({"enable", "disable", "warn"})
+
+
+class ConfigError(Exception):
+    """Raised for any config discovery, parse, or validation failure.
+
+    Carries a message meant for the user at the CLI boundary, never a traceback.
+    """
+
+
+@dataclass(frozen=True)
+class Config:
+    """Resolved markwright configuration.
+
+    :ivar enable: Allowlist of extension names, or ``None`` when unset.
+    :ivar disable: Denylist of extension names, empty when unset.
+    :ivar options: Per-extension option tables keyed by extension name.
+    :ivar warn: Default for the post stage's marker warnings.
+    :ivar source_path: The file this config was loaded from, or ``None`` for built-in defaults.
+    :ivar sources: Maps each key set in the file (``enable``, ``disable``, ``warn``, or an
+        extension name) to the file path it came from; keys not present use defaults.
+    """
+
+    enable: tuple[str, ...] | None = None
+    disable: tuple[str, ...] = ()
+    options: dict[str, dict[str, object]] = field(default_factory=dict)
+    warn: bool = False
+    source_path: Path | None = None
+    sources: dict[str, str] = field(default_factory=dict)
+
+
+def load_config(explicit_path: Path | None, start_dir: Path) -> Config:
+    """Resolve the configuration from an explicit path or by walk-up discovery.
+
+    :param explicit_path: A specific config file to load, bypassing discovery, or ``None``.
+    :param start_dir: The directory to begin walk-up discovery from when no explicit path is given.
+    :returns: The resolved :class:`Config`; built-in defaults when nothing is found.
+    :raises ConfigError: If a file is missing, unparseable, or fails schema validation.
+    """
+    if explicit_path is not None:
+        path, table = _load_explicit(explicit_path)
+    else:
+        discovered = _discover(start_dir)
+        if discovered is None:
+            return Config()
+        path, table = discovered
+    return _build_config(table, path)
+
+
+def _load_explicit(path: Path) -> tuple[Path, dict[str, object]]:
+    """Load a config table from an explicitly named file.
+
+    :param path: The file named by ``--config``.
+    :returns: The path and its config table.
+    :raises ConfigError: If the file is missing, or a ``pyproject.toml`` lacks a
+        ``[tool.markwright]`` table.
+    """
+    if not path.is_file():
+        raise ConfigError(f"config file not found: {path}")
+    parsed = _read_toml(path)
+    if path.name == "pyproject.toml":
+        table = _pyproject_markwright_table(parsed)
+        if table is None:
+            raise ConfigError(f"no [tool.markwright] table in {path}")
+        return path, table
+    return path, parsed
+
+
+def _discover(start_dir: Path) -> tuple[Path, dict[str, object]] | None:
+    """Walk up from ``start_dir`` to the filesystem root looking for a config file.
+
+    In each directory a ``markwright.toml`` wins over a ``pyproject.toml`` that carries a
+    ``[tool.markwright]`` table. The first directory with either stops the search.
+
+    :param start_dir: The directory to begin the walk from.
+    :returns: The winning path and its config table, or ``None`` if none is found.
+    :raises ConfigError: If a candidate file is present but unparseable.
+    """
+    for directory in [start_dir, *start_dir.parents]:
+        standalone = directory / "markwright.toml"
+        if standalone.is_file():
+            return standalone, _read_toml(standalone)
+        pyproject = directory / "pyproject.toml"
+        if pyproject.is_file():
+            table = _pyproject_markwright_table(_read_toml(pyproject))
+            if table is not None:
+                return pyproject, table
+    return None
+
+
+def _read_toml(path: Path) -> dict[str, object]:
+    """Parse a TOML file, converting parse failures into a clear boundary error.
+
+    :param path: The TOML file to read.
+    :returns: The parsed top-level table.
+    :raises ConfigError: If the file is not valid TOML.
+    """
+    try:
+        with path.open("rb") as handle:
+            parsed: dict[str, object] = tomllib.load(handle)
+    except tomllib.TOMLDecodeError as decode_error:
+        raise ConfigError(f"could not parse {path}: {decode_error}") from decode_error
+    return parsed
+
+
+def _pyproject_markwright_table(parsed: Mapping[str, object]) -> dict[str, object] | None:
+    """Extract the ``[tool.markwright]`` table from a parsed ``pyproject.toml``.
+
+    :param parsed: The parsed ``pyproject.toml`` top-level table.
+    :returns: The markwright config table, or ``None`` if the ``[tool.markwright]`` path is absent.
+    """
+    tool_section = parsed.get("tool")
+    if not isinstance(tool_section, dict):
+        return None
+    markwright_section = tool_section.get("markwright")
+    if not isinstance(markwright_section, dict):
+        return None
+    return markwright_section
+
+
+def _build_config(table: Mapping[str, object], path: Path) -> Config:
+    """Validate a raw config table and resolve it into a :class:`Config`.
+
+    :param table: The parsed config table (from a standalone file or a ``[tool.markwright]`` table).
+    :param path: The source path, recorded for the source map.
+    :returns: The resolved config.
+    :raises ConfigError: If any key, type, or extension name is invalid.
+    """
+    _reject_unknown_keys(table, path)
+    enable = _selection_list(table, "enable", path)
+    disable = _selection_list(table, "disable", path)
+    if enable is not None and disable is not None:
+        raise ConfigError(f"{path}: 'enable' and 'disable' are mutually exclusive")
+    return Config(
+        enable=enable,
+        disable=disable if disable is not None else (),
+        options=_extension_options(table, path),
+        warn=_warn_value(table, path),
+        source_path=path,
+        sources={key: str(path) for key in table},
+    )
+
+
+def _reject_unknown_keys(table: Mapping[str, object], path: Path) -> None:
+    """Reject any top-level key that is neither a recognized setting nor an extension name.
+
+    :param table: The config table.
+    :param path: The source path, for the error message.
+    :raises ConfigError: On the first unrecognized key.
+    """
+    for key in table:
+        if key not in _TOP_LEVEL_KEYS and key not in EXTENSION_NAMES:
+            raise ConfigError(f"{path}: unknown configuration key: {key!r}")
+
+
+def _selection_list(table: Mapping[str, object], key: str, path: Path) -> tuple[str, ...] | None:
+    """Read and validate an ``enable`` or ``disable`` list of extension names.
+
+    :param table: The config table.
+    :param key: Either ``"enable"`` or ``"disable"``.
+    :param path: The source path, for error messages.
+    :returns: The names as a tuple, or ``None`` if the key is absent.
+    :raises ConfigError: If the value is not a list of known extension names.
+    """
+    if key not in table:
+        return None
+    value = table[key]
+    if not isinstance(value, list) or not all(isinstance(item, str) for item in value):
+        raise ConfigError(f"{path}: '{key}' must be a list of extension names")
+    for name in value:
+        if name not in EXTENSION_NAMES:
+            raise ConfigError(f"{path}: unknown extension in '{key}': {name!r}")
+    return tuple(value)
+
+
+def _warn_value(table: Mapping[str, object], path: Path) -> bool:
+    """Read and validate the boolean ``warn`` default.
+
+    :param table: The config table.
+    :param path: The source path, for the error message.
+    :returns: The ``warn`` value, defaulting to ``False`` when absent.
+    :raises ConfigError: If ``warn`` is present but not a boolean.
+    """
+    if "warn" not in table:
+        return False
+    value = table["warn"]
+    if not isinstance(value, bool):
+        raise ConfigError(f"{path}: 'warn' must be a boolean")
+    return value
+
+
+def _extension_options(table: Mapping[str, object], path: Path) -> dict[str, dict[str, object]]:
+    """Collect the per-extension option tables from the config.
+
+    :param table: The config table.
+    :param path: The source path, for error messages.
+    :returns: Option dicts keyed by extension name, in registry order.
+    :raises ConfigError: If an extension key is present but not a table.
+    """
+    options: dict[str, dict[str, object]] = {}
+    for name in EXTENSION_NAMES:
+        if name not in table:
+            continue
+        extension_table = table[name]
+        if not isinstance(extension_table, dict):
+            raise ConfigError(f"{path}: '{name}' must be a table of options")
+        options[name] = extension_table
+    return options

{markwright-0.1.0 → markwright-0.2.0}/src/markwright/fence.py

@@ -30,6 +30,7 @@ from __future__ import annotations
 import html
 import json
 import re
+from collections.abc import Mapping
 
 from markdown import Markdown
 from markdown.extensions import Extension
@@ -267,16 +268,32 @@ def _expand_lines(lines: list[str], allowed_environments: list[str] | None) -> l
     return output
 
 
-def expand_source(text: str) -> str:
+def expand_source(text: str, options: Mapping[str, object] | None = None) -> str:
     """Extract fence directives and emit mw-fence marker comments in raw source.
 
-    Used by the ``mw pre`` CLI stage. Environments are not restricted (the
-    allow-list is an in-process configuration option only).
+    Used by the ``mw pre`` CLI stage. When ``options`` carries an
+    ``allowed_environments`` list, ``[environment ...]`` directives outside it are left
+    unextracted, matching the in-process ``allowed_environments`` config option.
 
     :param text: The source text.
+    :param options: The fence option table from config, or ``None`` for no restriction.
     :returns: The text with directives replaced by mw-fence marker comments.
     """
-    return "\n".join(_expand_lines(text.split("\n"), None))
+    return "\n".join(_expand_lines(text.split("\n"), _allowed_environments(options)))
+
+
+def _allowed_environments(options: Mapping[str, object] | None) -> list[str] | None:
+    """Read the ``allowed_environments`` list from a fence option table.
+
+    :param options: The fence option table, or ``None``.
+    :returns: The allowed environment names, or ``None`` to allow every environment.
+    """
+    if options is None:
+        return None
+    value = options.get("allowed_environments")
+    if isinstance(value, list):
+        return [str(item) for item in value]
+    return None
 
 
 class FencePreprocessor(Preprocessor):

{markwright-0.1.0 → markwright-0.2.0}/src/markwright/highlight.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 
 import re
 import xml.etree.ElementTree as etree
+from collections.abc import Mapping
 
 from markdown import Markdown
 from markdown.extensions import Extension
@@ -98,7 +99,7 @@ def _highlight_prose(segment: str) -> str:
     return _PROSE_HIGHLIGHT_RE.sub(r"<mark>\1</mark>", segment)
 
 
-def expand_source(text: str) -> str:
+def expand_source(text: str, options: Mapping[str, object] | None = None) -> str:
     """Wrap prose highlight markers in ``<mark>`` outside code regions.
 
     The source-stage transform for ``mw pre``. Fenced code blocks, inline code
@@ -107,6 +108,7 @@ def expand_source(text: str) -> str:
     post stage.
 
     :param text: Raw Markdown source.
+    :param options: Ignored; accepted so the registry calls every pre stage with one signature.
     :returns: Source with unescaped prose ``<^>...<^>`` markers wrapped in
         ``<mark>``.
     """

{markwright-0.1.0 → markwright-0.2.0}/src/markwright/image_compare.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 
 import html
 import re
+from collections.abc import Mapping
 
 from markdown import Markdown
 from markdown.extensions import Extension
@@ -43,13 +44,14 @@ def _render_match(line: str) -> str | None:
     return _build_compare_html(left_url, right_url, height, width)
 
 
-def expand_source(text: str) -> str:
+def expand_source(text: str, options: Mapping[str, object] | None = None) -> str:
     """Expand standalone compare embed lines to HTML in raw source.
 
     Used by the ``mw pre`` CLI stage. Emits the HTML inline without any
     Python-Markdown stash placeholder.
 
     :param text: The source text.
+    :param options: Ignored; accepted so the registry calls every pre stage with one signature.
     :returns: The text with standalone compare embeds replaced by HTML.
     """
     return "\n".join(_render_match(line) or line for line in text.split("\n"))

{markwright-0.1.0 → markwright-0.2.0}/src/markwright/instagram.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 
 import html
 import re
+from collections.abc import Mapping
 
 from markdown import Markdown
 from markdown.extensions import Extension
@@ -102,13 +103,14 @@ def _render_match(line: str) -> str | None:
     )
 
 
-def expand_source(text: str) -> str:
+def expand_source(text: str, options: Mapping[str, object] | None = None) -> str:
     """Expand standalone Instagram embed lines to embed HTML in raw source.
 
     Used by the ``mw pre`` CLI stage. Unlike the preprocessor, this emits the
     HTML inline without any Python-Markdown stash placeholder.
 
     :param text: The source text.
+    :param options: Ignored; accepted so the registry calls every pre stage with one signature.
     :returns: The text with standalone Instagram embeds replaced by HTML.
     """
     return "\n".join(_render_match(line) or line for line in text.split("\n"))

{markwright-0.1.0 → markwright-0.2.0}/src/markwright/registry.py

@@ -3,7 +3,7 @@
 
 from __future__ import annotations
 
-from collections.abc import Callable
+from collections.abc import Callable, Mapping
 from typing import TypedDict
 
 from markwright.codepen import apply_html as codepen_post
@@ -20,7 +20,7 @@ from markwright.twitter import apply_html as twitter_post
 from markwright.twitter import expand_source as twitter_pre
 from markwright.youtube import expand_source as youtube_pre
 
-PreFn = Callable[[str], str]
+PreFn = Callable[[str, Mapping[str, object] | None], str]
 PostFn = Callable[[str, list[str] | None], str]
 
 
@@ -87,17 +87,19 @@ def _ordered(
     return sorted(selected, key=lambda name: get_priority(REGISTRY[name]), reverse=True)
 
 
-def run_pre(text: str, names: list[str]) -> str:
+def run_pre(text: str, names: list[str], options: Mapping[str, Mapping[str, object]] | None = None) -> str:
     """Apply each selected pre-stage transform to ``text`` in descending priority order.
 
     :param text: Markdown source text.
     :param names: Selected extension names.
+    :param options: Per-extension option tables keyed by extension name; each stage receives
+        its own table, or ``None`` when it has none.
     :returns: Source text after every selected pre stage has run.
     """
     for name in _ordered(names, lambda spec: spec["pre"], lambda spec: spec["pre_priority"]):
         pre_fn = REGISTRY[name]["pre"]
         assert pre_fn is not None
-        text = pre_fn(text)
+        text = pre_fn(text, options.get(name) if options is not None else None)
     return text
 
 

{markwright-0.1.0 → markwright-0.2.0}/src/markwright/slideshow.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 
 import html
 import re
+from collections.abc import Mapping
 
 from markdown import Markdown
 from markdown.extensions import Extension
@@ -64,13 +65,14 @@ def _render_match(line: str) -> str | None:
     return _build_slideshow_html(urls, height, width)
 
 
-def expand_source(text: str) -> str:
+def expand_source(text: str, options: Mapping[str, object] | None = None) -> str:
     """Expand standalone slideshow embed lines to HTML in raw source.
 
     Used by the ``mw pre`` CLI stage. Emits the HTML inline without any
     Python-Markdown stash placeholder.
 
     :param text: The source text.
+    :param options: Ignored; accepted so the registry calls every pre stage with one signature.
     :returns: The text with standalone slideshow embeds replaced by HTML.
     """
     return "\n".join(_render_match(line) or line for line in text.split("\n"))

{markwright-0.1.0 → markwright-0.2.0}/src/markwright/twitter.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 
 import html
 import re
+from collections.abc import Mapping
 
 from markdown import Markdown
 from markdown.extensions import Extension
@@ -96,13 +97,14 @@ def _render_match(line: str) -> str | None:
     )
 
 
-def expand_source(text: str) -> str:
+def expand_source(text: str, options: Mapping[str, object] | None = None) -> str:
     """Expand standalone Twitter embed lines to embed HTML in raw source.
 
     Used by the ``mw pre`` CLI stage. Unlike the preprocessor, this emits the
     HTML inline without any Python-Markdown stash placeholder.
 
     :param text: The source text.
+    :param options: Ignored; accepted so the registry calls every pre stage with one signature.
     :returns: The text with standalone Twitter embeds replaced by HTML.
     """
     return "\n".join(_render_match(line) or line for line in text.split("\n"))

{markwright-0.1.0 → markwright-0.2.0}/src/markwright/youtube.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 
 import re
 import urllib.parse
+from collections.abc import Mapping
 
 from markdown import Markdown
 from markdown.extensions import Extension
@@ -48,13 +49,14 @@ def _render_match(line: str) -> str | None:
     )
 
 
-def expand_source(text: str) -> str:
+def expand_source(text: str, options: Mapping[str, object] | None = None) -> str:
     """Expand standalone YouTube embed lines to iframe HTML in raw source.
 
     Used by the ``mw pre`` CLI stage. Unlike the preprocessor, this emits the
     HTML inline without any Python-Markdown stash placeholder.
 
     :param text: The source text.
+    :param options: Ignored; accepted so the registry calls every pre stage with one signature.
     :returns: The text with standalone YouTube embeds replaced by iframe HTML.
     """
     return "\n".join(_render_match(line) or line for line in text.split("\n"))

markwright-0.1.0/src/markwright/cli.py

@@ -1,147 +0,0 @@
-# ABOUTME: Command-line entry point for the mw markwright pipeline tool.
-# Builds the argparse parser and dispatches list/pre/post/render; --version reports the package version.
-
-from __future__ import annotations
-
-import argparse
-import sys
-from importlib.metadata import version
-
-import markdown
-
-from markwright import registry
-
-
-def _package_version() -> str:
-    """Return the installed markwright distribution version.
-
-    :returns: The version string for the ``markwright`` distribution.
-    """
-    return version("markwright")
-
-
-def build_parser() -> argparse.ArgumentParser:
-    """Construct the ``mw`` argument parser with its subcommands.
-
-    :returns: A parser exposing ``--version`` and the ``list`` subcommand.
-    """
-    parser = argparse.ArgumentParser(prog="mw", description="markwright Markdown pipeline CLI.")
-    parser.add_argument("--version", action="version", version=f"mw {_package_version()}")
-    subparsers = parser.add_subparsers(dest="command")
-    subparsers.add_parser("list", help="List registered extensions and the stages each provides.")
-    pre_parser = subparsers.add_parser("pre", help="Expand markwright source directives read from stdin.")
-    _add_selection_flags(pre_parser)
-    post_parser = subparsers.add_parser("post", help="Post-process rendered HTML read from stdin.")
-    _add_selection_flags(post_parser)
-    post_parser.add_argument("--warn", action="store_true", help="Report skipped markers to stderr.")
-    render_parser = subparsers.add_parser("render", help="Render Markdown from stdin to final HTML.")
-    _add_selection_flags(render_parser)
-    return parser
-
-
-def _add_selection_flags(subparser: argparse.ArgumentParser) -> None:
-    """Add the shared ``--use`` and ``--exclude`` selection flags to a subparser.
-
-    :param subparser: The subcommand parser to extend.
-    """
-    subparser.add_argument("--use", action="append", default=[], help="Restrict to the named extension (repeatable).")
-    subparser.add_argument("--exclude", action="append", default=[], help="Drop the named extension (repeatable).")
-
-
-def _run_list() -> int:
-    """Print each registered extension and its available stages.
-
-    :returns: Always ``0``.
-    """
-    for name, stages in registry.describe():
-        print(f"{name}: {', '.join(stages)}")
-    return 0
-
-
-def _resolve_selection(args: argparse.Namespace) -> list[str] | None:
-    """Resolve the active extension names, reporting unknown names to stderr.
-
-    :param args: Parsed arguments carrying ``use`` and ``exclude`` lists.
-    :returns: Selected extension names, or ``None`` if a name is unknown (the
-        caller should then return exit code ``2``).
-    """
-    try:
-        return registry.select_extensions(args.use, args.exclude)
-    except ValueError as selection_error:
-        print(selection_error, file=sys.stderr)
-        return None
-
-
-def _run_pre(args: argparse.Namespace) -> int:
-    """Expand source directives from stdin and write the result to stdout.
-
-    :param args: Parsed arguments carrying ``use`` and ``exclude``.
-    :returns: ``0`` on success, ``2`` if a selected extension name is unknown.
-    """
-    names = _resolve_selection(args)
-    if names is None:
-        return 2
-    sys.stdout.write(registry.run_pre(sys.stdin.read(), names))
-    return 0
-
-
-def _run_post(args: argparse.Namespace) -> int:
-    """Post-process HTML from stdin and write the result to stdout.
-
-    :param args: Parsed arguments carrying ``use``, ``exclude``, and ``warn``.
-    :returns: ``0`` on success, ``2`` if a selected extension name is unknown.
-    """
-    names = _resolve_selection(args)
-    if names is None:
-        return 2
-    warnings: list[str] | None = [] if args.warn else None
-    rendered_html = registry.run_post(sys.stdin.read(), names, warnings)
-    sys.stdout.write(rendered_html)
-    if warnings is not None:
-        for warning in warnings:
-            print(warning, file=sys.stderr)
-    return 0
-
-
-def _run_render(args: argparse.Namespace) -> int:
-    """Render Markdown from stdin to final HTML using the in-process stack.
-
-    Builds a ``markdown.Markdown`` instance configured with ``pymdownx.superfences``
-    and ``pymdownx.highlight`` plus the selected ``markwright.*`` extensions, mirroring
-    the site stack so fence and highlight render correctly.
-
-    :param args: Parsed arguments carrying ``use`` and ``exclude``.
-    :returns: ``0`` on success, ``2`` if a selected extension name is unknown.
-    """
-    names = _resolve_selection(args)
-    if names is None:
-        return 2
-    instance = markdown.Markdown(
-        extensions=["pymdownx.superfences", "pymdownx.highlight", *(f"markwright.{name}" for name in names)],
-        extension_configs={"pymdownx.highlight": {"pygments_lang_class": True}},
-    )
-    sys.stdout.write(instance.convert(sys.stdin.read()))
-    return 0
-
-
-def main(argv: list[str] | None = None) -> int:
-    """Parse ``argv`` and dispatch to the selected subcommand.
-
-    :param argv: Argument vector, or ``None`` to read from ``sys.argv``.
-    :returns: Process exit code (``0`` success, ``2`` usage error).
-    """
-    parser = build_parser()
-    try:
-        args = parser.parse_args(argv)
-    except SystemExit as exit_error:
-        return exit_error.code if isinstance(exit_error.code, int) else 2
-    if args.command == "list":
-        return _run_list()
-    if args.command == "pre":
-        return _run_pre(args)
-    if args.command == "post":
-        return _run_post(args)
-    if args.command == "render":
-        return _run_render(args)
-    parser.print_usage()
-    return 2