Link Preview Module¶

def add_preview_static_resources(config: MkDocsConfig) -> None:
	"""Register preview JS/CSS on the MkDocs config (call only when enabled)."""
	if "js/preview.js" not in config["extra_javascript"]:
		config["extra_javascript"].append("js/preview.js")
	if "css/preview.css" not in config["extra_css"]:
		config["extra_css"].append("css/preview.css")

def copy_preview_static_assets(static_dir: str, config: MkDocsConfig) -> None:
	"""Copy preview.js / preview.css into the site directory."""
	js_output_dir = os.path.join(config["site_dir"], "js")
	os.makedirs(js_output_dir, exist_ok=True)
	shutil.copy(os.path.join(static_dir, "preview.js"), js_output_dir)

	css_output_dir = os.path.join(config["site_dir"], "css")
	os.makedirs(css_output_dir, exist_ok=True)
	shutil.copy(os.path.join(static_dir, "preview.css"), css_output_dir)

def create_preview_markdown(
	markdown_extensions: Any = None,
	mdx_configs: dict[str, Any] | None = None,
):
	"""Create a Python-Markdown instance aligned with the site config.

	Loads extensions incrementally so one broken/plugin-only extension cannot
	force a full fallback to the basic set.
	"""
	import markdown

	exts, configs = prepare_preview_markdown_config(markdown_extensions, mdx_configs)
	working: list[str] = list(_FALLBACK_EXTENSIONS)
	md = markdown.Markdown(extensions=working)

	for ext in exts:
		if ext in working:
			continue
		trial = [*working, ext]
		trial_configs = {k: configs[k] for k in trial if k in configs}
		try:
			md = markdown.Markdown(extensions=trial, extension_configs=trial_configs)
		except (
			ImportError,
			ValueError,
			TypeError,
			AttributeError,
			KeyError,
			OSError,
		) as exc:
			logger.debug("Skipping markdown extension %s for preview: %s", ext, exc)
			continue
		working = trial

	if working != list(_FALLBACK_EXTENSIONS):
		logger.info(
			"Preview markdown extensions: %s",
			", ".join(working),
		)
	return md

def decode_fragment(fragment: str) -> str:
	"""Normalize a URL fragment to decoded Unicode (no leading ``#``)."""
	frag = (fragment or "").lstrip("#")
	if not frag:
		return ""
	try:
		return unquote(frag)
	except (ValueError, TypeError):
		return frag

def excerpt_html(
	section_md: str,
	page_url: str,
	site_base: str,
	*,
	md: Any | None = None,
	markdown_extensions: Any = None,
	mdx_configs: dict[str, Any] | None = None,
	source_file: Any | None = None,
	files: Any | None = None,
) -> str:
	"""Build a sanitized rich HTML excerpt from section markdown.

	When ``md`` or site extension config is provided, rendering follows the
	MkDocs/Material markdown stack (minus unsafe/noisy extensions).
	"""
	converter = md
	if converter is None:
		converter = create_preview_markdown(markdown_extensions, mdx_configs)
	else:
		converter.reset()
	raw = converter.convert(section_md)
	raw = _rewrite_html_urls(
		raw,
		page_url,
		site_base,
		source_file=source_file,
		files=files,
	)
	return sanitize_preview_html(raw)

def excerpt_plain(section_md: str, max_chars: int) -> str:
	"""Plain-text excerpt: prose + fenced code as text, truncated."""
	parts: list[str] = []
	in_fence = False
	fence_lines: list[str] = []
	for line in section_md.splitlines():
		if _FENCE_RE.match(line.strip()):
			if in_fence:
				parts.append("\n".join(fence_lines))
				fence_lines = []
				in_fence = False
			else:
				in_fence = True
			continue
		if in_fence:
			fence_lines.append(line)
			continue
		stripped = line.strip()
		if not stripped or stripped.startswith("#"):
			continue
		parts.append(strip_markdown_inline(stripped))
	if fence_lines:
		parts.append("\n".join(fence_lines))
	text = "\n\n".join(p for p in parts if p)
	if len(text) > max_chars:
		return text[: max_chars - 1].rstrip() + "…"
	return text

def extract_summary(
	meta: dict[str, Any],
	body: str,
	max_chars: int,
) -> str:
	"""Summary priority: frontmatter description → summary → first paragraph."""
	for key in ("description", "summary"):
		val = meta.get(key)
		if isinstance(val, str) and val.strip():
			text = strip_markdown_inline(val.strip())
			if len(text) > max_chars:
				return text[: max_chars - 1].rstrip() + "…"
			return text
	return first_prose_paragraph(body, max_chars)

def extract_title_from_page(
	meta: dict[str, Any],
	body: str,
	fallback: str,
) -> str:
	"""Resolve a display title from frontmatter, first H1, or fallback."""
	title = meta.get("title")
	if isinstance(title, str) and title.strip():
		return title.strip()
	m = _HEADING_RE.search(body)
	if m and len(m.group(1)) == 1:
		return strip_markdown_inline(m.group(2))
	return fallback

def first_prose_paragraph(body: str, max_chars: int) -> str:
	"""Extract the first non-empty prose paragraph from markdown body.

	Skips ATX headings, blockquotes, tables, lists, and Material admonition /
	details / tab markers (``!!!``, ``???``, ``===``) plus their indented bodies.
	"""
	# Drop fenced code blocks so we don't preview code as summary.
	without_code = _CODE_FENCE_BLOCK_RE.sub("", body)
	chunks: list[str] = []
	buf: list[str] = []
	skip_indented_block = False
	for line in without_code.splitlines():
		stripped = line.strip()
		if not stripped:
			if buf:
				chunks.append(" ".join(buf))
				buf = []
			skip_indented_block = False
			continue
		# Admonition / details / tab openers and indented continuation lines.
		if stripped.startswith(("!!!", "???", "===")):
			if buf:
				chunks.append(" ".join(buf))
				buf = []
			skip_indented_block = True
			continue
		if skip_indented_block and line.startswith(("    ", "\t")):
			continue
		skip_indented_block = False
		if stripped.startswith(("#", ">", "|")):
			if buf:
				chunks.append(" ".join(buf))
				buf = []
			continue
		if stripped.startswith(("- ", "* ")) or re.match(r"^\d+\.\s", stripped):
			if buf:
				chunks.append(" ".join(buf))
				buf = []
			continue
		buf.append(stripped)
	if buf:
		chunks.append(" ".join(buf))

	for chunk in chunks:
		plain = strip_markdown_inline(chunk)
		if plain and not plain.startswith(("!!!", "???", "===")):
			if len(plain) > max_chars:
				return plain[: max_chars - 1].rstrip() + "…"
			return plain
	return ""

def inject_preview_script(
	output: str,
	config: MkDocsConfig,
	preview_config: dict[str, Any],
	*,
	graph_enabled: bool = False,
) -> str:
	"""Inject ``window.preview_options`` before ``</body>``."""
	base_path = _base_path_from_config(config)
	options = {
		"base_path": base_path,
		"mode": preview_config.get("mode", "summary"),
		"delay_ms": int(preview_config.get("delay_ms", 300)),
		"mobile": bool(preview_config.get("mobile", False)),
		"graph_enabled": graph_enabled,
	}
	payload = json.dumps(options)
	options_script = f"<script>window.preview_options = {payload};</script>"
	if "</body>" in output:
		return output.replace("</body>", f"{options_script}</body>")
	return output

def prepare_preview_markdown_config(
	markdown_extensions: Any = None,
	mdx_configs: dict[str, Any] | None = None,
) -> tuple[list[str], dict[str, Any]]:
	"""Filter site markdown extensions for hover-preview rendering.

	Reuses the MkDocs/Material extension stack where practical, but drops
	``toc`` (permalink clutter), ``pymdownx.snippets`` (arbitrary includes),
	and plugin-only extensions such as mkdocstrings.
	"""
	raw_exts: list[Any] = list(markdown_extensions or [])
	configs = dict(mdx_configs or {})
	kept: list[str] = []
	kept_names: set[str] = set()
	for ext in raw_exts:
		name = _normalize_extension_name(ext)
		if name is None or not _is_preview_safe_extension(name):
			if name:
				configs.pop(name, None)
			continue
		kept.append(name)
		kept_names.add(name)

	if not kept:
		kept = list(_FALLBACK_EXTENSIONS)
		kept_names = set(kept)
	else:
		has_superfences = "pymdownx.superfences" in kept_names
		for required in _FALLBACK_EXTENSIONS:
			if required in kept_names:
				continue
			if required == "fenced_code" and has_superfences:
				continue
			kept.append(required)
			kept_names.add(required)

	configs = {k: v for k, v in configs.items() if k in kept_names}
	return kept, configs

def resolve_section_markdown(
	sections: dict[str, tuple[str, str]],
	frag: str,
) -> tuple[str, str]:
	"""Return ``(heading_text, section_md)`` for a fragment.

	If the section has no extractable prose, descend into the first nested
	child with content; otherwise return the hierarchical section body (which
	already includes nested headings when split with same-or-higher rules).
	"""
	if frag not in sections:
		return "", ""
	heading_text, section_md = sections[frag]
	if _section_has_prose(section_md):
		return heading_text, section_md
	nested = _split_sections(section_md)
	for sid, _child_text, child_md in nested:
		if not sid:
			continue
		if _section_has_prose(child_md):
			return heading_text, child_md
	# Keep hierarchical body even if prose extractor is empty (e.g. only code).
	return heading_text, section_md

def sanitize_preview_html(raw: str) -> str:
	"""Sanitize HTML to the preview allow-list."""
	parser = _PreviewHTMLSanitizer()
	try:
		parser.feed(raw)
		parser.close()
	except (ValueError, TypeError, AssertionError):
		return html.escape(raw)
	return parser.result()

def slugify_heading(text: str) -> str:
	"""Slugify a heading title to match Material / pymdownx TOC ids."""
	fn = _get_slugify()
	return fn(text, "-")

def strip_markdown_inline(text: str) -> str:
	"""Remove common inline markdown markers for plain-text summaries."""
	text = _MD_IMAGE_RE.sub(r"\1", text)
	text = _MD_LINK_RE.sub(r"\1", text)
	text = _MD_BOLD_RE.sub(r"\2", text)
	text = _MD_ITALIC_RE.sub(r"\2", text)
	text = _MD_INLINE_CODE_RE.sub(r"\1", text)
	text = _MD_HTML_TAG_RE.sub("", text)
	return re.sub(r"\s+", " ", text).strip()

def write_previews_file(
	data: dict[str, dict[str, Any]],
	config: MkDocsConfig,
) -> None:
	"""Write ``site/previews/previews.json``."""
	output_dir = os.path.join(config["site_dir"], "previews")
	os.makedirs(output_dir, exist_ok=True)
	path = os.path.join(output_dir, "previews.json")
	with open(path, "w", encoding="utf-8") as f:
		json.dump(data, f, ensure_ascii=False)
	logger.info(f"Wrote previews to {path}")