Quartz StackedPages 插件指南在静态站点中实现 Andy Matuschak 式滑动分栏笔记浏览【免费下载链接】quartz a fast, batteries-included static-site generator that transforms Markdown content into fully functional websites项目地址: https://gitcode.com/GitHub_Trending/qua/quartz本篇技术指南聚焦于 Quartz 静态站点生成器项目根目录中的StackedPages社区组件插件。它实现了 Andy Matuschak 风格的堆叠面板stacked sliding panes交互点击页面内链时目标页面不会跳转离开而是在右侧以新窗格pane形式并排打开让读者沿笔记链接的路径横向追溯阅读轨迹。读完本文你将掌握StackedPages 的核心交互模型、#stackedURL 哈希机制、全部可配置参数及其默认值、在quartz.config.yaml中的启用与布局方式以及它与 Quartz v5 插件管理体系的底层衔接关系。[!note] 关于如何添加、移除或配置 Quartz 插件可参见配置文档中的 Plugins 章节。插件概览为什么需要堆叠分栏传统博客或知识库中点击内链意味着离开当前页面读者需要依赖浏览器后退按钮才能回到原文。StackedPages 改变了这一范式每个窗格都是一个完整的页面可以独立滚动、独立关闭多个窗格横向排列形成一条可追溯的阅读路径。这种交互模式非常适合用于数字花园 / 学习笔记库沿着概念链接逐层深入随时回看上一个知识点长文与参考文献联读正文与引用页面并排对照导览型内容为读者预设一条由浅入深的页面轨迹。StackedPages 属于 Quartz 的Component组件类别插件见 plugins 索引。组件类插件负责在页面布局中渲染 UI 元素与内置插件使用Plugin.X()不同社区组件插件在 TS 覆写中以ExternalPlugin.X()形式调用从.quartz/plugins导入。核心交互模型启用插件后页面的行为发生如下变化点击链接任何内部链接被点击时目标页面会在右侧新开一个窗格而不是替换当前页面。若已达到窗格数量上限则最左侧的窗格会被移除保持滑动窗口式的先进先出关闭窗格点击窗格头部pane header的×按钮即可将该窗格从堆栈中移除折叠书脊Collapsed spines当窗格数量超出视口宽度时较早的窗格会折叠成一条细长的垂直书脊书脊上显示页面标题点击书脊可重新将对应窗格带回焦点浏览器前进/后退完整的堆栈状态被编码进 URL 哈希中并与浏览器历史深度集成因此前进/后退导航完全符合直觉。URL 哈希与可分享性堆栈的当前状态会实时反映在地址栏URL 会更新为#stackedslug1,slug2形式的哈希slug1,slug2即当前堆栈中从左到右的页面 slug 列表。这意味着你可以把某条特定的阅读轨迹分享或收藏——接收者打开链接后会直接看到同样的窗格堆栈而不只是单个页面。这一设计也让堆栈状态天然支持浏览器历史记录的前进/后退语义。移动端行为堆栈分栏在移动端默认禁用。原因是水平方向的多窗格在窄屏上体验不佳横向平移在小屏幕上难以操作。判断阈值由mobileBreakpoint配置项控制默认800px当视口宽度低于该阈值时链接恢复正常导航行为点击内链直接跳转。启用与布局配置StackedPages 是社区插件需要通过npx quartz plugin add安装然后在quartz.config.yaml中启用。Quartz 的官方配置模板如 default.yaml已预置该插件条目默认处于enabled: false状态plugins: - source: quartz-community/stacked-pages enabled: true layout: position: afterBody priority: 50 display: all各字段含义source插件来源。社区插件以github:quartz-community/name或等价的quartz-community/namenpm 形式引用enabled是否启用该插件layout.position组件在页面布局中的插槽位置。afterBody表示渲染在正文之后页面底部区域layout.priority同位置内多个组件的排序优先级数值越大越靠后layout.display响应式显示控制。all表示在所有屏幕尺寸下可见可选值还包括mobile-only、desktop-only详见 布局组件文档。[!tip] 在 Quartz v5 中afterBody、header、beforeBody、left、right、footer等都是合法布局插槽见 layout.md 中的FullPageLayout类型定义。将组件放入afterBody意味着它渲染在正文之后、页脚之前。安装并启用的完整流程# 1. 从 GitHub 仓库安装插件写入 .quartz/plugins/ 并登记到 quartz.lock.json npx quartz plugin add github:quartz-community/stacked-pages # 2. 在 quartz.config.yaml 中启用也可直接编辑 YAML 将 enabled 置为 true npx quartz plugin enable stacked-pages[!note] 插件管理命令的完整参考add/install/enable/disable/prune等子命令见 plugin CLI 参考。例如在克隆他人项目或 CI 环境中可用npx quartz plugin install --from-config一键同步配置文件中的所有插件。配置参数详解StackedPages 接受四个配置选项均通过插件条目的options字段传入参数类型默认值说明maxTabsnumber8同一时间最多可见的堆叠窗格数量。达到上限后点击新链接最左侧窗格被移除mobileBreakpointnumber800视口宽度像素低于该值时堆叠功能禁用链接恢复普通导航showSpinesbooleantrue窗格溢出视口时是否显示折叠的书脊头部显示页面标题animateTransitionsbooleantrue是否对窗格打开/关闭过程播放过渡动画完整配置示例默认值- source: github:quartz-community/stacked-pages enabled: true layout: position: afterBody priority: 50 display: all options: maxTabs: 8 mobileBreakpoint: 800 showSpines: true animateTransitions: true参数调优建议降低maxTabs如4~5如果站点页面内容较长过宽的窗格堆栈会挤压每个窗格的阅读宽度减少窗格数量可保证可读性调整mobileBreakpoint默认800与 Quartz 布局系统的移动端断点一致见 layout.md 中的断点定义mobile: 800px、desktop: 1200px。如果你的目标读者多使用大屏平板可适当调低该值反之若多数是手机用户可保持或调高关闭animateTransitions在低性能设备或偏好即时响应的场景下可将动画关闭以减少滚动与重排开销关闭showSpines如果你不希望出现折叠书脊例如窗格较少、很少溢出时可设为false。[!note] 所有插件选项均可在quartz.ts中以 TS 覆写方式编程控制quartz.ts中设置的选项会与 YAML 选项合并并优先生效见 配置文档。但 StackedPages 的四个选项均为纯数据型参数直接使用 YAML 配置即可无需 TS 覆写。从源码看插件安装与加载机制为了更深入理解 StackedPages 在 Quartz 中的运行位置可以追溯插件安装与加载的底层实现安装入口install-plugins.ts 中的getExternalPluginSources()会优先尝试从quartz.js的externalPlugins读取插件列表否则回退到解析quartz.config.yaml中的plugins条目过滤掉enabled: false的条目后取source。这意味着enabled: false的插件不会被安装器拉取——只有真正启用后才进入安装流程来源解析parsePluginSource()负责解析github:org/repo形式的字符串来源以及带#ref的分支/标签形式、subdir/name的对象形式随后通过installPlugins()将仓库克隆到.quartz/plugins/并构建外部插件导出安装完成后插件在 TS 覆写中以ExternalPlugin.StackedPages()形式实例化。这正是 StackedPages 文档 API 一节中Function name: ExternalPlugin.StackedPages()的来源参见 plugins 索引 对 Community plugins 的说明。从源码结构可以推断StackedPages 作为一个独立仓库插件其窗格渲染、书脊折叠、哈希同步等逻辑全部封装在插件自身的前端代码中Quartz 核心只负责按layout.position: afterBody将其挂载到页面布局并按display: all决定响应式显示——这种核心调度 插件自治的架构正是 Quartz v5 插件体系的通用模式。API 参考速查| 项 | 值 | | -- | -- | | 类别 | Component组件 | | 函数名 |ExternalPlugin.StackedPages()| | 来源 |quartz-community/stacked-pages仓库 | | 安装命令 |npx quartz plugin add github:quartz-community/stacked-pages|常见问题与排查启用了插件但点击链接仍直接跳转检查视口宽度是否低于mobileBreakpoint默认 800px移动端/窄窗口下堆叠功能会被主动禁用窗格数量看起来不受maxTabs限制确认options是否正确嵌套在插件条目的options字段下而非顶层并检查 YAML 缩进安装后提示找不到插件确认配置中enabled为true后重新执行npx quartz plugin install --from-config安装器会跳过enabled: false的条目或直接运行npx quartz plugin add github:quartz-community/stacked-pages强制安装。小结StackedPages 以极低的接入成本一条 YAML 配置 一条安装命令为 Quartz 站点注入了 Andy Matuschak 式的横向滑动分栏浏览体验。它的核心价值在于通过#stackedslug1,slug2哈希让阅读轨迹本身可分享、可回溯、可被浏览器历史记录配合窗格关闭、折叠书脊与响应式禁用机制兼顾了桌面端的沉浸式追溯与移动端的简洁导航。配合 Quartz 灵活的layout.position/priority/display布局体系它可以无缝融入任何 Quartz v4/v5 项目。【免费下载链接】quartz a fast, batteries-included static-site generator that transforms Markdown content into fully functional websites项目地址: https://gitcode.com/GitHub_Trending/qua/quartz创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Quartz StackedPages 插件指南：在静态站点中实现 Andy Matuschak 式滑动分栏笔记浏览
Quartz StackedPages 插件指南在静态站点中实现 Andy Matuschak 式滑动分栏笔记浏览【免费下载链接】quartz a fast, batteries-included static-site generator that transforms Markdown content into fully functional websites项目地址: https://gitcode.com/GitHub_Trending/qua/quartz本篇技术指南聚焦于 Quartz 静态站点生成器项目根目录中的StackedPages社区组件插件。它实现了 Andy Matuschak 风格的堆叠面板stacked sliding panes交互点击页面内链时目标页面不会跳转离开而是在右侧以新窗格pane形式并排打开让读者沿笔记链接的路径横向追溯阅读轨迹。读完本文你将掌握StackedPages 的核心交互模型、#stackedURL 哈希机制、全部可配置参数及其默认值、在quartz.config.yaml中的启用与布局方式以及它与 Quartz v5 插件管理体系的底层衔接关系。[!note] 关于如何添加、移除或配置 Quartz 插件可参见配置文档中的 Plugins 章节。插件概览为什么需要堆叠分栏传统博客或知识库中点击内链意味着离开当前页面读者需要依赖浏览器后退按钮才能回到原文。StackedPages 改变了这一范式每个窗格都是一个完整的页面可以独立滚动、独立关闭多个窗格横向排列形成一条可追溯的阅读路径。这种交互模式非常适合用于数字花园 / 学习笔记库沿着概念链接逐层深入随时回看上一个知识点长文与参考文献联读正文与引用页面并排对照导览型内容为读者预设一条由浅入深的页面轨迹。StackedPages 属于 Quartz 的Component组件类别插件见 plugins 索引。组件类插件负责在页面布局中渲染 UI 元素与内置插件使用Plugin.X()不同社区组件插件在 TS 覆写中以ExternalPlugin.X()形式调用从.quartz/plugins导入。核心交互模型启用插件后页面的行为发生如下变化点击链接任何内部链接被点击时目标页面会在右侧新开一个窗格而不是替换当前页面。若已达到窗格数量上限则最左侧的窗格会被移除保持滑动窗口式的先进先出关闭窗格点击窗格头部pane header的×按钮即可将该窗格从堆栈中移除折叠书脊Collapsed spines当窗格数量超出视口宽度时较早的窗格会折叠成一条细长的垂直书脊书脊上显示页面标题点击书脊可重新将对应窗格带回焦点浏览器前进/后退完整的堆栈状态被编码进 URL 哈希中并与浏览器历史深度集成因此前进/后退导航完全符合直觉。URL 哈希与可分享性堆栈的当前状态会实时反映在地址栏URL 会更新为#stackedslug1,slug2形式的哈希slug1,slug2即当前堆栈中从左到右的页面 slug 列表。这意味着你可以把某条特定的阅读轨迹分享或收藏——接收者打开链接后会直接看到同样的窗格堆栈而不只是单个页面。这一设计也让堆栈状态天然支持浏览器历史记录的前进/后退语义。移动端行为堆栈分栏在移动端默认禁用。原因是水平方向的多窗格在窄屏上体验不佳横向平移在小屏幕上难以操作。判断阈值由mobileBreakpoint配置项控制默认800px当视口宽度低于该阈值时链接恢复正常导航行为点击内链直接跳转。启用与布局配置StackedPages 是社区插件需要通过npx quartz plugin add安装然后在quartz.config.yaml中启用。Quartz 的官方配置模板如 default.yaml已预置该插件条目默认处于enabled: false状态plugins: - source: quartz-community/stacked-pages enabled: true layout: position: afterBody priority: 50 display: all各字段含义source插件来源。社区插件以github:quartz-community/name或等价的quartz-community/namenpm 形式引用enabled是否启用该插件layout.position组件在页面布局中的插槽位置。afterBody表示渲染在正文之后页面底部区域layout.priority同位置内多个组件的排序优先级数值越大越靠后layout.display响应式显示控制。all表示在所有屏幕尺寸下可见可选值还包括mobile-only、desktop-only详见 布局组件文档。[!tip] 在 Quartz v5 中afterBody、header、beforeBody、left、right、footer等都是合法布局插槽见 layout.md 中的FullPageLayout类型定义。将组件放入afterBody意味着它渲染在正文之后、页脚之前。安装并启用的完整流程# 1. 从 GitHub 仓库安装插件写入 .quartz/plugins/ 并登记到 quartz.lock.json npx quartz plugin add github:quartz-community/stacked-pages # 2. 在 quartz.config.yaml 中启用也可直接编辑 YAML 将 enabled 置为 true npx quartz plugin enable stacked-pages[!note] 插件管理命令的完整参考add/install/enable/disable/prune等子命令见 plugin CLI 参考。例如在克隆他人项目或 CI 环境中可用npx quartz plugin install --from-config一键同步配置文件中的所有插件。配置参数详解StackedPages 接受四个配置选项均通过插件条目的options字段传入参数类型默认值说明maxTabsnumber8同一时间最多可见的堆叠窗格数量。达到上限后点击新链接最左侧窗格被移除mobileBreakpointnumber800视口宽度像素低于该值时堆叠功能禁用链接恢复普通导航showSpinesbooleantrue窗格溢出视口时是否显示折叠的书脊头部显示页面标题animateTransitionsbooleantrue是否对窗格打开/关闭过程播放过渡动画完整配置示例默认值- source: github:quartz-community/stacked-pages enabled: true layout: position: afterBody priority: 50 display: all options: maxTabs: 8 mobileBreakpoint: 800 showSpines: true animateTransitions: true参数调优建议降低maxTabs如4~5如果站点页面内容较长过宽的窗格堆栈会挤压每个窗格的阅读宽度减少窗格数量可保证可读性调整mobileBreakpoint默认800与 Quartz 布局系统的移动端断点一致见 layout.md 中的断点定义mobile: 800px、desktop: 1200px。如果你的目标读者多使用大屏平板可适当调低该值反之若多数是手机用户可保持或调高关闭animateTransitions在低性能设备或偏好即时响应的场景下可将动画关闭以减少滚动与重排开销关闭showSpines如果你不希望出现折叠书脊例如窗格较少、很少溢出时可设为false。[!note] 所有插件选项均可在quartz.ts中以 TS 覆写方式编程控制quartz.ts中设置的选项会与 YAML 选项合并并优先生效见 配置文档。但 StackedPages 的四个选项均为纯数据型参数直接使用 YAML 配置即可无需 TS 覆写。从源码看插件安装与加载机制为了更深入理解 StackedPages 在 Quartz 中的运行位置可以追溯插件安装与加载的底层实现安装入口install-plugins.ts 中的getExternalPluginSources()会优先尝试从quartz.js的externalPlugins读取插件列表否则回退到解析quartz.config.yaml中的plugins条目过滤掉enabled: false的条目后取source。这意味着enabled: false的插件不会被安装器拉取——只有真正启用后才进入安装流程来源解析parsePluginSource()负责解析github:org/repo形式的字符串来源以及带#ref的分支/标签形式、subdir/name的对象形式随后通过installPlugins()将仓库克隆到.quartz/plugins/并构建外部插件导出安装完成后插件在 TS 覆写中以ExternalPlugin.StackedPages()形式实例化。这正是 StackedPages 文档 API 一节中Function name: ExternalPlugin.StackedPages()的来源参见 plugins 索引 对 Community plugins 的说明。从源码结构可以推断StackedPages 作为一个独立仓库插件其窗格渲染、书脊折叠、哈希同步等逻辑全部封装在插件自身的前端代码中Quartz 核心只负责按layout.position: afterBody将其挂载到页面布局并按display: all决定响应式显示——这种核心调度 插件自治的架构正是 Quartz v5 插件体系的通用模式。API 参考速查| 项 | 值 | | -- | -- | | 类别 | Component组件 | | 函数名 |ExternalPlugin.StackedPages()| | 来源 |quartz-community/stacked-pages仓库 | | 安装命令 |npx quartz plugin add github:quartz-community/stacked-pages|常见问题与排查启用了插件但点击链接仍直接跳转检查视口宽度是否低于mobileBreakpoint默认 800px移动端/窄窗口下堆叠功能会被主动禁用窗格数量看起来不受maxTabs限制确认options是否正确嵌套在插件条目的options字段下而非顶层并检查 YAML 缩进安装后提示找不到插件确认配置中enabled为true后重新执行npx quartz plugin install --from-config安装器会跳过enabled: false的条目或直接运行npx quartz plugin add github:quartz-community/stacked-pages强制安装。小结StackedPages 以极低的接入成本一条 YAML 配置 一条安装命令为 Quartz 站点注入了 Andy Matuschak 式的横向滑动分栏浏览体验。它的核心价值在于通过#stackedslug1,slug2哈希让阅读轨迹本身可分享、可回溯、可被浏览器历史记录配合窗格关闭、折叠书脊与响应式禁用机制兼顾了桌面端的沉浸式追溯与移动端的简洁导航。配合 Quartz 灵活的layout.position/priority/display布局体系它可以无缝融入任何 Quartz v4/v5 项目。【免费下载链接】quartz a fast, batteries-included static-site generator that transforms Markdown content into fully functional websites项目地址: https://gitcode.com/GitHub_Trending/qua/quartz创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考