From 994c0b8da0cb63f7a6190b4da88ecb08446575c4 Mon Sep 17 00:00:00 2001 From: shkomg Date: Thu, 5 Nov 2026 19:12:05 +0100 Subject: [PATCH 1/5] =?UTF-8?q?fix(markdown):=20=E8=A1=8C=E5=86=85?= =?UTF-8?q?=E4=BB=A3=E7=A0=81=E4=BF=9D=E7=95=99=E8=BF=9E=E7=BB=AD=E7=A9=BA?= =?UTF-8?q?=E6=A0=BC=20(#708)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Inline code collapsed runs of spaces into one, so `a b` rendered as `a b`. Set white-space: break-spaces on inline code (code not directly inside pre), as suggested in the issue. Code blocks are rendered by expressive-code inside pre > code and are not affected. Closes #514 --- src/styles/markdown.css | 5 +++++ 1 file changed, 5 insertions(+) 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; } From 7a80bcf010db6ea46d7138772d0220acf4d184aa Mon Sep 17 00:00:00 2001 From: ahmetalkan Date: Sun, 15 Nov 2026 17:10:58 +0300 Subject: [PATCH 2/5] fix(sidebar): fall back to the other side on tablet when the preferred side has no widgets (#713) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit When position is "both", the 769-1279px range only shows the side configured in tabletSidebar. If that side has no enabled widgets, no sidebar column is generated at all at tablet width, while xl still shows the other one — the sidebar disappears completely. computeGridColumns now falls back to the opposite side when the preferred tablet side is empty, so a sidebar is still rendered at tablet width. Side-specific configuration (position, tabletSidebar) and the default configuration are unchanged. Co-authored-by: ahmetalkan --- src/utils/responsive-utils.ts | 25 ++++++++++++++++++++++--- 1 file changed, 22 insertions(+), 3 deletions(-) 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 需各自判定 From 72f6edc60338d6955c46834549af06d4b2763c5d Mon Sep 17 00:00:00 2001 From: Jihoon Jeon Date: Sun, 15 Nov 2026 23:11:33 +0900 Subject: [PATCH 3/5] fix(mermaid): render diagrams with @mermanjs/node for Merman 0.9 (#717) @mermanjs/web 0.9 refuses to initialize outside a browser realm, so the build-time rehype plugin can no longer use it. Render with the native @mermanjs/node engine instead and keep @mermanjs/web only for the DOM-safety assertion, which still runs in Node. - replace initMerman/renderSvg with createNodeEngine().renderSvgSync - pass themes through presentation.theme.preset (host_theme was removed) - use assertSelfContainedSvgForDom (assertSafeSvgForDom was renamed) - derive the theme name type from BUNDLED_THEME_PRESETS --- package.json | 3 +- pnpm-lock.yaml | 72 +++++++++++++++++++++++++++++++--- src/plugins/rehype-mermaid.mjs | 52 ++++++++++++------------ src/types/mermaidConfig.ts | 10 ++--- 4 files changed, 100 insertions(+), 37 deletions(-) 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..f1b0b68f714 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -71,9 +71,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 +2229,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==} @@ -8646,7 +8685,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: 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/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; }; From 908e7d775e4d3aee16bf44379ff710cb7caeb46d Mon Sep 17 00:00:00 2001 From: dringsim Date: Sun, 15 Nov 2026 22:11:53 +0800 Subject: [PATCH 4/5] =?UTF-8?q?fix(katex):=20=E8=A6=86=E7=9B=96rehype-kate?= =?UTF-8?q?x=E4=BE=9D=E8=B5=96=E7=9A=84katex=E7=89=88=E6=9C=AC=20(#718)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit fix #633 --- astro.config.mjs | 3 +-- pnpm-lock.yaml | 21 +++++---------------- pnpm-workspace.yaml | 2 ++ 3 files changed, 8 insertions(+), 18 deletions(-) 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/pnpm-lock.yaml b/pnpm-lock.yaml index f1b0b68f714..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: .: @@ -3391,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'} @@ -4416,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 @@ -9814,8 +9809,6 @@ snapshots: commander@7.2.0: {} - commander@8.3.0: {} - common-ancestor-path@2.0.0: {} commondir@1.0.1: {} @@ -11103,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 @@ -11685,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 @@ -12592,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" From 6c9e3ab700ed0922974ae0c79e483db3709618ed Mon Sep 17 00:00:00 2001 From: WirepullerDX <142487994+WirepullerDX@users.noreply.github.com> Date: Mon, 16 Nov 2026 05:44:53 +0800 Subject: [PATCH 5/5] docs: document KaTeX chemistry support --- docs/AGENT_CONTENT_PROMPT.md | 4 +--- docs/WRITING_GUIDE.md | 6 ++---- 2 files changed, 3 insertions(+), 7 deletions(-) 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} $$ ```