from __future__ import annotations import html import re from functools import lru_cache from pathlib import Path from typing import Any from urllib.parse import unquote, urlsplit from markdown_it import MarkdownIt from markdown_it.rules_block.state_block import StateBlock from markdown_it.rules_inline.state_inline import StateInline from markdown_it.token import Token from pygments import highlight from pygments.formatters.html import HtmlFormatter from pygments.lexers import get_lexer_by_name from pygments.lexers.special import TextLexer from pygments.util import ClassNotFound from .markdown_utils import heading_tokens from .markdown_compat import cjk_strong_plugin from .media import is_qt_video_player_url, media_kind, media_mime_type @lru_cache(maxsize=16) def _resource_text(path: Path, modified_ns: int, size: int) -> str: """Share static resources across tabs, invalidating on development edits.""" return path.read_text(encoding="utf-8") @lru_cache(maxsize=1) def _highlight_css() -> str: return HtmlFormatter().get_style_defs(".highlight") class MarkdownRenderer: def __init__(self, project_root: Path) -> None: self.project_root = project_root self.resources_dir = Path(__file__).resolve().parent / "resources" self.formatter = HtmlFormatter(nowrap=True) self.markdown = MarkdownIt( "commonmark", { "html": True, "typographer": False, "breaks": False, }, ).enable(["table", "strikethrough"]).use(cjk_strong_plugin) # Local documents and combined exports use file URIs for images. Keep # MarkdownIt's protection against executable schemes while allowing these. validate_link = self.markdown.validateLink self.markdown.validateLink = lambda url: urlsplit(url).scheme.lower() == "file" or validate_link(url) self.markdown.renderer.rules["fence"] = self._render_fence self.markdown.renderer.rules["code_block"] = self._render_code_block self.markdown.renderer.rules["math_block"] = self._render_math_block self.markdown.renderer.rules["math_inline"] = self._render_math_inline self.markdown.renderer.rules["image"] = self._render_image self.markdown.renderer.rules["link_open"] = self._render_link_open self.markdown.block.ruler.before( "fence", "mdhelper_math_block", self._parse_math_block, {"alt": ["paragraph", "reference", "blockquote", "list"]}, ) self.markdown.inline.ruler.before("escape", "mdhelper_math_inline", self._parse_math_inline) self.markdown.core.ruler.push("mdhelper_heading_ids", self._add_heading_ids) self.markdown.core.ruler.push("mdhelper_admonitions", self._convert_admonitions) self.markdown.core.ruler.push("mdhelper_task_lists", self._convert_task_lists) self.markdown.core.ruler.push("mdhelper_semantic_styles", self._mark_semantic_styles) self.markdown.core.ruler.push("mdhelper_source_lines", self._add_source_lines) # Table-cell margins have no layout effect. A content block gives the # semantic paragraph spacing a real box without changing table padding. for name in ('th_open', 'td_open'): self.markdown.renderer.rules[name] = lambda tokens, idx, options, env: self.markdown.renderer.renderToken(tokens, idx, options, env) + '
' for name in ('th_close', 'td_close'): self.markdown.renderer.rules[name] = lambda tokens, idx, options, env: '
' + self.markdown.renderer.renderToken(tokens, idx, options, env) for name in ("fence", "code_block", "math_block"): original = self.markdown.renderer.rules[name] def mapped(tokens, idx, options, env, render=original): output = render(tokens, idx, options, env) if tokens[idx].info.strip().lower() != 'mermaid': output = output.replace(' None: if not state.env.get("source_map"): return for token in state.tokens: if token.map and token.nesting == 1: token.attrSet("data-source-line", str(token.map[0])) token.attrSet("data-source-end", str(token.map[1])) def render_file( self, markdown_path: Path, theme: str = "light", font_scale: float = 1.0, wheel_scroll_speed: float = 1.0, document_width_scale: float = 1.0, document_font_family: str = "", document_font_size: int | None = None, document_style_css: str = "", math_engine: str = "katex", ) -> str: source = markdown_path.read_text(encoding="utf-8") env: dict[str, Any] = {"path": str(markdown_path), "headings": []} body = self.markdown.render(source, env) return self._wrap_html( body=body, title=markdown_path.name, theme=theme, font_scale=font_scale, wheel_scroll_speed=wheel_scroll_speed, document_width_scale=document_width_scale, document_font_family=document_font_family, document_font_size=document_font_size, document_style_css=document_style_css, math_engine=math_engine, ) def render_source( self, source: str, markdown_path: Path, theme: str = "light", font_scale: float = 1.0, wheel_scroll_speed: float = 1.0, document_width_scale: float = 1.0, document_font_family: str = "", document_font_size: int | None = None, document_style_css: str = "", math_engine: str = "katex", source_map: bool = False, ) -> str: env: dict[str, Any] = {"path": str(markdown_path), "headings": [], "source_map": source_map} body = self.markdown.render(source, env) return self._wrap_html( body=body, title=markdown_path.name, theme=theme, font_scale=font_scale, wheel_scroll_speed=wheel_scroll_speed, document_width_scale=document_width_scale, document_font_family=document_font_family, document_font_size=document_font_size, document_style_css=document_style_css, math_engine=math_engine, ) def render_code_source( self, source: str, code_path: Path, language: str = "text", theme: str = "light", font_scale: float = 1.0, wheel_scroll_speed: float = 1.0, document_width_scale: float = 1.0, document_font_family: str = "", document_font_size: int | None = None, document_style_css: str = "", math_engine: str = "katex", ) -> str: label = html.escape(language or code_path.suffix.lstrip(".") or "text") language_class = f" language-{html.escape(language)}" if language else "" highlighted = self._highlight_code(source, language, line_anchors=True) title = html.escape(code_path.name) body = ( f"

{title}

" '
' f'
{label}
' f'
{highlighted}
' "
" ) return self._wrap_html( body=body, title=code_path.name, theme=theme, font_scale=font_scale, wheel_scroll_speed=wheel_scroll_speed, document_width_scale=document_width_scale, document_font_family=document_font_family, document_font_size=document_font_size, document_style_css=document_style_css, math_engine=math_engine, ) def wrap_body_for_display( self, body: str, title: str, theme: str = "light", font_scale: float = 1.0, wheel_scroll_speed: float = 1.0, document_width_scale: float = 1.0, document_font_family: str = "", document_font_size: int | None = None, document_style_css: str = "", math_engine: str = "katex", ) -> str: return self._wrap_html( body=body, title=title, theme=theme, font_scale=font_scale, wheel_scroll_speed=wheel_scroll_speed, document_width_scale=document_width_scale, document_font_family=document_font_family, document_font_size=document_font_size, document_style_css=document_style_css, math_engine=math_engine, ) def _render_fence( self, tokens: list[Token], idx: int, options: dict[str, Any], env: dict[str, Any], ) -> str: token = tokens[idx] language = token.info.strip().split(maxsplit=1)[0] if token.info else "" normalized_language = language.lower() if normalized_language == "mermaid": return ( '
' '
mermaid
' f'
{html.escape(token.content)}
' "
\n" ) if normalized_language in {"math", "tex", "latex"}: return f'
$$\n{html.escape(token.content)}\n$$
\n' language_class = f" language-{html.escape(language)}" if language else "" code = self._highlight_code(token.content, language) label = html.escape(language or "text") return ( f'
' f'
{label}
' f'
{code}
' f"
\n" ) def _render_code_block( self, tokens: list[Token], idx: int, options: dict[str, Any], env: dict[str, Any], ) -> str: token = tokens[idx] return ( '
' '
'
            f"{html.escape(token.content)}"
            "
" "
\n" ) def _parse_math_block( self, state: StateBlock, start_line: int, end_line: int, silent: bool, ) -> bool: if state.is_code_block(start_line): return False start = state.bMarks[start_line] + state.tShift[start_line] opening = state.src[start : state.eMarks[start_line]].strip() delimiters = {"$$": "$$", r"\[": r"\]"} closing = delimiters.get(opening) if closing is None: return False close_line = start_line + 1 while close_line < end_line: line_start = state.bMarks[close_line] + state.tShift[close_line] line = state.src[line_start : state.eMarks[close_line]].strip() if line == closing: break close_line += 1 else: return False if silent: return True token = state.push("math_block", "math", 0) token.content = state.getLines( start_line + 1, close_line, state.sCount[start_line], False, ) token.markup = opening token.map = [start_line, close_line + 1] state.line = close_line + 1 return True def _parse_math_inline(self, state: StateInline, silent: bool) -> bool: start = state.pos source = state.src if source.startswith("$$", start): opening = closing = "$$" elif source.startswith(r"\(", start): opening, closing = r"\(", r"\)" elif source.startswith("$", start): opening = closing = "$" else: return False content_start = start + len(opening) content_end = self._find_math_closing_delimiter( source, closing, content_start, state.posMax, ) if content_end < 0 or content_end == content_start: return False if "\n" in source[content_start:content_end]: return False if not silent: token = state.push("math_inline", "math", 0) token.content = source[content_start:content_end] token.markup = opening state.pos = content_end + len(closing) return True def _find_math_closing_delimiter( self, source: str, delimiter: str, start: int, end: int, ) -> int: position = start while position < end: position = source.find(delimiter, position, end) if position < 0: return -1 if delimiter == "$" and ( (position > start and source[position - 1] == "$") or (position + 1 < end and source[position + 1] == "$") ): position += 1 continue backslashes = 0 cursor = position - 1 while cursor >= start and source[cursor] == "\\": backslashes += 1 cursor -= 1 if backslashes % 2 == 0: return position position += len(delimiter) return -1 def _render_math_block( self, tokens: list[Token], idx: int, options: dict[str, Any], env: dict[str, Any], ) -> str: token = tokens[idx] opening = token.markup or "$$" closing = r"\]" if opening == r"\[" else "$$" content = html.escape(token.content.rstrip("\n")) return f'
{opening}\n{content}\n{closing}
\n' def _render_math_inline( self, tokens: list[Token], idx: int, options: dict[str, Any], env: dict[str, Any], ) -> str: token = tokens[idx] opening = token.markup or "$" closing = r"\)" if opening == r"\(" else opening class_name = "math-display" if opening == "$$" else "math-inline" content = html.escape(token.content) return f'{opening}{content}{closing}' def _render_image( self, tokens: list[Token], idx: int, options: dict[str, Any], env: dict[str, Any], ) -> str: token = tokens[idx] src = token.attrGet("src") or "" title = token.attrGet("title") or "" alt = token.content or title or Path(src).name kind = media_kind(src) resolved_src = self._resolve_local_media_src(src, env) escaped_src = html.escape(resolved_src, quote=True) escaped_alt = html.escape(alt, quote=True) mime_type = media_mime_type(src) source_type = f' type="{html.escape(mime_type, quote=True)}"' if mime_type else "" caption = f"
{html.escape(alt)}
" if alt else "" if kind == "audio": return ( f'
' f'" f"{caption}
" ) if kind == "video": if is_qt_video_player_url(resolved_src): player_href = html.escape(f"{resolved_src}?mdhelper-open=player-new-tab", quote=True) external_href = html.escape(f"{resolved_src}?mdhelper-open=external", quote=True) return ( f'" ) return ( f'
' f'" f"{caption}
" ) if kind == "gif": return ( '
' f'{escaped_alt}' f"{caption}
" ) return f'{escaped_alt}' def _render_link_open( self, tokens: list[Token], idx: int, options: dict[str, Any], env: dict[str, Any], ) -> str: token = tokens[idx] href = token.attrGet("href") or "" resolved_href = self._resolve_local_href(href, env) if resolved_href != href: token.attrSet("href", resolved_href) return self.markdown.renderer.renderToken(tokens, idx, options, env) def _resolve_local_media_src(self, src: str, env: dict[str, Any]) -> str: if src.startswith("#"): return src parsed = urlsplit(src) if parsed.scheme: return src markdown_path_value = env.get("path") if not markdown_path_value: return src local_path = (Path(str(markdown_path_value)).parent / unquote(parsed.path)).resolve() if not local_path.exists(): return src uri = local_path.as_uri() if parsed.fragment: uri = f"{uri}#{parsed.fragment}" return uri def _resolve_local_href(self, href: str, env: dict[str, Any]) -> str: if href.startswith("#"): return href parsed = urlsplit(href) if parsed.scheme: return href markdown_path_value = env.get("path") if not markdown_path_value: return href local_path = (Path(str(markdown_path_value)).parent / unquote(parsed.path)).resolve() if not local_path.exists(): return href uri = local_path.as_uri() if parsed.fragment: uri = f"{uri}#{parsed.fragment}" return uri def _highlight_code(self, code: str, language: str, line_anchors: bool = False) -> str: normalized = language.lower() if normalized in {"pseudocode", "pseudo"}: highlighted = self._highlight_pseudocode(code) return self._add_line_anchors(highlighted) if line_anchors else highlighted try: lexer = get_lexer_by_name(normalized) if normalized else TextLexer() except ClassNotFound: lexer = TextLexer() highlighted = highlight(code, lexer, self.formatter) return self._add_line_anchors(highlighted) if line_anchors else highlighted def _add_line_anchors(self, highlighted: str) -> str: lines = highlighted.splitlines(keepends=True) return "".join( f'{line}' for index, line in enumerate(lines, start=1) ) def _highlight_pseudocode(self, code: str) -> str: escaped = html.escape(code) keywords = ( "BEGIN", "END", "SET", "FOR", "TO", "DO", "IF", "THEN", "ELSE", "RETURN", "WHILE", "REPEAT", "UNTIL", ) def replace_keyword(match: re.Match[str]) -> str: return f'{match.group(0)}' pattern = r"\b(" + "|".join(keywords) + r")\b" return re.sub(pattern, replace_keyword, escaped) def _add_heading_ids(self, state: Any) -> None: headings = state.env.setdefault('headings', []) for token, heading in heading_tokens(state.tokens): token.attrSet('id', heading.slug) if isinstance(headings, list): headings.append({'level': heading.level, 'title': heading.title, 'slug': heading.slug}) def _convert_admonitions(self, state: Any) -> None: labels = { "NOTE": "注意", "TIP": "提示", "IMPORTANT": "重要", "WARNING": "警告", "CAUTION": "小心", } tokens = state.tokens for index, token in enumerate(tokens): if token.type != "blockquote_open": continue inline_index = self._first_inline_in_blockquote(tokens, index) if inline_index is None: continue inline = tokens[inline_index] marker = re.match( r"^\[!(NOTE|TIP|IMPORTANT|WARNING|CAUTION)\]\s*([^\n]*)(?:\n(.*))?$", inline.content, re.DOTALL, ) if not marker: continue kind = marker.group(1) title = marker.group(2).strip() or labels[kind] rest = (marker.group(3) or "").lstrip() close_index = self._matching_close_index(tokens, index, "blockquote_close") if close_index is None: continue token.tag = "aside" token.attrJoin("class", f"admonition admonition-{kind.lower()}") tokens[close_index].tag = "aside" title_node = Token("html_inline", "", 0) title_node.content = f'{html.escape(title)}' children = [title_node] if rest: break_node = Token("html_inline", "", 0) break_node.content = "
" text = Token("text", "", 0) text.content = rest children.extend([break_node, text]) inline.content = f"{title}\n{rest}" if rest else title inline.children = children def _convert_task_lists(self, state: Any) -> None: tokens = state.tokens for index, token in enumerate(tokens): if token.type != "inline" or not token.children: continue first_child = token.children[0] if first_child.type != "text": continue marker = re.match(r"^\[([ xX])\]\s+", first_child.content) if not marker: continue list_item = self._nearest_open_token(tokens, index, "list_item_open") if list_item is None: continue bullet_list = self._nearest_open_token(tokens, index, "bullet_list_open") if bullet_list is not None: bullet_list.attrJoin("class", "task-list") checked = marker.group(1).lower() == "x" list_item.attrJoin("class", "task-list-item") checkbox = Token("html_inline", "", 0) checked_attr = " checked" if checked else "" checkbox.content = ( ' " ) first_child.content = first_child.content[marker.end() :] token.children.insert(0, checkbox) def _first_inline_in_blockquote(self, tokens: list[Token], start_index: int) -> int | None: start_level = tokens[start_index].level for index in range(start_index + 1, len(tokens)): token = tokens[index] if token.type == "blockquote_close" and token.level == start_level: return None if token.type == "inline": return index return None def _matching_close_index(self, tokens: list[Token], start_index: int, close_type: str) -> int | None: start_level = tokens[start_index].level for index in range(start_index + 1, len(tokens)): token = tokens[index] if token.type == close_type and token.level == start_level: return index return None def _nearest_open_token(self, tokens: list[Token], start_index: int, token_type: str) -> Token | None: inline_level = tokens[start_index].level for token in reversed(tokens[:start_index]): if token.type == token_type and token.level < inline_level: return token return None def _wrap_html( self, body: str, title: str, theme: str, font_scale: float, wheel_scroll_speed: float, document_width_scale: float, document_font_family: str, document_font_size: int | None, document_style_css: str, math_engine: str, ) -> str: css_path = self.resources_dir / "reader.css" js_path = self.resources_dir / "reader.js" css_stat, js_stat = css_path.stat(), js_path.stat() css = _resource_text(css_path, css_stat.st_mtime_ns, css_stat.st_size) js = _resource_text(js_path, js_stat.st_mtime_ns, js_stat.st_size) # Include raw HTML math delimiters too: wrap_body_for_display is public. needs_math = bool(re.search(r'math-(?:inline|block|display)|\$|\\[\[(]', body)) math_assets = self._math_assets(math_engine) if needs_math else {"css": "", "js": "", "config": ""} needs_mermaid = bool(re.search(r'class=[\"\'][^\"\']*\bmermaid\b', body)) mermaid_script = self._script_tag(self._resource_uri("vendor/mermaid/mermaid.min.js")) if needs_mermaid else "" pygments_css = _highlight_css() escaped_title = html.escape(title) escaped_theme = html.escape(theme, quote=True) escaped_math_engine = html.escape(self._normalized_math_engine(math_engine), quote=True) try: normalized_wheel_speed = max(0.5, min(3.0, float(wheel_scroll_speed))) except (TypeError, ValueError): normalized_wheel_speed = 1.0 try: normalized_width_scale = min((1.0, 1.25, 1.5, 1.75, 2.0), key=lambda candidate: abs(candidate - float(document_width_scale))) except (TypeError, ValueError): normalized_width_scale = 1.0 paper_width_px = int(round(794 * normalized_width_scale)) fallback_font_size = int(round(max(0.8, min(font_scale, 1.6)) * 16)) font_size = max(12, min(int(document_font_size or fallback_font_size), 28)) font_family = self._css_font_family(document_font_family) escaped_font_family = html.escape(font_family, quote=False) from .reader_decoration import MARKER, DYNAMIC_MARKER, wrap_decoration_text leaf_decorations = MARKER in document_style_css if leaf_decorations: body = wrap_decoration_text(body) reader_shell = self._reader_shell_html(body) if leaf_decorations: reader_shell = reader_shell.replace('
{escaped_title} {math_assets["css"]} {reader_shell} {math_assets["js"]} {mermaid_script} """ def _reader_shell_html(self, body: str) -> str: return f'
\n
\n{body}\n
\n
' def _resource_uri(self, relative_path: str) -> str: path = self.resources_dir / relative_path if not path.exists(): return "" return path.as_uri() def _script_tag(self, uri: str) -> str: if not uri: return "" return f'' def _stylesheet_tag(self, uri: str) -> str: if not uri: return "" return f'' def _css_font_family(self, font_family: str) -> str: name = font_family.strip() if not name: return '"Segoe UI", "Microsoft YaHei UI", "Microsoft YaHei", Arial, sans-serif' escaped_name = name.replace("\\", "\\\\").replace('"', '\\"') return f'"{escaped_name}", "Microsoft YaHei UI", Arial, sans-serif' def _math_assets(self, math_engine: str) -> dict[str, str]: normalized = self._normalized_math_engine(math_engine) if normalized == "mathjax": config = ( "window.MathJax = {" "tex: {inlineMath: [['$', '$'], ['\\\\(', '\\\\)']], " "displayMath: [['$$', '$$'], ['\\\\[', '\\\\]']], processEscapes: true}," "svg: {fontCache: 'none'}" "};" ) return { "css": "", "config": config, "js": self._script_tag(self._resource_uri("vendor/mathjax/tex-svg-full.js")), } return { "css": self._stylesheet_tag(self._resource_uri("vendor/katex/katex.min.css")), "config": "", "js": "\n".join( [ self._script_tag(self._resource_uri("vendor/katex/katex.min.js")), self._script_tag(self._resource_uri("vendor/katex/auto-render.min.js")), ] ), } def _normalized_math_engine(self, math_engine: str) -> str: return "mathjax" if str(math_engine).lower() == "mathjax" else "katex"