diff --git a/astro.config.mjs b/astro.config.mjs index ff9dff5e866..273e069353d 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -14,7 +14,6 @@ import icon from "astro-icon"; import { pluginLanguageLogo } from "ec-lang-logo"; /* Language Logo */ import { pluginCollapsible } from "expressive-code-collapsible"; /* Collapsible */ import { pluginLanguageBadge } from "expressive-code-language-badge"; /* Language Badge */ -import katex from "katex"; import "katex/dist/contrib/mhchem.mjs"; // 加载 mhchem 扩展 import rehypeAutolinkHeadings from "rehype-autolink-headings"; import rehypeCallouts from "rehype-callouts"; @@ -302,7 +301,7 @@ export default defineConfig({ [remarkPlantuml, plantumlConfig], ], rehypePlugins: [ - [rehypeKatex, { katex }], + rehypeKatex, [rehypeCallouts, { theme: siteConfig.post.rehypeCallouts.theme }], rehypeSlug, rehypeCodeGroup, diff --git a/docs/AGENT_CONTENT_PROMPT.md b/docs/AGENT_CONTENT_PROMPT.md index fbc387a2818..f2cb5b953c5 100644 --- a/docs/AGENT_CONTENT_PROMPT.md +++ b/docs/AGENT_CONTENT_PROMPT.md @@ -46,6 +46,7 @@ - 文章 Frontmatter 只必填 `title` 和 `published`。发布时建议按需填写 `description`、`tags`、`category`、`draft`、`author` 和 `comment`。其他字段见[字段规范](WRITING_GUIDE.md#43-字段规范)。 - 文章语言与站点默认语言不同时填写 `lang`,例如英文文章用 `en`。 - 提醒框使用 GitHub 语法,例如 `> [!NOTE]`。本站关闭了 Python-Markdown 的 `!!!`、`???` 和 `???+` 语法。折叠写法见[写作指南](WRITING_GUIDE.md#53-提醒框)。 +- 化学式和反应方程式可使用 KaTeX 的 `\ce{}`,示例见[化学公式](WRITING_GUIDE.md#188-katex-化学公式)。 - 日期按 `Asia/Shanghai` 时区。 - 已发布文章的 `published` 和 `slug` 不要修改;需要更新时设置 `updated`。 - 标签和分类优先沿用现有站点的写法,不要随意发明同义标签。 @@ -92,9 +93,6 @@ ## 已知限制 -- 当前版本的 KaTeX 化学公式不要使用 `\ce{}`,会显示红色未知命令。 -- 使用普通 KaTeX 写法,例如: - `\mathrm{CH_4 + 2O_2 \rightarrow CO_2 + 2H_2O}` - `draft: true` 在生产构建中隐藏,开发环境仍可见。 - Pagefind 搜索必须在 `pnpm build && pnpm preview` 后验证,开发服务器不能完整代表搜索结果。 - ESA Pages 没有与 Cloudflare Pages 完全相同的 PR Preview 流程,不要假设每个 PR 都有公开预览地址。 diff --git a/docs/WRITING_GUIDE.md b/docs/WRITING_GUIDE.md index 35f44fb3cec..c31559d2f4a 100644 --- a/docs/WRITING_GUIDE.md +++ b/docs/WRITING_GUIDE.md @@ -1226,13 +1226,11 @@ console.log("这一行标记为新增"); ### 18.8 KaTeX 化学公式 -官方演示页展示了 `mhchem` 的 `\ce{}` 语法,但当前仓库 `Firefly 6.16.9` 实测会把 `\ce` 渲染成红色未知命令。**不要直接依赖 `\ce{}`。** - -当前可靠写法是使用普通 KaTeX: +化学式和反应方程式可以用 KaTeX 的 `mhchem` 扩展书写。用 `\ce{}` 包住方程式,反应箭头写成 `->`。 ```markdown $$ -\mathrm{CH_4 + 2O_2 \rightarrow CO_2 + 2H_2O} +\ce{CH4 + 2O2 -> CO2 + 2H2O} $$ ``` diff --git a/package.json b/package.json index 5093037ae92..7746fc6647b 100644 --- a/package.json +++ b/package.json @@ -45,7 +45,8 @@ "@iconify/svelte": "^5.2.3", "@iconify/types": "^2.0.0", "@iconify/utils": "^3.1.7", - "@mermanjs/web": "0.8.0-alpha.3", + "@mermanjs/node": "0.9.3", + "@mermanjs/web": "0.9.3", "@napi-rs/wasm-runtime": "^1.2.6", "@swup/astro": "^1.8.0", "@tailwindcss/typography": "^0.5.20", diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 995c73230b9..b7016ff3ba6 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -4,6 +4,9 @@ settings: autoInstallPeers: true excludeLinksFromLockfile: false +overrides: + katex: ^0.19.1 + importers: .: @@ -71,9 +74,12 @@ importers: '@iconify/utils': specifier: ^3.1.7 version: 3.1.7 + '@mermanjs/node': + specifier: 0.9.3 + version: 0.9.3 '@mermanjs/web': - specifier: 0.8.0-alpha.3 - version: 0.8.0-alpha.3 + specifier: 0.9.3 + version: 0.9.3 '@napi-rs/wasm-runtime': specifier: ^1.2.6 version: 1.2.6(@emnapi/core@1.11.3)(@emnapi/runtime@1.11.3) @@ -2226,8 +2232,44 @@ packages: '@mdx-js/mdx@3.1.1': resolution: {integrity: sha512-f6ZO2ifpwAQIpzGWaBQT2TXxPv6z3RBzQKpVftEWN78Vl/YweF1uwussDx8ECAXVtr3Rs89fKyG9YlzUs9DyGQ==} - '@mermanjs/web@0.8.0-alpha.3': - resolution: {integrity: sha512-nuZcWWc/I85RWuFraiJp9LbUIC7zEB+hdWic6TSjV26iRgD9tOE+o/MMH48/h5R10lr4uLz5ec7mhFUOgFARjQ==} + '@mermanjs/node-darwin-arm64@0.9.3': + resolution: {integrity: sha512-60wjosh1ybTqk/UaLv+Rt8v70+a+TiKt2RorHZObNAy3lwnJYUkSHygpFgZYDjzBPI9BD9QaEcUHJIzzLzxolw==} + engines: {node: '>=22.0.0'} + cpu: [arm64] + os: [darwin] + + '@mermanjs/node-darwin-x64@0.9.3': + resolution: {integrity: sha512-RCUTdYw3QjRfoANpHSIXwJehuMhqqCtKJZyMn6FbwjLiDvAIhc6xqztNkRGuWgeidjket8ucvHTLSN6M5GT6jA==} + engines: {node: '>=22.0.0'} + cpu: [x64] + os: [darwin] + + '@mermanjs/node-linux-x64-gnu@0.9.3': + resolution: {integrity: sha512-LTR9ZEbl4YDibzG8F5ZkYjwc7pJWLkG9uiusNrcb+QohlXPmGTZUXZA7gE+jDH8mRzqcvex84qzPaAta/nGYcQ==} + engines: {node: '>=22.0.0'} + cpu: [x64] + os: [linux] + libc: [glibc] + + '@mermanjs/node-linux-x64-musl@0.9.3': + resolution: {integrity: sha512-aa5AjZbJyN8sNBtN5gTaOF4RzwBmds0JDGBAyiasWBAGbzwr524GFAF/sk9vPX6oT+Z0VsjLy3ZoQmHt8AL3lQ==} + engines: {node: '>=22.0.0'} + cpu: [x64] + os: [linux] + libc: [musl] + + '@mermanjs/node-win32-x64-msvc@0.9.3': + resolution: {integrity: sha512-UsUD3zbPv0cy4usMFMFFfQFhPY7An7meHj1YZLPEqLnx6HBG1BJ/ONvy5nxSZ9Ai/Oj9JozKI0VS3SYTl8geSQ==} + engines: {node: '>=22.0.0'} + cpu: [x64] + os: [win32] + + '@mermanjs/node@0.9.3': + resolution: {integrity: sha512-82NQI8z4R6pNAOvZEfm6MS5sMJjQ1SEVjznM/3E5VrDu2g1tQlNj2BXdt4pnCnsRofsXoiklWinzO8WLAvVmqA==} + engines: {node: '>=22.0.0'} + + '@mermanjs/web@0.9.3': + resolution: {integrity: sha512-+Oeu4Mr3KGwf0cAKyOC2Ho5HA2jiV+4+Q6zEtw7lNpM6AND0CY0dqI6l5tWF4kFDKuSZT+zMsthieS/exn1Uyw==} '@napi-rs/wasm-runtime@1.2.4': resolution: {integrity: sha512-AJxoUD2/15ESHbvpcyjU274nsAPLuOtPHCk0vKJM5pj//Fg/B1FXNWjPnXTT9PymCYYiHo4zPj0ZomXBKhoy7g==} @@ -3352,10 +3394,6 @@ packages: resolution: {integrity: sha512-QrWXB+ZQSVPmIWIhtEO9H+gwHaMGYiF5ChvoJ+K9ZGHG/sVsa6yiesAD1GC/x46sET00Xlwo1u49RVVVzvcSkw==} engines: {node: '>= 10'} - commander@8.3.0: - resolution: {integrity: sha512-OkTL9umf+He2DZkUq8f8J9of7yL6RJKI24dVITBmNfZBmri9zYZQrKkuXiKhyfPSu8tUhnVBB1iKXevvnlR4Ww==} - engines: {node: '>= 12'} - common-ancestor-path@2.0.0: resolution: {integrity: sha512-dnN3ibLeoRf2HNC+OlCiNc5d2zxbLJXOtiZUudNFSXZrNSydxcCsSpRzXwfu7BBWCIfHPw+xTayeBvJCP/D8Ng==} engines: {node: '>= 18'} @@ -4377,10 +4415,6 @@ packages: jsonfile@6.2.1: resolution: {integrity: sha512-zwOTdL3rFQ/lRdBnntKVOX6k5cKJwEc1HdilT71BWEu7J41gXIB2MRp+vxduPSwZJPWBxEzv4yH1wYLJGUHX4Q==} - katex@0.16.47: - resolution: {integrity: sha512-Eeo8Ys1doU1z+x8AZsPpQu+p/QcZBI5PeOo7QGQdy2x2m0MU/hYagBbGOmXwr5KVbEfVuWv9LpnQWeehogurjg==} - hasBin: true - katex@0.19.1: resolution: {integrity: sha512-jG8uKntjSEcm2EpQOh0XturpPuuC9r3Sq5HLHdsFdWZT27E672SF19QEi+of0/YeOy15lDgRhKvr5614uRrEfA==} hasBin: true @@ -8646,7 +8680,30 @@ snapshots: transitivePeerDependencies: - supports-color - '@mermanjs/web@0.8.0-alpha.3': {} + '@mermanjs/node-darwin-arm64@0.9.3': + optional: true + + '@mermanjs/node-darwin-x64@0.9.3': + optional: true + + '@mermanjs/node-linux-x64-gnu@0.9.3': + optional: true + + '@mermanjs/node-linux-x64-musl@0.9.3': + optional: true + + '@mermanjs/node-win32-x64-msvc@0.9.3': + optional: true + + '@mermanjs/node@0.9.3': + optionalDependencies: + '@mermanjs/node-darwin-arm64': 0.9.3 + '@mermanjs/node-darwin-x64': 0.9.3 + '@mermanjs/node-linux-x64-gnu': 0.9.3 + '@mermanjs/node-linux-x64-musl': 0.9.3 + '@mermanjs/node-win32-x64-msvc': 0.9.3 + + '@mermanjs/web@0.9.3': {} '@napi-rs/wasm-runtime@1.2.4(@emnapi/core@1.11.3)(@emnapi/runtime@1.11.3)': dependencies: @@ -9752,8 +9809,6 @@ snapshots: commander@7.2.0: {} - commander@8.3.0: {} - common-ancestor-path@2.0.0: {} commondir@1.0.1: {} @@ -11041,10 +11096,6 @@ snapshots: optionalDependencies: graceful-fs: 4.2.11 - katex@0.16.47: - dependencies: - commander: 8.3.0 - katex@0.19.1: dependencies: commander: 15.0.0 @@ -11623,7 +11674,7 @@ snapshots: dependencies: '@types/katex': 0.16.8 devlop: 1.1.0 - katex: 0.16.47 + katex: 0.19.1 micromark-factory-space: 2.0.1 micromark-util-character: 2.1.1 micromark-util-symbol: 2.0.1 @@ -12530,7 +12581,7 @@ snapshots: '@types/katex': 0.16.8 hast-util-from-html-isomorphic: 2.0.0 hast-util-to-text: 4.0.2 - katex: 0.16.47 + katex: 0.19.1 unist-util-visit-parents: 6.0.2 vfile: 6.0.3 diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml index 898118882d5..5af8d5610e3 100644 --- a/pnpm-workspace.yaml +++ b/pnpm-workspace.yaml @@ -3,3 +3,5 @@ packages: allowBuilds: esbuild: true workerd: true +overrides: + katex: "^0.19.1" diff --git a/src/plugins/rehype-mermaid.mjs b/src/plugins/rehype-mermaid.mjs index 85599939b7c..059633042de 100644 --- a/src/plugins/rehype-mermaid.mjs +++ b/src/plugins/rehype-mermaid.mjs @@ -1,5 +1,5 @@ -import { readFile } from "node:fs/promises"; -import { assertSafeSvgForDom, initMerman, renderSvg } from "@mermanjs/web"; +import { createNodeEngine } from "@mermanjs/node"; +import { assertSelfContainedSvgForDom } from "@mermanjs/web"; import { fromHtml } from "hast-util-from-html"; import { h } from "hastscript"; import { visit } from "unist-util-visit"; @@ -15,14 +15,9 @@ import { } from "./utils/diagramConstants.js"; import { extractText } from "./utils/extractText.js"; -const mermanWasmUrl = import.meta.resolve( - "@mermanjs/web/pkg/merman_wasm_bg.wasm", -); -await initMerman({ - wasm: { - module_or_path: await readFile(new URL(mermanWasmUrl)), - }, -}); +// @mermanjs/web 自 0.9 起仅支持浏览器运行时,构建期渲染改用 Node 原生引擎; +// @mermanjs/web 仅用于校验输出的 SVG 可以安全插入 DOM +const mermanEngine = await createNodeEngine(); /** * 在构建时将 Mermaid 源码渲染为浅色和深色两套静态 SVG @@ -40,24 +35,29 @@ function removeSvgMaxWidth(svg) { return svg.replace(/(]*style="[^"]*?)max-width:\s*[^;]+;?/, "$1"); } -function buildMermaidSvgs(mermaidCode, themeConfig, diagramIndex) { - const lightSvg = renderSvg(mermaidCode, { - host_theme: { preset: themeConfig.lightTheme }, - svg: { - diagram_id: `mermaid-${diagramIndex}-light`, - pipeline: "parity", - }, - }); - const darkSvg = renderSvg(mermaidCode, { - host_theme: { preset: themeConfig.darkTheme }, - svg: { - diagram_id: `mermaid-${diagramIndex}-dark`, - pipeline: "parity", - }, +function renderMermaidSvg(mermaidCode, preset, diagramId) { + return mermanEngine.renderSvgSync(mermaidCode, { + optionsJson: JSON.stringify({ + presentation: { theme: { preset } }, + svg: { diagram_id: diagramId, pipeline: "parity" }, + }), }); +} + +function buildMermaidSvgs(mermaidCode, themeConfig, diagramIndex) { + const lightSvg = renderMermaidSvg( + mermaidCode, + themeConfig.lightTheme, + `mermaid-${diagramIndex}-light`, + ); + const darkSvg = renderMermaidSvg( + mermaidCode, + themeConfig.darkTheme, + `mermaid-${diagramIndex}-dark`, + ); - assertSafeSvgForDom(lightSvg); - assertSafeSvgForDom(darkSvg); + assertSelfContainedSvgForDom(lightSvg); + assertSelfContainedSvgForDom(darkSvg); return { lightSvg: removeSvgMaxWidth(lightSvg), diff --git a/src/styles/markdown.css b/src/styles/markdown.css index 73074908344..7f88107d4bb 100644 --- a/src/styles/markdown.css +++ b/src/styles/markdown.css @@ -96,6 +96,11 @@ } } + /* 行内代码保留连续空格;代码块(pre > code)不受影响 */ + :not(pre) > code { + white-space: break-spaces; + } + .expressive-code { @apply my-4; } diff --git a/src/types/mermaidConfig.ts b/src/types/mermaidConfig.ts index 93314c240d1..4f161cca2c9 100644 --- a/src/types/mermaidConfig.ts +++ b/src/types/mermaidConfig.ts @@ -1,9 +1,9 @@ -import type { HostThemePresetName } from "@mermanjs/web"; +import type { BUNDLED_THEME_PRESETS } from "@mermanjs/web"; /** - * merman 内置宿主主题预设名 + * merman 内置主题预设名 */ -export type MermaidThemeName = HostThemePresetName; +export type MermaidThemeName = (typeof BUNDLED_THEME_PRESETS)[number]; /** * Mermaid 图表渲染配置 @@ -11,8 +11,8 @@ export type MermaidThemeName = HostThemePresetName; * 控制 markdown 文章中 ` ```mermaid ` 代码块在构建时的服务端 SVG 渲染行为。 */ export type MermaidConfig = { - /** 亮色模式下使用的 merman 宿主主题预设名 */ + /** 亮色模式下使用的 merman 内置主题预设名 */ lightTheme: MermaidThemeName; - /** 暗色模式下使用的 merman 宿主主题预设名 */ + /** 暗色模式下使用的 merman 内置主题预设名 */ darkTheme: MermaidThemeName; }; diff --git a/src/utils/responsive-utils.ts b/src/utils/responsive-utils.ts index 383db9446cb..58dfc655aa9 100644 --- a/src/utils/responsive-utils.ts +++ b/src/utils/responsive-utils.ts @@ -137,15 +137,34 @@ export function computeGridColumns(input: GridColumnsInput): GridColumnVars { const rightIn = sidebarActive && input.hasRightWidgets && input.position !== "left"; - // 平板端:position 为 both 时只显示 tabletSidebar 指定的那一侧 + // 平板端:position 为 both 时只显示 tabletSidebar 指定的那一侧。 + // 若指定的一侧没有可用组件(hasLeft/hasRightWidgets 为 false),则回退到另一侧, + // 避免平板宽度下整列侧边栏直接消失。 + let tabletSide = input.tabletSidebar; + if ( + input.position === "both" && + tabletSide === "left" && + !input.hasLeftWidgets && + input.hasRightWidgets + ) { + tabletSide = "right"; + } else if ( + input.position === "both" && + tabletSide === "right" && + !input.hasRightWidgets && + input.hasLeftWidgets + ) { + tabletSide = "left"; + } + const mdLeft = leftIn && (input.position === "left" || - (input.position === "both" && input.tabletSidebar === "left")); + (input.position === "both" && tabletSide === "left")); const mdRight = rightIn && (input.position === "right" || - (input.position === "both" && input.tabletSidebar === "right")); + (input.position === "both" && tabletSide === "right")); // 侧栏已启用但本断点无侧栏列 → 内容栏按比例收窄;比例钳到 [0,1],1 即不收窄 // 闸门用 enabled 而非 sidebarActive:enable: false 时仍铺满。md 与 xl 需各自判定