mddocx-native 1.2.1__py3-none-any.whl

mddocx/__init__.py

@@ -0,0 +1,115 @@
+from .api import MarkdownWord, render, render_string
+from .batch import BatchResult, collect_markdown_inputs, render_many
+from .config import (
+    CacheConfig,
+    CompilationLimits,
+    FontConfig,
+    FooterConfig,
+    HeaderConfig,
+    ImageConfig,
+    Margins,
+    ListConfig,
+    MathFailurePolicy,
+    MermaidConfig,
+    ChartConfig,
+    DataConfig,
+    PageConfig,
+    PerformanceConfig,
+    PluginConfig,
+    RenderConfig,
+    ReproducibilityConfig,
+    ResourcePolicy,
+    TableConfig,
+    TOCConfig,
+    ValidationConfig,
+    ReferenceConfig, NotesConfig, CitationConfig, AccessibilityConfig, FigureConfig,
+    HeadingNumberingConfig, TitlePageConfig, AbstractConfig, CodeConfig, CalloutConfig, CommentConfig, FieldConfig, MetadataConfig,
+)
+from .extensions import MddocxExtension, load_entrypoint_extensions
+from .profiling import RenderStats
+from .validation import validate_docx_package
+from .inspection import DocxInspection, inspect_docx, inspect_docx_bytes
+from .visual_qa import VisualQAReport, compare_visual_pages, render_docx_pages
+from .accessibility import AccessibilityFinding, AccessibilityReport, audit_docx_accessibility, audit_docx_accessibility_bytes
+from .benchmark import BenchmarkReport, run_performance_gate
+from .api_stability import PUBLIC_API_VERSION, get_public_api_manifest
+from .metadata import MetadataSanitizationReport, SanitizedMarkdown, sanitize_markdown_metadata
+from .project import (
+    ProjectManifest, ProjectCompilation, ProjectBuildResult, ProjectWatchEvent,
+    load_project, compile_project, build_project, watch_project, init_project, project_info,
+)
+
+__all__ = [
+    "MarkdownWord",
+    "RenderConfig",
+    "Margins",
+    "ListConfig",
+    "PageConfig",
+    "ResourcePolicy",
+    "MathFailurePolicy",
+    "MermaidConfig",
+    "ChartConfig",
+    "DataConfig",
+    "HeaderConfig",
+    "FooterConfig",
+    "TOCConfig",
+    "TableConfig",
+    "FontConfig",
+    "ImageConfig",
+    "PerformanceConfig",
+    "CompilationLimits",
+    "ReproducibilityConfig",
+    "ValidationConfig",
+    "CacheConfig",
+    "PluginConfig",
+    "ReferenceConfig",
+    "NotesConfig",
+    "CitationConfig",
+    "AccessibilityConfig",
+    "FigureConfig",
+    "HeadingNumberingConfig",
+    "TitlePageConfig",
+    "AbstractConfig",
+    "CodeConfig",
+    "CalloutConfig",
+    "CommentConfig",
+    "FieldConfig",
+    "MetadataConfig",
+    "MetadataSanitizationReport",
+    "SanitizedMarkdown",
+    "sanitize_markdown_metadata",
+    "RenderStats",
+    "MddocxExtension",
+    "load_entrypoint_extensions",
+    "BatchResult",
+    "collect_markdown_inputs",
+    "render_many",
+    "validate_docx_package",
+    "DocxInspection",
+    "inspect_docx",
+    "inspect_docx_bytes",
+    "VisualQAReport",
+    "compare_visual_pages",
+    "render_docx_pages",
+    "render",
+    "render_string",
+    "ProjectManifest",
+    "ProjectCompilation",
+    "ProjectBuildResult",
+    "ProjectWatchEvent",
+    "load_project",
+    "compile_project",
+    "build_project",
+    "watch_project",
+    "init_project",
+    "project_info",
+    "AccessibilityFinding",
+    "AccessibilityReport",
+    "audit_docx_accessibility",
+    "audit_docx_accessibility_bytes",
+    "BenchmarkReport",
+    "run_performance_gate",
+    "PUBLIC_API_VERSION",
+    "get_public_api_manifest",
+]
+__version__ = "1.2.1"

mddocx/accessibility.py

@@ -0,0 +1,198 @@
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+from io import BytesIO
+import json
+from pathlib import Path
+import re
+from zipfile import BadZipFile, ZipFile
+
+from lxml import etree
+
+from .inspection import inspect_docx_bytes
+
+W = "http://schemas.openxmlformats.org/wordprocessingml/2006/main"
+M = "http://schemas.openxmlformats.org/officeDocument/2006/math"
+WP = "http://schemas.openxmlformats.org/drawingml/2006/wordprocessingDrawing"
+ADEC = "http://schemas.microsoft.com/office/drawing/2017/decorative"
+DC = "http://purl.org/dc/elements/1.1/"
+NS = {"w": W, "m": M, "wp": WP, "adec": ADEC, "dc": DC}
+
+_SEVERITY_RANK = {"info": 0, "low": 1, "medium": 2, "high": 3}
+
+
+@dataclass(slots=True)
+class AccessibilityFinding:
+    code: str
+    severity: str
+    message: str
+    count: int = 1
+
+
+@dataclass(slots=True)
+class AccessibilityReport:
+    findings: list[AccessibilityFinding] = field(default_factory=list)
+    images: int = 0
+    images_missing_alt: int = 0
+    semantic_tables: int = 0
+    tables_missing_header: int = 0
+    headings: int = 0
+    heading_level_jumps: int = 0
+    empty_hyperlinks: int = 0
+    document_title_present: bool = False
+
+    @property
+    def high_findings(self) -> int:
+        return sum(f.count for f in self.findings if f.severity == "high")
+
+    @property
+    def medium_findings(self) -> int:
+        return sum(f.count for f in self.findings if f.severity == "medium")
+
+    @property
+    def ok(self) -> bool:
+        return self.high_findings == 0
+
+    def passes(self, fail_on: str = "high") -> bool:
+        threshold = _SEVERITY_RANK.get(fail_on, 3)
+        return not any(_SEVERITY_RANK.get(f.severity, 0) >= threshold for f in self.findings)
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "ok": self.ok,
+            "images": self.images,
+            "images_missing_alt": self.images_missing_alt,
+            "semantic_tables": self.semantic_tables,
+            "tables_missing_header": self.tables_missing_header,
+            "headings": self.headings,
+            "heading_level_jumps": self.heading_level_jumps,
+            "empty_hyperlinks": self.empty_hyperlinks,
+            "document_title_present": self.document_title_present,
+            "findings": [asdict(f) for f in self.findings],
+        }
+
+    def to_json(self, indent: int | None = 2) -> str:
+        return json.dumps(self.to_dict(), indent=indent, ensure_ascii=False, sort_keys=True)
+
+    def to_text(self) -> str:
+        status = "PASS" if self.ok else "ISSUES"
+        lines = [
+            f"mddocx accessibility audit: {status}",
+            f"Images: {self.images}  Missing alt text: {self.images_missing_alt}",
+            f"Semantic tables: {self.semantic_tables}  Missing header rows: {self.tables_missing_header}",
+            f"Headings: {self.headings}  Heading-level jumps: {self.heading_level_jumps}",
+            f"Empty hyperlinks: {self.empty_hyperlinks}",
+            f"Document title metadata: {'yes' if self.document_title_present else 'no'}",
+        ]
+        if self.findings:
+            lines.append("Findings:")
+            for finding in self.findings:
+                suffix = f" (x{finding.count})" if finding.count != 1 else ""
+                lines.append(f"  {finding.severity.upper()} {finding.code}: {finding.message}{suffix}")
+        return "\n".join(lines)
+
+
+def audit_docx_accessibility(path: str | Path) -> AccessibilityReport:
+    return audit_docx_accessibility_bytes(Path(path).read_bytes())
+
+
+def audit_docx_accessibility_bytes(blob: bytes) -> AccessibilityReport:
+    report = AccessibilityReport()
+    package = inspect_docx_bytes(blob)
+    if not package.valid_zip:
+        report.findings.append(AccessibilityFinding("A11Y001", "high", "The input is not a valid DOCX package."))
+        return report
+    try:
+        with ZipFile(BytesIO(blob), "r") as zf:
+            parser = etree.XMLParser(resolve_entities=False, no_network=True, load_dtd=False, huge_tree=False)
+            document = etree.fromstring(zf.read("word/document.xml"), parser=parser)
+            core = None
+            if "docProps/core.xml" in zf.namelist():
+                try:
+                    core = etree.fromstring(zf.read("docProps/core.xml"), parser=parser)
+                except etree.XMLSyntaxError:
+                    core = None
+    except (BadZipFile, KeyError, OSError, etree.XMLSyntaxError):
+        report.findings.append(AccessibilityFinding("A11Y001", "high", "The DOCX package cannot be audited safely."))
+        return report
+
+    docprs = document.xpath(".//wp:docPr", namespaces=NS)
+    report.images = len(docprs)
+    missing_alt = document.xpath(
+        ".//wp:docPr[(not(@descr) or normalize-space(@descr)='') and not(.//adec:decorative[@val='1'])]",
+        namespaces=NS,
+    )
+    report.images_missing_alt = len(missing_alt)
+    if report.images_missing_alt:
+        report.findings.append(AccessibilityFinding(
+            "A11Y101", "high", "Images or charts are missing alternative text.", report.images_missing_alt
+        ))
+
+    for table in document.xpath(".//w:tbl", namespaces=NS):
+        # Equation-number layout tables are presentation scaffolding, not semantic data tables.
+        if table.xpath(".//m:oMath", namespaces=NS) and len(table.xpath("./w:tr", namespaces=NS)) <= 1:
+            continue
+        report.semantic_tables += 1
+        first_rows = table.xpath("./w:tr[1]", namespaces=NS)
+        has_header = bool(first_rows and first_rows[0].xpath("./w:trPr/w:tblHeader", namespaces=NS))
+        if not has_header:
+            report.tables_missing_header += 1
+    if report.tables_missing_header:
+        report.findings.append(AccessibilityFinding(
+            "A11Y201", "medium", "Semantic tables should identify their first row as a repeating/header row.", report.tables_missing_header
+        ))
+
+    levels: list[int] = []
+    for p in document.xpath(".//w:p[w:pPr/w:pStyle]", namespaces=NS):
+        style_nodes = p.xpath("./w:pPr/w:pStyle/@w:val", namespaces=NS)
+        if not style_nodes:
+            continue
+        level = _heading_level(str(style_nodes[0]))
+        if level is not None:
+            levels.append(level)
+    report.headings = len(levels)
+    last = None
+    for level in levels:
+        if last is not None and level > last + 1:
+            report.heading_level_jumps += 1
+        last = level
+    if report.heading_level_jumps:
+        report.findings.append(AccessibilityFinding(
+            "A11Y301", "medium", "Heading hierarchy skips one or more levels.", report.heading_level_jumps
+        ))
+
+    empty_links = 0
+    for link in document.xpath(".//w:hyperlink", namespaces=NS):
+        text = "".join(link.itertext()).strip()
+        if not text:
+            empty_links += 1
+    report.empty_hyperlinks = empty_links
+    if empty_links:
+        report.findings.append(AccessibilityFinding(
+            "A11Y401", "high", "Hyperlinks with no readable link text were found.", empty_links
+        ))
+
+    title = ""
+    if core is not None:
+        nodes = core.xpath("./dc:title", namespaces=NS)
+        if nodes and nodes[0].text:
+            title = nodes[0].text.strip()
+    report.document_title_present = bool(title)
+    if not report.document_title_present:
+        report.findings.append(AccessibilityFinding(
+            "A11Y501", "low", "Document title metadata is empty. Set RenderConfig.title or YAML front matter title."
+        ))
+
+    if not levels:
+        report.findings.append(AccessibilityFinding(
+            "A11Y302", "low", "No semantic Word heading styles were detected."
+        ))
+    return report
+
+
+def _heading_level(style: str) -> int | None:
+    compact = style.replace(" ", "")
+    match = re.search(r"(?:MD)?Heading([1-6])$", compact, re.IGNORECASE)
+    if match:
+        return int(match.group(1))
+    return None

mddocx/api.py

@@ -0,0 +1,352 @@
+from __future__ import annotations
+
+from copy import deepcopy
+from datetime import datetime
+import hashlib
+from pathlib import Path
+from time import perf_counter
+import tracemalloc
+from typing import Any
+
+from .ast.base import Document
+from .cache import AstCache
+from .config import RenderConfig
+from .diagnostics import Diagnostic, DiagnosticReporter, MddocxError
+from .extensions.base import call_transform_document
+from .extensions.discovery import load_entrypoint_extensions
+from .limits import enforce_ast_limits, enforce_input_limit
+from .metadata import MetadataSanitizationReport, sanitize_markdown_metadata, scrub_generated_docx_core_properties
+from .normalize import Normalizer
+from .parser import MarkdownParser
+from .profiling import RenderStats
+from .render import DocxRenderer
+from .reproducibility import make_reproducible_docx
+from .validation import validate_docx_package
+
+
+class MarkdownWord:
+    def __init__(self, config: RenderConfig | None = None):
+        self.config = deepcopy(config) if config is not None else RenderConfig()
+        self._config_was_provided = config is not None
+        if self.config.plugins.names:
+            discovered = load_entrypoint_extensions(
+                self.config.plugins.names, self.config.plugins.entrypoint_group
+            )
+            self.config.extensions = tuple(self.config.extensions) + discovered
+        self.reporter = DiagnosticReporter()
+        self.parser = MarkdownParser(self.config.extensions, self.config.metadata)
+        self.normalizer = Normalizer()
+        self.last_stats = RenderStats()
+
+    @property
+    def diagnostics(self):
+        return tuple(self.reporter.diagnostics)
+
+    def diagnostics_json(self, indent: int | None = 2) -> str:
+        return self.reporter.to_json(indent=indent)
+
+    def diagnostics_sarif(self, indent: int | None = 2) -> str:
+        return self.reporter.to_sarif(indent=indent)
+
+    def render_file(self, input_path: str | Path, output_path: str | Path) -> None:
+        input_path = Path(input_path)
+        output_path = Path(output_path)
+        try:
+            if input_path.stat().st_size > self.config.limits.max_input_bytes:
+                raise _input_limit_error(self.config.limits.max_input_bytes)
+            markdown = input_path.read_text(encoding="utf-8-sig")
+            blob = self._compile(markdown, input_path.parent, source_file=str(input_path))
+            output_path.parent.mkdir(parents=True, exist_ok=True)
+            output_path.write_bytes(blob)
+        except MddocxError as exc:
+            self._record_error(exc)
+            raise
+
+    def render_string(self, markdown: str, base_dir: str | Path | None = None) -> bytes:
+        return self._compile(
+            markdown,
+            Path(base_dir) if base_dir is not None else Path("."),
+            source_file=None,
+        )
+
+    def render_ast(self, document: Document, base_dir: str | Path | None = None) -> bytes:
+        self.reporter.diagnostics.clear()
+        base = Path(base_dir) if base_dir is not None else Path(".")
+        cfg = self._config_for_document(base, document.metadata)
+        started = perf_counter()
+        try:
+            transformed = call_transform_document(cfg.extensions, self.normalizer.normalize(document))
+            enforce_ast_limits(transformed, cfg.limits)
+            renderer = DocxRenderer(self.reporter)
+            blob = renderer.render(transformed, cfg)
+            blob = self._finalize_output(blob, cfg)
+        except MddocxError as exc:
+            self._record_error(exc)
+            raise
+        elapsed = (perf_counter() - started) * 1000
+        self.last_stats = RenderStats(
+            render_ms=elapsed,
+            total_ms=elapsed,
+            output_bytes=len(blob),
+            output_sha256=hashlib.sha256(blob).hexdigest(),
+        )
+        return blob
+
+    def check_file(self, input_path: str | Path) -> None:
+        self.reporter.diagnostics.clear()
+        input_path = Path(input_path)
+        try:
+            if input_path.stat().st_size > self.config.limits.max_input_bytes:
+                raise _input_limit_error(self.config.limits.max_input_bytes)
+            markdown = input_path.read_text(encoding="utf-8-sig")
+            enforce_input_limit(markdown, self.config.limits)
+            sanitized = sanitize_markdown_metadata(markdown, self.config.metadata)
+            self._report_metadata_sanitization(sanitized.report, str(input_path))
+            ast = self.normalizer.normalize(self.parser.parse(sanitized.markdown, source_file=str(input_path), sanitize_metadata=False))
+            cfg = self._config_for_document(input_path.parent, ast.metadata)
+            ast = call_transform_document(cfg.extensions, ast)
+            enforce_ast_limits(ast, cfg.limits)
+        except MddocxError as exc:
+            self._record_error(exc)
+            raise
+
+    def _compile(self, markdown: str, base_dir: Path, source_file: str | None) -> bytes:
+        self.reporter.diagnostics.clear()
+        cfg_for_memory = self.config.performance
+        started_tracemalloc = cfg_for_memory.track_memory and not tracemalloc.is_tracing()
+        if started_tracemalloc:
+            tracemalloc.start()
+        total_start = perf_counter()
+        cache_hit = False
+        try:
+            enforce_input_limit(markdown, self.config.limits)
+            sanitized = sanitize_markdown_metadata(markdown, self.config.metadata)
+            self._report_metadata_sanitization(sanitized.report, source_file)
+            markdown = sanitized.markdown
+            ast: Document | None = None
+            cache: AstCache | None = None
+            cache_key: str | None = None
+            if self.config.cache.ast_enabled:
+                if self.config.extensions:
+                    self.reporter.info(
+                        "CACHE402",
+                        "Persistent AST cache is disabled when extensions are active.",
+                        source_file,
+                    )
+                else:
+                    cache = AstCache(self.config.cache, base_dir)
+                    cache_key = cache.key(markdown, source_file)
+                    ast = cache.load(cache_key)
+                    cache_hit = ast is not None
+                    if cache_hit:
+                        self.reporter.info("CACHE401", "Loaded normalized AST from persistent cache.", source_file)
+
+            parse_ms = 0.0
+            normalize_ms = 0.0
+            if ast is None:
+                parse_start = perf_counter()
+                ast = self.parser.parse(markdown, source_file=source_file, sanitize_metadata=False)
+                parse_ms = (perf_counter() - parse_start) * 1000
+
+                normalize_start = perf_counter()
+                ast = self.normalizer.normalize(ast)
+                normalize_ms = (perf_counter() - normalize_start) * 1000
+                if cache is not None and cache_key is not None:
+                    try:
+                        cache.save(cache_key, ast)
+                    except (OSError, TypeError, ValueError) as exc:
+                        self.reporter.warn("CACHE403", f"Unable to write persistent AST cache: {type(exc).__name__}", source_file)
+
+            cfg = self._config_for_document(base_dir, ast.metadata)
+            transform_start = perf_counter()
+            ast = call_transform_document(cfg.extensions, ast)
+            enforce_ast_limits(ast, cfg.limits)
+            normalize_ms += (perf_counter() - transform_start) * 1000
+
+            render_start = perf_counter()
+            renderer = DocxRenderer(self.reporter)
+            blob = renderer.render(ast, cfg)
+            blob = self._finalize_output(blob, cfg)
+            render_ms = (perf_counter() - render_start) * 1000
+            total_ms = (perf_counter() - total_start) * 1000
+
+            peak = None
+            if cfg_for_memory.track_memory and tracemalloc.is_tracing():
+                _, peak = tracemalloc.get_traced_memory()
+            self.last_stats = RenderStats(
+                parse_ms=parse_ms,
+                normalize_ms=normalize_ms,
+                render_ms=render_ms,
+                total_ms=total_ms,
+                peak_memory_bytes=peak,
+                output_bytes=len(blob),
+                output_sha256=hashlib.sha256(blob).hexdigest(),
+                ast_cache_hit=cache_hit,
+            )
+            return blob
+        except MddocxError as exc:
+            self._record_error(exc)
+            raise
+        finally:
+            if started_tracemalloc and tracemalloc.is_tracing():
+                tracemalloc.stop()
+
+    @staticmethod
+    def _finalize_output(blob: bytes, cfg: RenderConfig) -> bytes:
+        blob = scrub_generated_docx_core_properties(
+            blob, cfg.metadata, template_used=cfg.template is not None,
+            explicit={
+                "title": cfg.title is not None,
+                "author": cfg.author is not None,
+                "subject": cfg.subject is not None,
+                "keywords": cfg.keywords is not None,
+                "comments": cfg.comments is not None,
+                "created_at": cfg.created_at is not None,
+                "modified_at": False,
+            },
+        )
+        blob = make_reproducible_docx(blob, cfg.reproducibility)
+        validate_docx_package(blob, cfg.validation)
+        return blob
+
+    def _report_metadata_sanitization(self, report: MetadataSanitizationReport, source_file: str | None) -> None:
+        if report.changed:
+            parts = []
+            if report.removed_lines:
+                parts.append(f"{report.removed_lines} source line(s)")
+            if report.removed_front_matter_keys:
+                parts.append(f"{len(report.removed_front_matter_keys)} front-matter field(s)")
+            detail = " and ".join(parts) or "metadata"
+            self.reporter.info("META101", f"Removed AI/chat export metadata: {detail}.", source_file)
+        elif report.detected_export_metadata and report.policy == "keep":
+            self.reporter.info("META102", "AI/chat export metadata was detected and preserved by configuration.", source_file)
+
+    def _record_error(self, exc: MddocxError) -> None:
+        if not self.reporter.diagnostics or self.reporter.diagnostics[-1] != exc.diagnostic:
+            self.reporter.diagnostics.append(exc.diagnostic)
+
+    def _config_for_document(self, base_dir: Path, metadata: dict[str, Any]) -> RenderConfig:
+        cfg = deepcopy(self.config)
+        if cfg.base_dir is None:
+            cfg.base_dir = base_dir
+        return _apply_front_matter(cfg, metadata, self._config_was_provided)
+
+
+def _input_limit_error(max_bytes: int) -> MddocxError:
+    return MddocxError(
+        Diagnostic("error", "LIMIT401", f"Markdown input exceeds {max_bytes} bytes.")
+    )
+
+
+def _apply_front_matter(cfg: RenderConfig, metadata: dict[str, Any], explicit_config: bool) -> RenderConfig:
+    if not metadata:
+        return cfg
+    defaults = RenderConfig()
+
+    def can_use(current: Any, default: Any) -> bool:
+        return not explicit_config or current == default
+
+    scalar_fields = ("title", "author", "subject", "comments")
+    for name in scalar_fields:
+        if metadata.get(name) is not None and can_use(getattr(cfg, name), getattr(defaults, name)):
+            setattr(cfg, name, str(metadata[name]))
+    if metadata.get("keywords") is not None and can_use(cfg.keywords, defaults.keywords):
+        value = metadata["keywords"]
+        cfg.keywords = ", ".join(map(str, value)) if isinstance(value, list) else str(value)
+    if metadata.get("theme") is not None and can_use(cfg.theme, defaults.theme):
+        cfg.theme = str(metadata["theme"])
+    if metadata.get("page_size") in {"A4", "Letter"} and can_use(cfg.page.size, defaults.page.size):
+        cfg.page.size = metadata["page_size"]
+    if metadata.get("orientation") in {"portrait", "landscape"} and can_use(cfg.page.orientation, defaults.page.orientation):
+        cfg.page.orientation = metadata["orientation"]
+    if metadata.get("rtl") in {"off", "auto", "force"} and can_use(cfg.rtl, defaults.rtl):
+        cfg.rtl = metadata["rtl"]
+    if metadata.get("toc") is not None and can_use(cfg.toc.enabled, defaults.toc.enabled):
+        cfg.toc.enabled = bool(metadata["toc"])
+    if metadata.get("page_numbers") is not None and can_use(cfg.footer.page_number, defaults.footer.page_number):
+        cfg.footer.page_number = bool(metadata["page_numbers"])
+        cfg.footer.enabled = cfg.footer.enabled or cfg.footer.page_number
+    if metadata.get("auto_landscape_tables") is not None and can_use(cfg.table.auto_landscape, defaults.table.auto_landscape):
+        cfg.table.auto_landscape = bool(metadata["auto_landscape_tables"])
+    if metadata.get("header") is not None and can_use(cfg.header.text, defaults.header.text):
+        cfg.header.text = str(metadata["header"])
+        cfg.header.enabled = True
+    if metadata.get("footer") is not None and can_use(cfg.footer.text, defaults.footer.text):
+        cfg.footer.text = str(metadata["footer"])
+        cfg.footer.enabled = True
+    if metadata.get("notes") in {"footnote", "endnote"} and can_use(cfg.notes.style, defaults.notes.style):
+        cfg.notes.style = str(metadata["notes"])
+    if metadata.get("bibliography") is not None and can_use(cfg.citations.bibliography, defaults.citations.bibliography):
+        cfg.citations.bibliography = Path(str(metadata["bibliography"]))
+    if metadata.get("citation_style") in {"author-year", "apa", "ieee", "numeric"} and can_use(cfg.citations.style, defaults.citations.style):
+        cfg.citations.style = str(metadata["citation_style"])
+    if metadata.get("auto_bibliography") is not None and can_use(cfg.citations.auto_bibliography, defaults.citations.auto_bibliography):
+        cfg.citations.auto_bibliography = bool(metadata["auto_bibliography"])
+    if metadata.get("title_page") is not None and can_use(cfg.title_page.enabled, defaults.title_page.enabled):
+        cfg.title_page.enabled = bool(metadata["title_page"])
+    if metadata.get("subtitle") is not None and can_use(cfg.title_page.subtitle, defaults.title_page.subtitle):
+        cfg.title_page.subtitle = str(metadata["subtitle"])
+        cfg.title_page.enabled = True
+    if metadata.get("organization") is not None and can_use(cfg.title_page.organization, defaults.title_page.organization):
+        cfg.title_page.organization = str(metadata["organization"])
+        cfg.title_page.enabled = True
+    if metadata.get("title_date") is not None and can_use(cfg.title_page.date, defaults.title_page.date):
+        cfg.title_page.date = str(metadata["title_date"])
+    if metadata.get("abstract") is not None and can_use(cfg.abstract.text, defaults.abstract.text):
+        cfg.abstract.text = str(metadata["abstract"])
+    if metadata.get("abstract_title") is not None and can_use(cfg.abstract.title, defaults.abstract.title):
+        cfg.abstract.title = str(metadata["abstract_title"])
+    if metadata.get("keywords") is not None and not cfg.abstract.keywords:
+        value = metadata["keywords"]
+        cfg.abstract.keywords = tuple(map(str, value)) if isinstance(value, list) else tuple(x.strip() for x in str(value).split(",") if x.strip())
+    if metadata.get("heading_numbering") is not None and can_use(cfg.heading_numbering.enabled, defaults.heading_numbering.enabled):
+        cfg.heading_numbering.enabled = bool(metadata["heading_numbering"])
+    if metadata.get("heading_numbering_depth") is not None and can_use(cfg.heading_numbering.max_level, defaults.heading_numbering.max_level):
+        try:
+            cfg.heading_numbering.max_level = max(1, min(6, int(metadata["heading_numbering_depth"])))
+        except (TypeError, ValueError):
+            pass
+    if metadata.get("equation_numbering") in {"document", "section"} and can_use(cfg.references.equation_number_format, defaults.references.equation_number_format):
+        cfg.references.equation_number_format = str(metadata["equation_numbering"])
+    if metadata.get("caption_numbering") in {"document", "section"} and can_use(cfg.references.caption_number_format, defaults.references.caption_number_format):
+        cfg.references.caption_number_format = str(metadata["caption_numbering"])
+    if metadata.get("code_line_numbers") is not None and can_use(cfg.code.line_numbers, defaults.code.line_numbers):
+        cfg.code.line_numbers = bool(metadata["code_line_numbers"])
+    if metadata.get("syntax_highlighting") is not None and can_use(cfg.code.syntax_highlighting, defaults.code.syntax_highlighting):
+        cfg.code.syntax_highlighting = bool(metadata["syntax_highlighting"])
+    if metadata.get("page_x_of_y") is not None and can_use(cfg.footer.page_x_of_y, defaults.footer.page_x_of_y):
+        cfg.footer.page_x_of_y = bool(metadata["page_x_of_y"]); cfg.footer.enabled = cfg.footer.enabled or cfg.footer.page_x_of_y
+    if metadata.get("created_at") is not None and can_use(cfg.created_at, defaults.created_at):
+        try:
+            cfg.created_at = datetime.fromisoformat(str(metadata["created_at"]).replace("Z", "+00:00"))
+        except ValueError:
+            pass
+    return cfg
+
+
+def _config_with_template(config: RenderConfig | None, template: str | Path | None) -> RenderConfig | None:
+    if template is None:
+        return config
+    cfg = deepcopy(config) if config is not None else RenderConfig()
+    cfg.template = Path(template)
+    return cfg
+
+
+def render(
+    input_path: str | Path,
+    output_path: str | Path,
+    config: RenderConfig | None = None,
+    *,
+    template: str | Path | None = None,
+) -> None:
+    MarkdownWord(_config_with_template(config, template)).render_file(input_path, output_path)
+
+
+def render_string(
+    markdown: str,
+    config: RenderConfig | None = None,
+    base_dir: str | Path | None = None,
+    *,
+    template: str | Path | None = None,
+) -> bytes:
+    return MarkdownWord(_config_with_template(config, template)).render_string(markdown, base_dir=base_dir)