主站

知识库

Quartz v5 站点四处显示问题修复（2026-10-07）

Properties1
tagsops, quartz, caddy, site, incident

6分钟阅读

Quartz v5 站点四处显示问题修复（2026-10-07）

站点：http://${LANIP}:100（Caddy，quartz-vault.service，产物 ${HOME}/github/quartz/public）。 构建：./deploy/rebuild.sh（build → 泄漏/隐私扫描 → 重载服务 → 探测）。

问题 1：侧边「活页夹标签卡片」—— 已关闭

现象：每个页面左边缘竖排一串标签卡片（binder-tab / binder-spine / binder-label， 带 × 关闭按钮），标题就是相邻页面的名字（首页上显示 ops、README 等）。

来源：插件 github:quartz-community/stacked-pages（“Binder-style stacked page tabs”）， 在 quartz.config.yaml 里 layout.position: afterBody，客户端脚本把标签条渲染进 #stacked-pages-container（data-show-spines="true"）。

修法：quartz.config.yaml 里该插件改 enabled: false（已加注释说明为何关）。 验证：产物中 grep -rl binder-tab public --include=*.html | wc -l = 0。

问题 2：目录页目录列表重复两遍 —— 已修（框架 bug）

现象：没有 index.md 的目录（如 /ops/，55 篇）页面上「此文件夹下有 55 条笔记。」

  • 子目录 + 笔记列表整块出现两次，页面高度 13525px（正常 6956px）。

根因：Quartz v5 的 quartz/plugins/pageTypes/dispatcher.ts 里 populateVirtualPageHtmlAst() 为了支持 transclusion，把虚拟页 pageBody 渲染出的 HTML 写回了 ve.tree.children：

const htmlAst = fromHtml(htmlString, { fragment: true }) as HtmlRoot
ve.tree.children = htmlAst.children   // ← 元凶
ve.vfile.data.htmlAst = htmlAst

而虚拟页的 pageBody 就是 FolderContent（folder-page 插件），它把 tree 当作自己的正文 渲染。于是 emit 阶段再渲染一次 pageBody，就把同一块内容渲染了两遍 —— 目录页出现两份列表。 （populateVirtualPageHtmlAst 真正需要保留的只有 vfile.data.htmlAst，transclusion 读的是它。）

修法（照上游 v5 分支的做法，两处）：

  1. 删掉 ve.tree.children = htmlAst.children 这一行（保留 htmlAst，transclusion 不受影响）。
  2. emit() 与 partialEmit() 里把 allFilesWithVirtual 的构造提到 populateVirtualPageHtmlAst(...) 之前，并传入合并后的 allFiles，这样 Body 渲染时能解析到其它虚拟页。

验证：12 个目录页 page-listing 计数全部 = 1（修前 = 2），/ops/ 页面高度回到 6956px。

注意（给后来者）

  • 以上两项修复都在 vendored 的 Quartz 核心/插件配置里：quartz/ 是 jackyzha0/quartz 的克隆 （当前停在 ab346fa feat(v5): add plugin system (#2295)），quartz.config.yaml 未纳入 git。 将来升级 Quartz 核心可能产生 dispatcher.ts 补丁合并冲突 —— 升级后必须重跑上面两条验证。
  • 判据只有产物：page-listing 每页 1 个、binder-tab 全站 0 个。

问题 3：文件夹/文件难分辨 + 列表里显示 tags（2026-10-07 同日，纯 CSS）

诉求：① 侧栏与目录列表里文件夹、文件看起来一样，希望一眼能看出「这是文件夹」； ② 目录页/标签页每条笔记链接后面的 tag 胶囊让版面拥挤，去掉。

做法：改 quartz/styles/custom.scss（由 quartz/plugins/emitters/componentResources.ts 引入，构建时打进 public/index.css），不改插件源码 —— 观感调整走官方扩展点，插件升级不丢：

  • 侧栏：.explorer .folder-container .folder-title（文件夹）→ 加粗 600 + 主题色 + 文件夹图标； .explorer .nav-file-title（文件）→ 400 常规字重 + --darkgray。
  • 目录/标签列表（.page-listing）：ul.tags { display: none } 去掉 tag 胶囊； 文件夹条目用 a.internal[href$="/"] 命中（指向 index 的链接都以 / 结尾）→ 加粗 + 主题色 + 同一个图标； 文件条目标题 h3 a.internal 降为 400。
  • 文件夹图标用 lucide “folder” 的 data-URI 走 mask，颜色跟随 currentColor（变量 --qv-folder-icon）。

踩坑：插件自带 li.section-li>.section>.tags{display:none} 只在 @media (max-width:600px) 里， 桌面端一直显示 —— 别只看打包后的 CSS 就以为已经隐藏，必须用 getComputedStyle 在真实视口里量。 同理，标题默认 600 字重继承给链接，所以「文件夹加粗」在文件也是 600 时等于没做，必须同时把文件降到 400。

验证（浏览器 getComputedStyle，视口 1600px）：

  • .page-listing ul.tags 可见数 = 0（/ops/ 56 个、/tags/ops 33 个全部隐藏）；
  • 文件夹条目 weight=600 / color=--secondary / ::before 图标宽度 16px，文件条目 weight=400 / content=none；
  • 侧栏文件夹 600+图标、侧栏文件 400 无图标；笔记正文不含 ul.tags，不受影响。

问题 4：笔记页 Obsidian 按钮的位置与链接（2026-10-07 同日）

诉求：每篇文章标题右侧的 Obsidian 图标按钮 ①位置稍微上移；②链接更新库名与地址。

根因：按钮是本机自建插件 plugins-src/obsidian-open（quartz.config.yaml 用本地源声明， layout: beforeBody / priority 11，紧跟 article-title）。配置里写的是旧的 vault: agent —— 库早已改名，而 Obsidian 按库根目录名解析库名，${KNOWLEDGE_ROOT} → 库名就是 a， 所以旧链接点开找不到库。

做法：

  • quartz.config.yaml：options.vault: agent → a；插件源码 src/util/obsidian.ts 的 DEFAULT_VAULT 同步改 a（README 选项表与示例一并更新）。
  • 位置：src/components/ObsidianOpen.tsx 内联 CSS 给 a.obsidian-open 加 position: relative; top: -0.15rem（≈ -2.4px）—— 相对定位只上移图标，不影响行布局。
  • 改完必须重建插件 dist：cd plugins-src/obsidian-open && ../../node_modules/.bin/tsup。 站点构建读的是 dist/，只改 src/ 不生效（quartz.config.yaml 用本地源 → 软链到 .quartz/plugins/）。

验证：

  • 产物链接：obsidian://open?vault=a&file=research/openclaw.md&paneType=tab；
  • 位置：图标中心比标题文字盒中心低 3.7px（改前 6.1px），与标题同行、不换行；
  • 协议与库：xdg-mime query default x-scheme-handler/obsidian = obsidian.desktop； ~/.config/obsidian/obsidian.json 中 ${KNOWLEDGE_ROOT} 已注册（open: true），库名解析为 a。

关系图谱