@windcoder/astro-theme-orchid 0.0.0-stage → 0.1.0

package/src/plugins/rehype-diagram.ts

@@ -0,0 +1,218 @@
+/**
+ * rehype 图表插件（M3b-b4，移植自 orchid-blog）
+ *
+ * - rehypeMermaid：div.mermaid-container → 构建期 beautiful-mermaid 渲染
+ *   light/dark 双静态 SVG（div.mermaid-svg-light/-dark 包裹，CSS 按主题显隐），
+ *   失败降级 .mermaid-error + pre.mermaid-fallback-code 源码展示，零客户端运行时
+ * - rehypePlantuml：div.plantuml-wrapper → img.plantuml-image（data-light-src/-dark-src），
+ *   客户端 plantuml-theme-switch.js 按主题切换 src、加载失败展示重试
+ * - rehypeDiagramPanZoom：为含图表的文章注入 diagram-panzoom.js（控制栏/拖拽/全屏）
+ *
+ * 偏差（相对 orchid）：
+ * - 客户端脚本改 readFileSync 模块顶层读入，不依赖 Vite ?raw 管线
+ * - panzoom 脚本仅对实际含图表的 tree 注入（orchid 无条件注入）
+ * - plantuml wrapper 不再生成随机 id（保证构建产物可复现）
+ */
+
+import { readFileSync } from "node:fs";
+import { renderMermaidSVG, THEMES } from "beautiful-mermaid";
+
+type Transformer = (tree: any, file: any) => void;
+
+/** 深度遍历辅助（与 rehype.ts 内 visit 同风格），fn 返回 'skip' 跳过子树 */
+function visit(node: any, fn: (n: any) => void | "skip") {
+	const children = node.children;
+	if (!Array.isArray(children)) return;
+	for (const child of children) {
+		if (fn(child) !== "skip") visit(child, fn);
+	}
+}
+
+const panzoomScript = readFileSync(
+	new URL("./scripts/diagram-panzoom.js", import.meta.url),
+	"utf8",
+);
+
+const plantumlSwitchScript = readFileSync(
+	new URL("./scripts/plantuml-theme-switch.js", import.meta.url),
+	"utf8",
+);
+
+/** 本 rehype tree 已注入过 panzoom 脚本（每篇文档最多一次） */
+const panzoomInjected = new WeakSet<object>();
+
+function hasClass(node: any, name: string): boolean {
+	const cls = node.properties?.className;
+	return Array.isArray(cls) && cls.includes(name);
+}
+
+function injectScript(tree: any, code: string) {
+	tree.children.push({
+		type: "element",
+		tagName: "script",
+		properties: {},
+		children: [{ type: "text", value: code }],
+	});
+}
+
+function injectPanzoom(tree: any) {
+	if (panzoomInjected.has(tree)) return;
+	panzoomInjected.add(tree);
+	injectScript(tree, panzoomScript);
+}
+
+export interface MermaidOptions {
+	lightTheme: string;
+	darkTheme: string;
+}
+
+export function rehypeMermaid(options: MermaidOptions): Transformer {
+	return (tree) => {
+		let found = false;
+		visit(tree, (node) => {
+			if (node.type !== "element" || node.tagName !== "div") return;
+			if (!hasClass(node, "mermaid-container")) return;
+			const code = String(node.properties?.["data-mermaid-code"] ?? "");
+			const wrapper: any = {
+				type: "element",
+				tagName: "div",
+				properties: { className: ["diagram-wrapper", "mermaid-wrapper"] },
+				children: [],
+			};
+			try {
+				const lightSvg = renderMermaidSVG(code, {
+					...THEMES[options.lightTheme],
+					padding: 20,
+				});
+				const darkSvg = renderMermaidSVG(code, {
+					...THEMES[options.darkTheme],
+					padding: 20,
+				});
+				wrapper.children.push(
+					{
+						type: "element",
+						tagName: "div",
+						properties: { className: ["mermaid-svg-light"] },
+						children: [{ type: "raw", value: lightSvg }],
+					},
+					{
+						type: "element",
+						tagName: "div",
+						properties: { className: ["mermaid-svg-dark"] },
+						children: [{ type: "raw", value: darkSvg }],
+					},
+				);
+				node.tagName = "div";
+				node.properties = {
+					className: ["diagram-container", "mermaid-diagram-container"],
+				};
+				node.children = [wrapper];
+			} catch (err) {
+				const message = err instanceof Error ? err.message : String(err);
+				const preview = code.length > 200 ? `${code.slice(0, 200)}…` : code;
+				console.error(`[theme] Mermaid 渲染失败（${message}）：\n${preview}`);
+				node.properties = {
+					className: [
+						"diagram-container",
+						"mermaid-diagram-container",
+						"mermaid-error",
+					],
+				};
+				node.children = [
+					{
+						type: "element",
+						tagName: "p",
+						properties: {},
+						children: [
+							{ type: "text", value: "Mermaid 图表渲染失败，已展示源码：" },
+						],
+					},
+					{
+						type: "element",
+						tagName: "pre",
+						properties: { className: ["mermaid-fallback-code"] },
+						children: [
+							{
+								type: "element",
+								tagName: "code",
+								properties: {},
+								children: [{ type: "text", value: code }],
+							},
+						],
+					},
+				];
+			}
+			found = true;
+			return "skip";
+		});
+		if (found) injectPanzoom(tree);
+	};
+}
+
+export function rehypePlantuml(): Transformer {
+	return (tree) => {
+		let found = false;
+		visit(tree, (node) => {
+			if (node.type !== "element" || node.tagName !== "div") return;
+			if (!hasClass(node, "plantuml-wrapper")) return;
+			const lightSrc = String(node.properties?.["data-light-src"] ?? "");
+			const darkSrc = String(node.properties?.["data-dark-src"] ?? lightSrc);
+			const alt = String(
+				node.properties?.["data-plantuml-alt"] || "PlantUML diagram",
+			);
+			const img = {
+				type: "element",
+				tagName: "img",
+				properties: {
+					className: ["plantuml-image"],
+					src: lightSrc,
+					alt,
+					"data-light-src": lightSrc,
+					"data-dark-src": darkSrc,
+					loading: "lazy",
+					decoding: "async",
+				},
+				children: [],
+			};
+			node.tagName = "div";
+			node.properties = {
+				className: ["diagram-container", "plantuml-diagram-container"],
+			};
+			node.children = [
+				{
+					type: "element",
+					tagName: "div",
+					properties: { className: ["plantuml-wrapper"] },
+					children: [img],
+				},
+			];
+			found = true;
+			return "skip";
+		});
+		if (found) {
+			injectPanzoom(tree);
+			// PlantUML 主题切换/失败重试脚本（与 panzoom 互相独立，各自防重入）
+			injectScript(tree, plantumlSwitchScript);
+		}
+	};
+}
+
+/** 单独挂载时的兜底：扫描 tree 中任意图表容器并注入 panzoom 脚本 */
+export function rehypeDiagramPanZoom(): Transformer {
+	return (tree) => {
+		if (panzoomInjected.has(tree)) return;
+		let found = false;
+		visit(tree, (node) => {
+			if (found) return "skip";
+			if (
+				node.type === "element" &&
+				node.tagName === "div" &&
+				hasClass(node, "diagram-container")
+			) {
+				found = true;
+				return "skip";
+			}
+		});
+		if (found) injectPanzoom(tree);
+	};
+}

package/src/plugins/rehype-email.ts

@@ -0,0 +1,75 @@
+/**
+ * 邮箱防爬（M3b-b4，移植自 orchid-blog）
+ *
+ * 构建期把 mailto: 链接的地址编码进 data-encoded-email，href 置为 '#'，
+ * 并内联一段 onclick 解码脚本：点击时还原地址 → 回写 href → 延时补一次点击。
+ * 爬虫不执行点击，拿不到明文邮箱；解码逻辑随属性内联，无需额外客户端资源。
+ *
+ * 偏差说明：orchid 会向 head 注入占位样式，本主题统一并入 global.css
+ * （a[data-encoded-email] 光标提示），插件保持纯 DOM 变换。
+ */
+
+type Transformer = (tree: any, file: any) => void;
+
+/** 深度遍历辅助（与 rehype.ts 内 visit 同风格），fn 返回 'skip' 跳过子树 */
+function visit(node: any, fn: (n: any) => void | "skip") {
+	const children = node.children;
+	if (!Array.isArray(children)) return;
+	for (const child of children) {
+		if (fn(child) !== "skip") visit(child, fn);
+	}
+}
+
+export interface EmailProtectionOptions {
+	/** base64：兼容性最好（btoa 仅支持 Latin1，超集地址跳过保护保持原样）；rot13：零 API 依赖 */
+	method: "base64" | "rot13";
+}
+
+const encodeBase64 = (value: string): string | null => {
+	try {
+		// Buffer 在 Node 构建期可用；btoa 遇非 Latin1 会抛错，统一 try/catch 兜底
+		return typeof Buffer !== "undefined"
+			? Buffer.from(value, "utf8").toString("base64")
+			: btoa(value);
+	} catch {
+		return null;
+	}
+};
+
+const encodeRot13 = (value: string): string =>
+	value.replace(/[a-zA-Z]/g, (c) => {
+		const base = c <= "Z" ? 65 : 97;
+		return String.fromCharCode(((c.charCodeAt(0) - base + 13) % 26) + base);
+	});
+
+/** 点击时还原地址并补一次点击（压缩成单行内联，this 为链接元素自身） */
+const ONCLICK_TEMPLATE = (method: "base64" | "rot13") => {
+	const decode =
+		method === "base64"
+			? "function(e){return decodeURIComponent(escape(atob(e)))}"
+			: 'function(e){return e.replace(/[a-zA-Z]/g,function(c){var b=c.charCodeAt(0),s=c<="Z"?65:97;return String.fromCharCode((b-s+13)%26+s)})}';
+	return `(function(){var e=this.getAttribute('data-encoded-email');if(!e)return;this.removeAttribute('data-encoded-email');this.setAttribute('href','mailto:'+(${decode})(e));var a=this;setTimeout(function(){a.click()},0)}).call(this);return false`
+		.replace(/\s+/g, " ")
+		.trim();
+};
+
+export function rehypeEmailProtection(
+	options: EmailProtectionOptions,
+): Transformer {
+	const encode = options.method === "base64" ? encodeBase64 : encodeRot13;
+	const onclick = ONCLICK_TEMPLATE(options.method);
+	return (tree) => {
+		visit(tree, (node) => {
+			if (node.type !== "element" || node.tagName !== "a") return;
+			const href = String(node.properties?.href ?? "");
+			if (!href.toLowerCase().startsWith("mailto:")) return;
+			const address = href.slice("mailto:".length);
+			const encoded = encode(address);
+			// 编码失败（非 Latin1 的 base64 场景）保持原链接，不做半吊子保护
+			if (!encoded) return;
+			node.properties["data-encoded-email"] = encoded;
+			node.properties.href = "#";
+			node.properties.onclick = onclick;
+		});
+	};
+}

package/src/plugins/rehype-github-card.ts

@@ -0,0 +1,114 @@
+/**
+ * ::github{repo="owner/repo"} → GitHub 仓库卡片（A2，移植自参考模板
+ * rehype-component-github-card）
+ *
+ * remarkDirectives 已把 leaf 指令转成 <github repo="…"> 标签；本插件将其替换为
+ * 卡片结构 + 内联脚本：客户端 fetch api.github.com 填充描述/stars/forks/
+ * license/头像；fetch-waiting（骨架 pulsate 动画）→ 完成态 / fetch-error 两态。
+ * 数据获取发生在读者浏览器端，构建期零请求。
+ */
+import { h } from "hastscript";
+
+function githubCard(properties: any, children: any[]): any {
+	if (Array.isArray(children) && children.length !== 0)
+		return h(
+			"div",
+			{ class: "hidden" },
+			`Invalid directive. ("github" directive must be leaf type '::github{repo="owner/repo"}')`,
+		);
+
+	const repo = String(properties.repo ?? "");
+	if (!repo.includes("/"))
+		return h(
+			"div",
+			{ class: "hidden" },
+			`Invalid repository. ("repo" attribute must be in the format "owner/repo")`,
+		);
+
+	// 每卡片随机 id 防同页多卡片串数据（碰撞概率可忽略）
+	const cardUuid = `GC${Math.random().toString(36).slice(-6)}`;
+
+	const nAvatar = h(`div#${cardUuid}-avatar`, { class: "gc-avatar" });
+	const nLanguage = h(
+		`span#${cardUuid}-language`,
+		{ class: "gc-language" },
+		"Waiting...",
+	);
+
+	const nTitle = h("div", { class: "gc-titlebar" }, [
+		h("div", { class: "gc-titlebar-left" }, [
+			h("div", { class: "gc-owner" }, [
+				nAvatar,
+				h("div", { class: "gc-user" }, repo.split("/")[0]),
+			]),
+			h("div", { class: "gc-divider" }, "/"),
+			h("div", { class: "gc-repo" }, repo.split("/")[1]),
+		]),
+		h("div", { class: "github-logo" }),
+	]);
+
+	const nDescription = h(
+		`div#${cardUuid}-description`,
+		{ class: "gc-description" },
+		"Waiting for api.github.com...",
+	);
+
+	const nStars = h(`div#${cardUuid}-stars`, { class: "gc-stars" }, "00K");
+	const nForks = h(`div#${cardUuid}-forks`, { class: "gc-forks" }, "0K");
+	const nLicense = h(`div#${cardUuid}-license`, { class: "gc-license" }, "0K");
+
+	const nScript = h(
+		`script#${cardUuid}-script`,
+		{ type: "text/javascript" },
+		`
+      fetch('https://api.github.com/repos/${repo}', { referrerPolicy: "no-referrer" }).then(response => response.json()).then(data => {
+        document.getElementById('${cardUuid}-description').innerText = data.description?.replace(/:[a-zA-Z0-9_]+:/g, '') || "Description not set";
+        document.getElementById('${cardUuid}-language').innerText = data.language;
+        document.getElementById('${cardUuid}-forks').innerText = Intl.NumberFormat('en-us', { notation: "compact", maximumFractionDigits: 1 }).format(data.forks).replaceAll("\\u202f", '');
+        document.getElementById('${cardUuid}-stars').innerText = Intl.NumberFormat('en-us', { notation: "compact", maximumFractionDigits: 1 }).format(data.stargazers_count).replaceAll("\\u202f", '');
+        const avatarEl = document.getElementById('${cardUuid}-avatar');
+        avatarEl.style.backgroundImage = 'url(' + data.owner.avatar_url + '&s=32' + ')';
+        avatarEl.style.backgroundColor = 'transparent';
+        document.getElementById('${cardUuid}-license').innerText = data.license?.spdx_id || "no-license";
+        document.getElementById('${cardUuid}-card').classList.remove("fetch-waiting");
+      }).catch(err => {
+        document.getElementById('${cardUuid}-card')?.classList.add("fetch-error");
+      })
+    `,
+	);
+
+	return h(
+		`a#${cardUuid}-card`,
+		{
+			class: "card-github fetch-waiting",
+			href: `https://github.com/${repo}`,
+			target: "_blank",
+		},
+		[
+			nTitle,
+			nDescription,
+			h("div", { class: "gc-infobar" }, [nStars, nForks, nLicense, nLanguage]),
+			nScript,
+		],
+	);
+}
+
+export function rehypeGithubCard(): any {
+	return (tree: any) => {
+		const walk = (node: any) => {
+			if (!Array.isArray(node.children)) return;
+			for (let i = 0; i < node.children.length; i++) {
+				const child = node.children[i];
+				if (child.type === "element" && child.tagName === "github") {
+					node.children[i] = githubCard(
+						child.properties ?? {},
+						child.children ?? [],
+					);
+				} else {
+					walk(child);
+				}
+			}
+		};
+		walk(tree);
+	};
+}

package/src/plugins/rehype.ts

@@ -0,0 +1,284 @@
+/**
+ * rehype 插件集（M3a，全部零依赖手写 hast 遍历）
+ *
+ * 挂载顺序（index.ts）：externalLinks → callouts → figure → firstImage → anchor
+ * 代码块渲染自 §4.61 起由 Expressive Code 接管（index.ts 直连 rehype 内核），
+ * 本文件不再包含代码块插件。
+ * 注意：hast 节点类名有两种形态——shiki/EC 产出用 HTML 属性名直接写 properties
+ * （class 为字符串而非 className 数组）；remark-rehype 原始节点则是 className
+ * 数组。读取类名务必走 getClassList 兼容两种形态。
+ */
+type Transformer = (tree: any, file: any) => void;
+
+/** 浅遍历辅助：对 node.children 逐个调用 fn，fn 可通过返回 'skip' 跳过子树 */
+function visit(node: any, fn: (n: any, parent: any | null) => void | "skip") {
+	const children = node.children;
+	if (!Array.isArray(children)) return;
+	for (const child of children) {
+		if (fn(child, node) !== "skip") visit(child, fn);
+	}
+}
+
+const isBlank = (n: any) => n.type === "text" && !n.value.trim();
+
+/**
+ * 读取 hast 节点类名列表（兼容两种形态）：shiki 产出用 HTML 属性名直接写
+ * properties（class 为字符串），remark-rehype 原始节点则是 className 数组。
+ */
+function getClassList(props: any): string[] {
+	const raw = props?.className ?? props?.class;
+	if (Array.isArray(raw)) return raw.map(String);
+	if (typeof raw === "string") return raw.split(/\s+/).filter(Boolean);
+	return [];
+}
+
+/* ---------------------------------------------------------------- 外链 */
+
+/**
+ * 外链新窗口打开：http(s) 绝对链接追加 target="_blank" rel="noopener noreferrer"
+ */
+export function rehypeExternalLinks(): Transformer {
+	return (tree) => {
+		visit(tree, (node) => {
+			if (node.type !== "element" || node.tagName !== "a") return;
+			const href = String(node.properties?.href ?? "");
+			if (!/^https?:\/\//i.test(href)) return;
+			node.properties.target = "_blank";
+			const rel = String(node.properties.rel ?? "");
+			const parts = new Set(rel.split(/\s+/).filter(Boolean));
+			parts.add("noopener");
+			parts.add("noreferrer");
+			node.properties.rel = [...parts].join(" ");
+		});
+	};
+}
+
+/* -------------------------------------------------------------- callouts */
+
+const CALLOUT_META: Record<
+	string,
+	{ cls: string; title: string; icon: string }
+> = {
+	NOTE: { cls: "info", title: "注", icon: "info" },
+	INFO: { cls: "info", title: "信息", icon: "info" },
+	TIP: { cls: "tip", title: "技巧", icon: "tip" },
+	ABSTRACT: { cls: "tip", title: "摘要", icon: "tip" },
+	SUMMARY: { cls: "tip", title: "摘要", icon: "tip" },
+	TLDR: { cls: "tip", title: "摘要", icon: "tip" },
+	TODO: { cls: "tip", title: "待办", icon: "tip" },
+	IMPORTANT: { cls: "important", title: "重要", icon: "important" },
+	EXAMPLE: { cls: "important", title: "示例", icon: "important" },
+	WARNING: { cls: "warn", title: "注意", icon: "warn" },
+	CAUTION: { cls: "warn", title: "警告", icon: "warn" },
+	ATTENTION: { cls: "warn", title: "注意", icon: "warn" },
+	QUESTION: { cls: "warn", title: "问题", icon: "help" },
+	HELP: { cls: "warn", title: "帮助", icon: "help" },
+	FAQ: { cls: "warn", title: "问答", icon: "help" },
+	DANGER: { cls: "danger", title: "危险", icon: "danger" },
+	ERROR: { cls: "danger", title: "错误", icon: "x" },
+	FAILURE: { cls: "danger", title: "失败", icon: "x" },
+	FAIL: { cls: "danger", title: "失败", icon: "x" },
+	MISSING: { cls: "danger", title: "缺失", icon: "x" },
+	BUG: { cls: "danger", title: "缺陷", icon: "bug" },
+	SUCCESS: { cls: "success", title: "成功", icon: "check" },
+	CHECK: { cls: "success", title: "成功", icon: "check" },
+	DONE: { cls: "success", title: "完成", icon: "check" },
+	QUOTE: { cls: "quote", title: "引用", icon: "quote" },
+	CITE: { cls: "quote", title: "引用", icon: "quote" },
+};
+
+/** 与原型一致的 lucide 风格图标（stroke 1.75） */
+const CALLOUT_ICONS: Record<string, string> = {
+	info: '<circle cx="12" cy="12" r="10"/><path d="M12 16v-4"/><path d="M12 8h.01"/>',
+	tip: '<path d="M9 18h6"/><path d="M10 22h4"/><path d="M15.09 14c.18-.98.65-1.74 1.41-2.5A4.65 4.65 0 0 0 18 8 6 6 0 0 0 6 8c0 1 .23 2.23 1.5 3.5A4.61 4.61 0 0 1 8.91 14"/>',
+	important:
+		'<path d="M2.7 10.3a2.41 2.41 0 0 0 0 3.41l7.59 7.59a2.41 2.41 0 0 0 3.41 0l7.59-7.59a2.41 2.41 0 0 0 0-3.41l-7.59-7.59a2.41 2.41 0 0 0-3.41 0z"/><path d="M12 8v4"/><path d="M12 16h.01"/>',
+	warn: '<path d="m21.73 18-8-14a2 2 0 0 0-3.48 0l-8 14A2 2 0 0 0 4 21h16a2 2 0 0 0 1.73-3"/><path d="M12 9v4"/><path d="M12 17h.01"/>',
+	danger: '<path d="M13 2 3 14h9l-1 8 10-12h-9l1-8z"/>',
+	check: '<path d="M20 6 9 17l-5-5"/>',
+	help: '<circle cx="12" cy="12" r="10"/><path d="M9.09 9a3 3 0 0 1 5.83 1c0 2-3 3-3 3"/><path d="M12 17h.01"/>',
+	x: '<path d="M18 6 6 18"/><path d="m6 6 12 12"/>',
+	bug: '<path d="m8 2 1.88 1.88"/><path d="M14.12 3.88 16 2"/><path d="M9 7.13v-1a3.003 3.003 0 1 1 6 0v1"/><path d="M12 20c-3.3 0-6-2.7-6-6v-3a4 4 0 0 1 4-4h4a4 4 0 0 1 4 4v3c0 3.3-2.7 6-6 6"/><path d="M12 20v-9"/><path d="M6.53 9C4.6 8.8 3 7.1 3 5"/><path d="M6 13H2"/><path d="M3 21c0-2.1 1.7-3.9 3.8-4"/><path d="M20.97 5c0 2.1-1.6 3.8-3.5 4"/><path d="M22 13h-4"/><path d="M17.2 17c2.1.1 3.8 1.9 3.8 4"/>',
+	quote:
+		'<path d="M16 3a2 2 0 0 0-2 2v6a2 2 0 0 0 2 2 1 1 0 0 1 1 1v1a2 2 0 0 1-2 2 1 1 0 0 0-1 1v2a1 1 0 0 0 1 1 6 6 0 0 0 6-6V5a2 2 0 0 0-2-2z"/><path d="M5 3a2 2 0 0 0-2 2v6a2 2 0 0 0 2 2 1 1 0 0 1 1 1v1a2 2 0 0 1-2 2 1 1 0 0 0-1 1v2a1 1 0 0 0 1 1 6 6 0 0 0 6-6V5a2 2 0 0 0-2-2z"/>',
+};
+
+function iconSvg(name: string) {
+	return {
+		type: "element",
+		tagName: "svg",
+		properties: {
+			className: ["co-icon"],
+			viewBox: "0 0 24 24",
+			fill: "none",
+			stroke: "currentColor",
+			strokeWidth: "1.75",
+			strokeLinecap: "round",
+			strokeLinejoin: "round",
+			ariaHidden: "true",
+		},
+		children: [
+			{ type: "raw", value: CALLOUT_ICONS[name] ?? CALLOUT_ICONS.info },
+		],
+	};
+}
+
+/**
+ * GitHub 警告块语法：> [!TYPE]（26 种别名，GFM alert + Obsidian callout 集合）
+ * 转换为 <div class="callout {cls}"><svg class="co-icon"/><div><b>标题</b>…原内容</div></div>
+ * 中文默认标题；[!TYPE] 同一行剩余文字作为自定义标题；语义相近的别名共用配色。
+ */
+export function rehypeCallouts(): Transformer {
+	return (tree) => {
+		visit(tree, (node) => {
+			if (node.type !== "element" || node.tagName !== "blockquote") return;
+			// 注意：Astro 7 的 mdast→hast 转换会给 blockquote 塞入首尾 "\n" 空白文本节点，
+			// 不能假设 children[0] 就是 <p>，须按类型查找首个元素子节点
+			const first = (node.children ?? []).find(
+				(c: any) => c.type === "element",
+			);
+			if (!first || first.tagName !== "p") return;
+			const firstText = first.children?.find((c: any) => c.type === "text");
+			if (!firstText) return;
+			const m = String(firstText.value).match(
+				/^\[!(NOTE|INFO|TIP|ABSTRACT|SUMMARY|TLDR|TODO|IMPORTANT|EXAMPLE|WARNING|CAUTION|ATTENTION|QUESTION|HELP|FAQ|DANGER|ERROR|BUG|FAILURE|FAIL|MISSING|SUCCESS|CHECK|DONE|QUOTE|CITE)\][ \t]*\n?/i,
+			);
+			if (!m) return;
+			const meta = CALLOUT_META[m[1].toUpperCase()];
+			// 移除标记文本；[!TYPE] 同一行剩余文字作为自定义标题（GitHub 语法）。
+			// 「无标题」时正则已吃掉换行（m[0] 以 \n 结尾），「有标题」时只吃到空格，
+			// 故以 m[0] 是否以 \n 结尾区分，避免把正文首行误当标题
+			const rest = String(firstText.value).slice(m[0].length);
+			let custom = "";
+			let bodyText = rest;
+			if (!m[0].endsWith("\n")) {
+				const nl = rest.indexOf("\n");
+				if (nl === -1) {
+					custom = rest.trim();
+					bodyText = "";
+				} else {
+					custom = rest.slice(0, nl).trim();
+					bodyText = rest.slice(nl + 1);
+				}
+			}
+			firstText.value = bodyText;
+			const title = custom || meta.title;
+			if (!firstText.value && first.children.length === 1) {
+				node.children = node.children.filter((c: any) => c !== first);
+			}
+			const body = {
+				type: "element",
+				tagName: "div",
+				properties: {},
+				children: [
+					{
+						type: "element",
+						tagName: "b",
+						properties: {},
+						children: [{ type: "text", value: title }],
+					},
+					...node.children,
+				],
+			};
+			node.tagName = "div";
+			node.properties = { className: ["callout", meta.cls] };
+			node.children = [iconSvg(meta.icon), body];
+		});
+	};
+}
+
+/* ---------------------------------------------------------------- figure */
+
+/**
+ * 独立段落中的单图 → <figure>；img 的 title 属性 → <figcaption>。
+ * 灯箱归组交给页面级 data-lightbox-gallery 容器（§4.70）：figure 不再自带
+ * data-lightbox，否则文章容器内嵌套两组容器会被双重绑定点击监听而双开灯箱
+ */
+export function rehypeFigure(): Transformer {
+	return (tree) => {
+		visit(tree, (node) => {
+			if (node.type !== "element" || node.tagName !== "p") return;
+			const meaningful = (node.children ?? []).filter((c: any) => !isBlank(c));
+			if (
+				meaningful.length !== 1 ||
+				meaningful[0].type !== "element" ||
+				meaningful[0].tagName !== "img"
+			)
+				return;
+			const img = meaningful[0];
+			const title = img.properties?.title;
+			const figure: any = {
+				type: "element",
+				tagName: "figure",
+				properties: {},
+				children: [img],
+			};
+			if (title) {
+				delete img.properties.title;
+				figure.children.push({
+					type: "element",
+					tagName: "figcaption",
+					properties: {},
+					children: [{ type: "text", value: String(title) }],
+				});
+			}
+			// 用 figure 替换 p 内容（p 无其他有意义子节点，直接整体替换）
+			node.tagName = "figure";
+			node.properties = figure.properties;
+			node.children = figure.children;
+		});
+	};
+}
+
+/* -------------------------------------------------------------- 首图提取 */
+
+/**
+ * 提取正文第一张图片地址 → frontmatter.firstImage（列表卡片封面兜底，决策 9）
+ */
+export function rehypeFirstImage(): Transformer {
+	return (tree, file) => {
+		let found = false;
+		visit(tree, (node) => {
+			if (found) return "skip";
+			if (node.type === "element" && node.tagName === "img") {
+				const src = node.properties?.src;
+				if (typeof src === "string" && src) {
+					file.data.astro.frontmatter.firstImage = src;
+					found = true;
+				}
+			}
+			return;
+		});
+	};
+}
+
+/* ------------------------------------------------------------ 标题锚点 */
+
+/**
+ * h2–h4（Astro 已注入 id）末尾追加 <a class="h-anchor">#</a>
+ */
+export function rehypeAnchor(): Transformer {
+	return (tree) => {
+		visit(tree, (node) => {
+			if (node.type !== "element") return;
+			if (!["h2", "h3", "h4"].includes(node.tagName)) return;
+			const id = node.properties?.id;
+			if (!id) return;
+			node.children.push({
+				type: "element",
+				tagName: "a",
+				properties: {
+					className: ["h-anchor"],
+					href: `#${id}`,
+					ariaLabel: "链接到本节",
+				},
+				children: [{ type: "text", value: "#" }],
+			});
+		});
+	};
+}
+
+/* -------------------------------------------------------------- 代码块 */
+
+/* §4.61 起代码块渲染由 Expressive Code 接管（index.ts 直连 rehype 内核），
+   自研 rehypeCodeBlock（复制/折叠按钮包装）已退役；此处不再有代码块插件 */