docvortex 0.2.1__py3-none-any.whl

docvortex/render/_internal/markdown/inline.py

@@ -0,0 +1,260 @@
+"""Middle JSON 2.0 行内 Span 到 Markdown 的安全序列化。"""
+
+from __future__ import annotations
+
+import html
+import re
+from collections.abc import Sequence
+
+from ....content.inline import join_inline_spans
+from ....options import LatexDelimitersConfig
+from ....schema import CodeInlineSpan, EquationInlineSpan, HyperlinkSpan, InlineSpan, TextSpan
+from .escaping import escape_conservative_markdown_text
+
+_HTML_LIKE_TEXT_RE = re.compile(r"</?[A-Za-z][^<>\n]*>|<!--.*?-->|<![A-Za-z][^<>\n]*>|<\?[^<>\n]*\?>")
+_ENTITY_LIKE_RE = re.compile(r"&(?:#[xX][0-9A-Fa-f]+|#[0-9]+|[A-Za-z][A-Za-z0-9]+);?")
+_SIMPLE_STYLE_WRAPPERS = {
+    frozenset({"bold"}): "**",
+    frozenset({"italic"}): "*",
+    frozenset({"strikethrough"}): "~~",
+    frozenset({"bold", "italic"}): "***",
+}
+
+
+def render_inline_content(content: list[InlineSpan], delimiters: LatexDelimitersConfig) -> str:
+    """把一段 MiddleJson 行内内容渲染为 Markdown。"""
+    return render_inline_spans(content, delimiters)
+
+
+def render_joined_inline_contents(contents: list[list[InlineSpan]], delimiters: LatexDelimitersConfig) -> str:
+    """按物理段落边界规则合并多段 content 后渲染 Markdown。"""
+    return render_inline_spans(join_inline_spans(contents), delimiters)
+
+
+def render_inline_spans(spans: list[InlineSpan], delimiters: LatexDelimitersConfig) -> str:
+    """把行内 Span 序列化为 Markdown 与必要的安全 HTML。"""
+    return "".join(_render_inline_span(span, delimiters) for span in spans)
+
+
+def render_inline_spans_in_html_context(spans: list[InlineSpan], delimiters: LatexDelimitersConfig) -> str:
+    """把 Markdown raw HTML 容器内的 Span 全部序列化为安全 HTML 行内语法。"""
+    return "".join(_render_inline_span_in_html_context(span, delimiters) for span in spans)
+
+
+def _render_inline_span(span: InlineSpan, delimiters: LatexDelimitersConfig) -> str:
+    """渲染单个结构化行内 Span。"""
+    if isinstance(span, TextSpan):
+        content = _escape_plain_markdown_text(span.content)
+        return _apply_styles(content, span.content, span.styles)
+    if isinstance(span, CodeInlineSpan):
+        return _render_inline_code(span.content)
+    if isinstance(span, EquationInlineSpan):
+        return f"{delimiters.inline.left}{span.content}{delimiters.inline.right}"
+    if isinstance(span, HyperlinkSpan):
+        label = render_inline_spans(list(span.content), delimiters)
+        return _render_link(label, span.url, _requires_html_link(list(span.content)))
+    raise TypeError(f"Unsupported inline span: {type(span).__name__}")
+
+
+def _render_inline_span_in_html_context(span: InlineSpan, delimiters: LatexDelimitersConfig) -> str:
+    """渲染一个嵌入 Markdown raw HTML block 的结构化行内 Span。"""
+    if isinstance(span, TextSpan):
+        return _apply_html_styles(html.escape(span.content, quote=False), span.styles)
+    if isinstance(span, CodeInlineSpan):
+        return f"<code>{html.escape(span.content, quote=False)}</code>"
+    if isinstance(span, EquationInlineSpan):
+        return html.escape(f"{delimiters.inline.left}{span.content}{delimiters.inline.right}", quote=False)
+    if isinstance(span, HyperlinkSpan):
+        label = render_inline_spans_in_html_context(list(span.content), delimiters)
+        return _render_link(label, span.url, True)
+    raise TypeError(f"Unsupported inline span: {type(span).__name__}")
+
+
+def _render_inline_code(content: str) -> str:
+    """选择长于内容中反引号游程的 fence，稳定输出 Markdown 行内代码。"""
+    normalized = content.replace("\r\n", " ").replace("\r", " ").replace("\n", " ")
+    longest = max((len(match.group(0)) for match in re.finditer(r"`+", normalized)), default=0)
+    fence = "`" * (longest + 1)
+    if normalized.startswith(("`", " ")) or normalized.endswith(("`", " ")):
+        return f"{fence} {normalized} {fence}"
+    return f"{fence}{normalized}{fence}"
+
+
+def _escape_plain_markdown_text(content: str) -> str:
+    """转义 Markdown 符号，并把普通文字中的标签外观保持为惰性实体。"""
+    parts: list[str] = []
+    cursor = 0
+    for match in _HTML_LIKE_TEXT_RE.finditer(content):
+        parts.append(_escape_entity_like_text(escape_conservative_markdown_text(content[cursor : match.start()])))
+        parts.append(html.escape(match.group(0), quote=False))
+        cursor = match.end()
+    parts.append(_escape_entity_like_text(escape_conservative_markdown_text(content[cursor:])))
+    return "".join(parts)
+
+
+def _escape_entity_like_text(content: str) -> str:
+    """保护会被下游 Markdown 解析器当作 HTML 实体的字面量文本。"""
+
+    def replace(match: re.Match[str]) -> str:
+        """只保护确实会被 HTML 实体解码器改写的候选。"""
+        candidate = match.group(0)
+        return f"&amp;{candidate[1:]}" if html.unescape(candidate) != candidate else candidate
+
+    return _ENTITY_LIKE_RE.sub(replace, content)
+
+
+def _apply_styles(content: str, plain_text: str, styles: Sequence[str]) -> str:
+    """按样式复杂度选择 Markdown wrapper 或安全 HTML 标签。"""
+    if not content or not styles:
+        return content
+    marker = _get_visible_space_marker(styles)
+    if marker is not None:
+        rendered_markers = _render_visible_space_marker_text(content, plain_text, styles, marker)
+        if rendered_markers is not None:
+            return rendered_markers
+    if plain_text and not plain_text.strip() and any(style in styles for style in ("underline", "strikethrough", "emphasis")):
+        return _render_visible_whitespace(plain_text, styles)
+
+    return _apply_style_wrappers(content, styles)
+
+
+def _get_visible_space_marker(styles: Sequence[str]) -> str | None:
+    """按 dev 规则选择可见空格 marker，下划线优先于删除线。"""
+    if "underline" in styles:
+        return "_"
+    if "strikethrough" in styles:
+        return "-"
+    return None
+
+
+def _render_visible_space_marker_text(
+    content: str,
+    plain_text: str,
+    styles: Sequence[str],
+    marker: str,
+) -> str | None:
+    """把纯 ASCII 空格或非空文本首尾空格转换为可见 marker。"""
+    if not plain_text:
+        return None
+    style_key = frozenset(styles)
+    force_html = style_key not in _SIMPLE_STYLE_WRAPPERS
+    if all(char == " " for char in plain_text):
+        ignored_style = "underline" if marker == "_" else "strikethrough"
+        remaining_styles = [style for style in styles if style != ignored_style]
+        return _apply_style_wrappers(
+            marker * len(plain_text),
+            remaining_styles,
+            force_html=force_html,
+        )
+
+    leading_count = len(plain_text) - len(plain_text.lstrip(" "))
+    trailing_count = len(plain_text) - len(plain_text.rstrip(" "))
+    if leading_count == 0 and trailing_count == 0:
+        return None
+    if not content.startswith(" " * leading_count) or not content.endswith(" " * trailing_count):
+        return None
+    content_end = len(content) - trailing_count if trailing_count else len(content)
+    core = content[leading_count:content_end]
+    rendered = f"{marker * leading_count}{core}{marker * trailing_count}"
+    return _apply_style_wrappers(rendered, styles, force_html=force_html)
+
+
+def _apply_style_wrappers(
+    content: str,
+    styles: Sequence[str],
+    *,
+    force_html: bool = False,
+) -> str:
+    """给已处理空格的内容添加 Markdown 或 HTML 样式 wrapper。"""
+    if not content or not styles:
+        return content
+
+    leading = content[: len(content) - len(content.lstrip(" \t"))]
+    trailing = content[len(content.rstrip(" \t")) :]
+    core = content.strip(" \t")
+    if not core:
+        return content
+
+    style_key = frozenset(styles)
+    wrapper = _SIMPLE_STYLE_WRAPPERS.get(style_key)
+    if wrapper is not None and not force_html:
+        return f"{leading}{wrapper}{core}{wrapper}{trailing}"
+    return f"{leading}{_apply_html_styles(core, styles)}{trailing}"
+
+
+def render_styled_markdown_text(content: str, styles: Sequence[str]) -> str:
+    """按正文相同规则把已转义文字渲染为 Markdown 或安全 HTML 样式。"""
+    return _apply_style_wrappers(content, styles)
+
+
+def markdown_styles_require_html(styles: Sequence[str]) -> bool:
+    """判断样式组合是否必须整体使用 HTML 标签表达。"""
+    return bool(styles) and frozenset(styles) not in _SIMPLE_STYLE_WRAPPERS
+
+
+def _render_visible_whitespace(content: str, styles: Sequence[str]) -> str:
+    """使用原 HTML 规则保留非 ASCII marker 场景的可见空白。"""
+    visible = "".join("<br>" if char == "\n" else "&nbsp;" for char in content.expandtabs(4))
+    return _apply_html_styles(visible, styles)
+
+
+def _apply_html_styles(content: str, styles: Sequence[str]) -> str:
+    """按稳定顺序给复杂样式添加 HTML wrapper。"""
+    if "superscript" in styles:
+        content = f"<sup>{content}</sup>"
+    elif "subscript" in styles:
+        content = f"<sub>{content}</sub>"
+    if "underline" in styles:
+        content = f"<u>{content}</u>"
+    if "bold" in styles:
+        content = f"<strong>{content}</strong>"
+    if "italic" in styles:
+        content = f"<em>{content}</em>"
+    if "strikethrough" in styles:
+        content = f"<s>{content}</s>"
+    if "emphasis" in styles:
+        content = f'<span style="text-emphasis: dot; text-emphasis-position: under;">{content}</span>'
+    return content
+
+
+def _requires_html_link(spans: list[InlineSpan]) -> bool:
+    """判断链接标签是否含不适合嵌入 Markdown link 的复杂样式。"""
+    for span in spans:
+        if isinstance(span, TextSpan):
+            if span.styles and frozenset(span.styles) not in _SIMPLE_STYLE_WRAPPERS:
+                return True
+    return False
+
+
+def _render_link(label: str, url: str, use_html: bool) -> str:
+    """按标签复杂度输出 Markdown 或 HTML 超链接。"""
+    if not label:
+        return ""
+    if not url or url == ".":
+        return label
+    if use_html:
+        return f'<a href="{html.escape(url, quote=True)}">{label}</a>'
+    safe_url = url.replace("\\", "%5C").replace(" ", "%20").replace("(", "%28").replace(")", "%29")
+    return f"[{_escape_markdown_link_label(label)}]({safe_url})"
+
+
+def render_internal_link(label: str, anchor: str) -> str:
+    """把已渲染目录标签包装为当前文档内锚点链接。"""
+    safe_anchor = anchor.replace(" ", "%20").replace("(", "%28").replace(")", "%29")
+    return f"[{_escape_markdown_link_label(label)}](#{safe_anchor})"
+
+
+def _escape_markdown_link_label(label: str) -> str:
+    """转义 Markdown link 标签中的方括号并保留既有反斜杠。"""
+    return re.sub(r"(?<!\\)([\[\]])", r"\\\1", label)
+
+
+__all__ = [
+    "markdown_styles_require_html",
+    "render_inline_content",
+    "render_inline_spans",
+    "render_inline_spans_in_html_context",
+    "render_internal_link",
+    "render_joined_inline_contents",
+    "render_styled_markdown_text",
+]

docvortex/render/_internal/markdown/renderer.py

@@ -0,0 +1,93 @@
+"""严格 MiddleJson 到 Markdown 的公共渲染实现。"""
+
+from __future__ import annotations
+
+from ....options import LatexDelimitersConfig
+from ....content.inline import inline_plain_text
+from ....schema import PAGE_AUXILIARY_BLOCK_TYPES, MiddleJson, PageFootnoteBlock, TextBlock, TitleBlockBase
+from ...contracts import ImageRenderer, RenderMode
+from ..common.planner import PlannedBlock, build_render_plan
+from .blocks import render_planned_block
+
+_PAGE_SEPARATOR = "\n\n---\n\n"
+
+
+def render_markdown(
+    middle_json: MiddleJson,
+    *,
+    mode: RenderMode = RenderMode.DEFAULT,
+    asset_base_url: str = "",
+    image_renderer: ImageRenderer | None = None,
+    latex_delimiters: LatexDelimitersConfig | None = None,
+) -> str:
+    """把严格 MiddleJson 纯函数式渲染为 Markdown 字符串。"""
+    if not isinstance(middle_json, MiddleJson):
+        raise TypeError("render_markdown expects a MiddleJson instance")
+    if not isinstance(mode, RenderMode):
+        raise TypeError("mode must be a RenderMode value")
+
+    delimiters = latex_delimiters or LatexDelimitersConfig()
+    planned_pages = build_render_plan(middle_json, mode)
+    anchor_targets = _collect_markdown_anchor_targets(middle_json)
+    emitted_anchors: set[str] = set()
+    rendered_pages = [
+        _render_page(
+            page,
+            mode=mode,
+            delimiters=delimiters,
+            asset_base_url=asset_base_url,
+            image_renderer=image_renderer,
+            anchor_targets=anchor_targets,
+            emitted_anchors=emitted_anchors,
+        )
+        for page in planned_pages
+    ]
+    if mode is RenderMode.FULL:
+        return _PAGE_SEPARATOR.join(rendered_pages)
+    return "\n\n".join(page for page in rendered_pages if page)
+
+
+def _render_page(
+    planned_blocks: list[PlannedBlock],
+    *,
+    mode: RenderMode,
+    delimiters: LatexDelimitersConfig,
+    asset_base_url: str,
+    image_renderer: ImageRenderer | None = None,
+    anchor_targets: set[str] | None = None,
+    emitted_anchors: set[str] | None = None,
+) -> str:
+    """渲染单页逻辑块，并在默认模式中过滤重复页元素。"""
+    rendered: list[str] = []
+    for planned in planned_blocks:
+        if planned.removed:
+            continue
+        if mode is RenderMode.DEFAULT and planned.block.type in PAGE_AUXILIARY_BLOCK_TYPES:
+            continue
+        text = render_planned_block(
+            planned,
+            delimiters=delimiters,
+            asset_base_url=asset_base_url,
+            image_renderer=image_renderer,
+            anchor_targets=anchor_targets,
+            emitted_anchors=emitted_anchors,
+        )
+        if text and text.strip():
+            rendered.append(text.strip("\n"))
+    return "\n\n".join(rendered)
+
+
+def _collect_markdown_anchor_targets(middle_json: MiddleJson) -> set[str]:
+    """收集真实可见的顶层正文、标题和页面脚注 anchor，供目录链接判定。"""
+    targets: set[str] = set()
+    for page in middle_json.pages:
+        for block in page.blocks:
+            if not isinstance(block, (TextBlock, TitleBlockBase, PageFootnoteBlock)):
+                continue
+            anchor = (block.anchor or "").strip()
+            if anchor and inline_plain_text(block.content).strip():
+                targets.add(anchor)
+    return targets
+
+
+__all__ = ["render_markdown"]

docvortex/render/_internal/markdown/table.py

@@ -0,0 +1,281 @@
+"""Markdown renderer 的 HTML 表格判型与无损 GFM 转换。"""
+
+from __future__ import annotations
+
+import html
+import re
+
+from bs4 import BeautifulSoup
+from bs4.element import NavigableString, Tag
+
+from ....options import LatexDelimitersConfig
+from .assets import prefix_html_image_sources
+from .inline import markdown_styles_require_html, render_styled_markdown_text
+
+_INLINE_EQ_RE = re.compile(r"<eq>(?P<latex>.*?)</eq>", re.IGNORECASE | re.DOTALL)
+_GFM_FORMULA_PIPE_RE = re.compile(r"(?P<slashes>\\*)\|")
+_COMPLEX_CELL_TAGS = {
+    "blockquote",
+    "div",
+    "dl",
+    "figure",
+    "h1",
+    "h2",
+    "h3",
+    "h4",
+    "h5",
+    "h6",
+    "img",
+    "li",
+    "math",
+    "object",
+    "ol",
+    "pre",
+    "svg",
+    "table",
+    "ul",
+}
+_ALLOWED_INLINE_TAGS = {
+    "a",
+    "b",
+    "br",
+    "code",
+    "em",
+    "eq",
+    "i",
+    "p",
+    "s",
+    "span",
+    "strong",
+    "sub",
+    "sup",
+    "u",
+}
+_STYLE_TAGS = {
+    "b": "bold",
+    "strong": "bold",
+    "em": "italic",
+    "i": "italic",
+    "u": "underline",
+    "s": "strikethrough",
+    "sup": "superscript",
+    "sub": "subscript",
+}
+
+
+def _strip_embedded_images(markup: str) -> str:
+    """移除自定义图片 renderer 接管的 HTML 图片，并识别清理后的空内容。"""
+    soup = BeautifulSoup(markup, "html.parser")
+    images = soup.find_all("img")
+    if not images:
+        return markup
+    for image in images:
+        image.decompose()
+    if not soup.get_text(strip=True):
+        return ""
+    return str(soup)
+
+
+def render_html_table(
+    content: str,
+    *,
+    asset_base_url: str,
+    delimiters: LatexDelimitersConfig,
+) -> str | None:
+    """将 HTML table 按复杂度输出原 HTML 或转换为 GFM 表格。"""
+    prefixed = prefix_html_image_sources(content, asset_base_url)
+    soup = BeautifulSoup(prefixed, "html.parser")
+    tables = soup.find_all("table")
+    if not tables:
+        return None
+    table = tables[0]
+    if len(tables) != 1 or _is_complex_table(table):
+        return format_embedded_html(prefixed, asset_base_url="", delimiters=delimiters).strip()
+    markdown = _convert_simple_table(table, delimiters)
+    if markdown is not None:
+        return markdown
+    return format_embedded_html(prefixed, asset_base_url="", delimiters=delimiters).strip()
+
+
+def format_embedded_html(
+    markup: str,
+    *,
+    asset_base_url: str,
+    delimiters: LatexDelimitersConfig,
+) -> str:
+    """统一处理嵌入 HTML 的图片地址与行内公式标签。"""
+    prefixed = prefix_html_image_sources(markup, asset_base_url)
+
+    def _replace_inline_equation(match: re.Match[str]) -> str:
+        """把单个 HTML eq 标签替换为配置的行内公式定界符。"""
+        return f" {delimiters.inline.left}{html.unescape(match.group('latex')).strip()}{delimiters.inline.right} "
+
+    return _INLINE_EQ_RE.sub(_replace_inline_equation, prefixed)
+
+
+def _is_complex_table(table: Tag) -> bool:
+    """判断表格是否包含 GFM 无法无损表达的结构。"""
+    if table.find("table") is not None:
+        return True
+    thead = table.find("thead")
+    if thead is not None and len(thead.find_all("tr", recursive=False)) > 1:
+        return True
+    for cell in table.find_all(("th", "td")):
+        if cell.has_attr("rowspan") or cell.has_attr("colspan"):
+            return True
+        if len(cell.find_all("p")) > 1:
+            return True
+        for descendant in cell.descendants:
+            if not isinstance(descendant, Tag):
+                continue
+            if descendant.name in _COMPLEX_CELL_TAGS:
+                return True
+            if descendant.name not in _ALLOWED_INLINE_TAGS:
+                return True
+            if descendant.name == "span" and descendant.attrs:
+                return True
+    return False
+
+
+def _convert_simple_table(table: Tag, delimiters: LatexDelimitersConfig) -> str | None:
+    """把已确认简单的单层 HTML table 转换为 GFM。"""
+    rows = table.find_all("tr")
+    if not rows:
+        return None
+    rendered_rows: list[list[str]] = []
+    header_flags: list[list[bool]] = []
+    for row in rows:
+        cells = row.find_all(("th", "td"), recursive=False)
+        if not cells:
+            return None
+        rendered_rows.append([_normalize_cell_text(_render_inline_children(cell, delimiters)) for cell in cells])
+        header_flags.append([cell.name == "th" for cell in cells])
+
+    width = max(len(row) for row in rendered_rows)
+    for row in rendered_rows:
+        row.extend([""] * (width - len(row)))
+    header_index = _detect_header_index(table, header_flags)
+    header = rendered_rows[header_index]
+    body = rendered_rows[:header_index] + rendered_rows[header_index + 1 :]
+    return "\n".join(
+        [
+            _format_markdown_row(header),
+            _format_markdown_row(["---"] * width),
+            *[_format_markdown_row(row) for row in body],
+        ]
+    )
+
+
+def _detect_header_index(table: Tag, header_flags: list[list[bool]]) -> int:
+    """优先选择 thead 或全 th 行，否则使用首行作为 GFM 表头。"""
+    thead = table.find("thead")
+    if thead is not None and thead.find("tr", recursive=False) is not None:
+        return 0
+    for index, flags in enumerate(header_flags):
+        if flags and all(flags):
+            return index
+    return 0
+
+
+def _render_inline_children(
+    node: Tag,
+    delimiters: LatexDelimitersConfig,
+    inherited_styles: tuple[str, ...] = (),
+) -> str:
+    """递归渲染简单单元格中的安全行内 HTML。"""
+    parts: list[str] = []
+    for child in node.children:
+        if isinstance(child, NavigableString):
+            escaped = _escape_cell_text(str(child))
+            parts.append(render_styled_markdown_text(escaped, inherited_styles))
+            continue
+        if not isinstance(child, Tag):
+            continue
+        name = child.name
+        style = _STYLE_TAGS.get(name)
+        styles = tuple(dict.fromkeys((*inherited_styles, style))) if style is not None else inherited_styles
+        rendered = _render_inline_children(child, delimiters, styles)
+        if name in {"p", "span"}:
+            parts.append(rendered)
+        elif name == "br":
+            parts.append("<br>")
+        elif name == "code":
+            parts.append(_render_inline_code(child.get_text()))
+        elif name == "eq":
+            latex = html.unescape(child.get_text()).strip()
+            escaped_latex = _escape_gfm_formula_pipes(latex)
+            parts.append(f"{delimiters.inline.left}{escaped_latex}{delimiters.inline.right}" if escaped_latex else "")
+        elif name == "a":
+            href = str(child.get("href", "")).strip()
+            if not href:
+                parts.append(rendered)
+            elif _node_has_complex_text_style(child, inherited_styles):
+                parts.append(f'<a href="{html.escape(href, quote=True)}">{rendered}</a>')
+            else:
+                parts.append(f"[{rendered}]({_escape_link_url(href)})")
+        elif name in _STYLE_TAGS:
+            parts.append(rendered)
+        else:
+            parts.append(rendered)
+    return "".join(parts)
+
+
+def _node_has_complex_text_style(node: Tag, inherited_styles: tuple[str, ...]) -> bool:
+    """判断节点后代是否含必须用 HTML 表达的有效文字样式组合。"""
+    for child in node.children:
+        if isinstance(child, NavigableString):
+            if str(child) and markdown_styles_require_html(inherited_styles):
+                return True
+            continue
+        if not isinstance(child, Tag):
+            continue
+        style = _STYLE_TAGS.get(child.name)
+        styles = tuple(dict.fromkeys((*inherited_styles, style))) if style is not None else inherited_styles
+        if _node_has_complex_text_style(child, styles):
+            return True
+    return False
+
+
+def _render_inline_code(content: str) -> str:
+    """使用足够长的反引号包装表格单元格内代码。"""
+    longest = max((len(match.group(0)) for match in re.finditer(r"`+", content)), default=0)
+    fence = "`" * max(1, longest + 1)
+    return f"{fence}{_escape_cell_text(content)}{fence}"
+
+
+def _escape_gfm_formula_pipes(latex: str) -> str:
+    """转义公式竖线，并保证 GFM 解析后恢复原始反斜杠数量。"""
+
+    def _replace(match: re.Match[str]) -> str:
+        """把竖线前 n 个反斜杠扩展为 2n+1 个 Markdown 反斜杠。"""
+        slash_count = len(match.group("slashes"))
+        return "\\" * (2 * slash_count + 1) + "|"
+
+    return _GFM_FORMULA_PIPE_RE.sub(_replace, latex)
+
+
+def _escape_link_url(url: str) -> str:
+    """转义 GFM 表格链接目标中的空格、反斜杠和括号。"""
+    return url.replace("\\", "%5C").replace(" ", "%20").replace("(", "%28").replace(")", "%29").replace("|", "%7C")
+
+
+def _escape_cell_text(content: str) -> str:
+    """转义 GFM 单元格中的 HTML、反斜杠与管道符，避免源文本注入活动标签。"""
+    escaped_html = content.replace("&", "&amp;").replace("<", "&lt;")
+    return escaped_html.replace("\\", "\\\\").replace("|", r"\|")
+
+
+def _normalize_cell_text(content: str) -> str:
+    """压缩普通空白，同时保留显式 br 换行。"""
+    content = re.sub(r"[ \t\r\f\v]+", " ", content)
+    content = re.sub(r" *\n+ *", " ", content)
+    content = re.sub(r" *<br> *", "<br>", content)
+    return content.strip()
+
+
+def _format_markdown_row(row: list[str]) -> str:
+    """把一行单元格格式化为 GFM 行。"""
+    return f"| {' | '.join(row)} |"
+
+
+__all__ = ["format_embedded_html", "render_html_table"]

docvortex/render/_internal/pdf/__init__.py

@@ -0,0 +1,3 @@
+"""PDF 私有渲染实现。"""
+
+__all__: list[str] = []