Markdown Conversion¶

Markdown conversion utilities for TeXSmith.

MarkdownConversionError ¶

Bases: Exception

Raised when Markdown cannot be converted into HTML.

MarkdownDocument `dataclass` ¶

MarkdownDocument(html: str, front_matter: dict[str, Any])

Result of converting Markdown into HTML.

deduplicate_markdown_extensions ¶

deduplicate_markdown_extensions(
    values: Iterable[str],
) -> list[str]

Remove duplicate extensions while preserving order and case.

Source code in src/texsmith/adapters/markdown/__init__.py

def deduplicate_markdown_extensions(values: Iterable[str]) -> list[str]:
    """Remove duplicate extensions while preserving order and case."""
    seen: set[str] = set()
    result: list[str] = []
    for value in values:
        if not isinstance(value, str):
            continue
        key = value.lower()
        if key in seen:
            continue
        seen.add(key)
        result.append(value)
    return result

normalize_markdown_extensions ¶

normalize_markdown_extensions(
    values: Iterable[str] | str | None,
) -> list[str]

Normalise extension names from CLI-friendly strings into a flat list.

Source code in src/texsmith/adapters/markdown/__init__.py

def normalize_markdown_extensions(
    values: Iterable[str] | str | None,
) -> list[str]:
    """Normalise extension names from CLI-friendly strings into a flat list."""
    if values is None:
        return []

    if isinstance(values, str):
        candidates: Iterable[str] = [values]
    else:
        candidates = values

    normalized: list[str] = []
    for value in candidates:
        if not isinstance(value, str):
            continue
        chunks = re.split(r"[,\s\x00]+", value)
        normalized.extend(chunk for chunk in chunks if chunk)
    return normalized

render_markdown ¶

render_markdown(
    source: str,
    extensions: Sequence[str] | None = None,
    *,
    base_path: str | Path | None = None,
) -> MarkdownDocument

Convert Markdown source into HTML while collecting front matter.

Source code in src/texsmith/adapters/markdown/__init__.py

def render_markdown(
    source: str,
    extensions: Sequence[str] | None = None,
    *,
    base_path: str | Path | None = None,
) -> MarkdownDocument:
    """Convert Markdown source into HTML while collecting front matter."""
    try:
        import markdown
    except ModuleNotFoundError as exc:  # pragma: no cover - environment dependent
        raise MarkdownConversionError(
            "Python Markdown is required to process Markdown inputs; "
            "install the 'markdown' package."
        ) from exc

    metadata, markdown_body = split_front_matter(source)

    active_extensions = list(extensions or ())
    extensions_key = tuple(active_extensions)

    snippet_enabled = any(
        _normalise_extension_name(extension) == "pymdownx.snippets"
        for extension in active_extensions
    )
    snippet_paths: tuple[str, ...] = ()
    if snippet_enabled and base_path is not None:
        snippet_paths = (str(Path(base_path).resolve()),)

    entry = _resolve_markdown_entry(markdown, extensions_key, snippet_paths)

    resolved_base: Path | None = None
    if base_path is not None:
        try:
            resolved_base = Path(base_path).resolve()
        except OSError:
            resolved_base = Path(base_path)

    try:
        with entry.lock:
            processor = entry.processor
            reset_callback = getattr(processor, "reset", None)
            if callable(reset_callback):
                reset_callback()
            processor.texsmith_mermaid_base_path = (
                str(resolved_base) if resolved_base is not None else None
            )
            html = processor.convert(markdown_body)
    except MarkdownConversionError:
        raise
    except Exception as exc:  # pragma: no cover - library-controlled
        raise MarkdownConversionError(f"Failed to convert Markdown source: {exc}") from exc

    return MarkdownDocument(html=html, front_matter=metadata)

resolve_markdown_extensions ¶

resolve_markdown_extensions(
    requested: Iterable[str] | None,
    disabled: Iterable[str] | None,
) -> list[str]

Return the active Markdown extension list after applying overrides.

Source code in src/texsmith/adapters/markdown/__init__.py

def resolve_markdown_extensions(
    requested: Iterable[str] | None,
    disabled: Iterable[str] | None,
) -> list[str]:
    """Return the active Markdown extension list after applying overrides."""
    enabled = normalize_markdown_extensions(requested)
    disabled_normalized = {
        extension.lower() for extension in normalize_markdown_extensions(disabled)
    }

    combined = deduplicate_markdown_extensions(list(DEFAULT_MARKDOWN_EXTENSIONS) + enabled)

    if not disabled_normalized:
        return combined

    return [extension for extension in combined if extension.lower() not in disabled_normalized]

split_front_matter ¶

split_front_matter(
    source: str,
) -> tuple[dict[str, Any], str]

Split YAML front matter from Markdown content, returning metadata and body.

Source code in src/texsmith/adapters/markdown/__init__.py

def split_front_matter(source: str) -> tuple[dict[str, Any], str]:
    """Split YAML front matter from Markdown content, returning metadata and body."""
    candidate = source.lstrip("\ufeff")
    prefix_len = len(source) - len(candidate)
    lines = candidate.splitlines()
    if not lines or lines[0].strip() != "---":
        return {}, source

    front_matter_lines: list[str] = []
    closing_index: int | None = None
    for idx, line in enumerate(lines[1:], start=1):
        stripped = line.strip()
        if stripped in {"---", "..."}:
            closing_index = idx
            break
        front_matter_lines.append(line)

    if closing_index is None:
        return {}, source

    raw_block = "\n".join(front_matter_lines)
    try:
        metadata = yaml.safe_load(raw_block) or {}
    except yaml.YAMLError:
        return {}, source

    if not isinstance(metadata, dict):
        metadata = {}

    body_lines = lines[closing_index + 1 :]
    body = "\n".join(body_lines)
    if source.endswith("\n"):
        body += "\n"

    prefix = source[:prefix_len]
    return metadata, prefix + body

Central registry for TeXSmith's bundled Markdown extensions.

ExtensionSpec `dataclass` ¶

ExtensionSpec(
    slug: str,
    markdown_entry: str,
    renderer_entry: str | None = None,
    mkdocs_entry: str | None = None,
    description: str | None = None,
)

Describe how to import Markdown and renderer hooks for an extension.