Quartz 的 JSON Canvas 支持：用 CanvasPage 插件把 Obsidian 画布发布为可交互网页

Quartz 的 JSON Canvas 支持用 CanvasPage 插件把 Obsidian 画布发布为可交互网页【免费下载链接】quartz a fast, batteries-included static-site generator that transforms Markdown content into fully functional websites项目地址: https://gitcode.com/GitHub_Trending/qua/quartzQuartz 内置了对外部 JSON Canvas.canvas文件的一流渲染支持只要安装了canvas-page社区插件仓库中的.canvas文件就会被构造成可平移pan、可缩放zoom的交互式画布页面文字节点、文件引用、链接节点、分组节点与连线edge均按视觉原样呈现。读完本文你将掌握如何在 Quartz 站点中启用 Canvas 支持、理解CanvasPage插件的全部配置项与“canvas”页面框架Page Frame的工作原理并能在quartz.config.yaml中自定义画布页的布局。什么是 JSON CanvasQuartz 如何渲染它JSON Canvas 是一种开放的无限画布数据文件格式画布文件以.canvas扩展名存储本质上是标准 JSON。它由 Obsidian 等笔记工具原生支持用于表达节点nodes与连线edges组成的可视化思维网络。Quartz 将这类文件作为**页面类型Page Type**来对待。依据 docs/features/Canvas.mdQuartz 支持把.canvas文件渲染为interactive, pannable and zoomable canvas pages并保留以下要素的完整视觉保真度Text nodes文本节点渲染 Markdown 内容支持 GFMGitHub Flavored Markdown涵盖标题、加粗、斜体、删除线、列表、链接与代码块File nodes文件节点指向仓库vault内其他页面悬停时支持 popover 预览Link nodes链接节点引用外部 URLGroup nodes分组节点可带标签与背景色的视觉分组容器Edges连线节点之间的 SVG 连接支持可选标签、箭头标记与颜色覆盖上下左右四个方向。在 Quartz v5 中这类能力由CanvasPage页面类型插件提供属于外部社区插件其完整配置与能力清单见 docs/plugins/CanvasPage.md。值得说明的是obsidian模板默认就启用了quartz-community/canvas-page见 quartz/cli/templates/obsidian.yaml也就是说通过npx quartz create选择 Obsidian 模板创建站点后Canvas 支持通常是开箱即用的。快速开始安装 canvas-page 插件Canvas 支持由外部插件canvas-page提供安装命令如下npx quartz plugin add github:quartz-community/canvas-page该命令会把插件条目写入quartz.config.yaml并将其安装到.quartz/plugins/目录。如果你克隆了一个已引用但尚未安装该插件的项目例如 CI 环境可以统一安装配置中引用的所有插件npx quartz plugin install --from-config如需移除已不在配置中的插件使用npx quartz plugin prune两个命令均支持--dry-run预览变更详见 docs/configuration.md 与 docs/cli/plugin.md。安装并启用后任何位于content/目录下的.canvas文件都会在构建时被识别并输出为独立的可交互 HTML 页面。CanvasPage 插件的配置选项CanvasPage是一个页面类型插件函数签名为ExternalPlugin.CanvasPage()。它接受以下配置选项默认值以当前文档为准选项作用默认值enableInteraction是否启用画布上的平移pan与缩放zoom交互trueinitialZoom画布首次显示时的初始缩放级别1minZoom缩小时允许的最小缩放级别0.1maxZoom放大时允许的最大缩放级别5配置方式有两种。一种是在quartz.config.yaml中通过options指定plugins: - source: github:quartz-community/canvas-page enabled: true options: enableInteraction: true initialZoom: 1 minZoom: 0.1 maxZoom: 5另一种是在quartz.ts中使用 TS 覆盖当选项需要回调函数等 YAML 无法表达的 JavaScript 值时必须走这条路径。注意插件覆盖必须放在loadQuartzConfig()之前才会在配置加载实例化组件时生效import { loadQuartzConfig, loadQuartzLayout } from ./quartz/plugins/loader/config-loader import * as ExternalPlugin from ./.quartz/plugins ExternalPlugin.CanvasPage({ enableInteraction: true, initialZoom: 1, maxZoom: 5, }) const config await loadQuartzConfig() export default config export const layout await loadQuartzLayout()quartz.ts中的选项与 YAML 选项是合并关系且 TS 侧优先级更高见 docs/configuration.md。全屏模式的补充说明在仓库的 docs/Canvas.canvas 演示画布中还记录了两个细节可作为配置的延伸参考画布右上角有展开按钮用于切换全屏模式画布会填充整个视口按Escape退出可通过defaultFullscreen选项默认为false让画布启动时即进入全屏模式切换按钮会在展开/收起图标之间自动变化。由于这些选项来自仓库内置的演示画布内容而非插件文档的正式表格实际使用时请以安装的canvas-page插件版本声明为准。“canvas”页面框架为无限画布设计的沉浸式布局CanvasPage插件通过 Frame Registry 注册了自己的canvas页面框架Page Frame这是它区别于普通内容页的核心。框架的视觉行为根据 docs/plugins/CanvasPage.mdcanvas框架提供默认全屏渲染画布以 100vw × 100vh 占据整个视口最大化利用屏幕空间贴合 JSON Canvas“无限画布”的定位可切换的左侧边栏这是该框架唯一的布局槽位从左侧边缘滑入渲染与内容页left侧边栏相同的组件如 Explorer、Search、Page Title 等顶栏左上角的汉堡/关闭按钮用于切换侧边栏按Escape或点击关闭按钮即可收起右侧的画布控制区提供放大、缩小、重置等控件移动端适配侧边栏以覆盖overlay方式浮于画布之上而不是把画布推到一边。框架解析优先级与 YAML 覆盖框架的解析顺序在 docs/layout.md 中定义YAML 配置覆盖layout.byPageType.name.template插件注册的框架插件通过 Frame Registry 注册的框架从插件的frames导出加载插件声明页面类型插件源码中frame属性声明的框架兜底default从实现看页面类型分发器PageTypeDispatcher见 quartz/plugins/pageTypes/dispatcher.ts在解析布局时正是按配置覆盖 页面类型声明 默认的优先级合并出最终frame而frameRegistry见 quartz/components/frames/registry.ts负责按名称注册和查询框架并会在同名框架被不同来源覆盖时打印警告。因此如果你不希望画布页全屏展示可以在quartz.config.yaml中把 canvas 页面的模板覆盖为内置的default标准三栏布局layout: byPageType: canvas: template: default # 改用标准三栏布局或者改用无侧栏的minimal框架layout: byPageType: canvas: template: minimal同样的机制也出现在 docs/configuration.md 中——layout.byPageType的template字段专门用于覆盖某个页面类型的框架。框架是如何由插件提供的外部插件携带自定义框架的机制在 docs/advanced/making plugins.md 中有完整说明canvas-page正是该机制的真实范例。一个插件要提供框架需要实现PageFrame接口name、render、可选css在render()中接收全部布局槽位并返回 JSX在src/frames/index.ts中重新导出框架在package.json的exports中暴露./frames子路径并在quartzmanifest 的frames字段中声明框架元数据在构建配置如tsup.config.ts中将src/frames/index.ts加入 entry在页面类型插件的frame属性中引用框架名称。用户安装插件后Quartz 会自动从./frames导出加载框架并注册到 Frame Registry之后即可在任何页面类型或 YAML 配置覆盖中按名称使用。Quartz 内核同样内置了三种框架见 docs/layout.mddefault标准三栏被 ContentPage、FolderPage、TagPage、BasesPage 使用、full-width无侧栏的单列全宽、minimal无侧栏无头部装饰仅内容与页脚被 404 页使用。其中MinimalFrame的实现位于 quartz/components/frames/MinimalFrame.tsx其注释明确提到适用于全屏画布、信息亭、自定义落地页等沉浸式页面类型与canvas框架的设计思路一脉相承。框架最终会以data-frame属性作用在.page元素上方便你用.page[data-framecanvas]之类的选择器编写框架专属 CSS。Canvas 文件与 Quartz 的深度集成演示画布一个可直接阅读的 .canvas 实例仓库自带的 docs/Canvas.canvas 是一个结构完整的 JSON Canvas 演示文件也是理解该格式与插件能力的最好样例。它包含6 个分组节点Node Types、Configuration、Preset Colors、Edges Connections等使用预设色color: 1~6标识文本节点展示 GFM 渲染加粗、斜体、删除线、外部链接、行内代码、列表、各级标题文件节点如{type: file, file: plugins/CanvasPage.md}指向仓库内其他页面链接节点如指向 JSON Canvas 规范的外部 URL自定义十六进制颜色例如color: #ff6600多条连线fromNode/toNode/fromSide/toSide定义连接关系部分连线带label如supports、labeled edge和颜色。文件中还包含了作者在画布内整理的核心信息——配置选项表格、全屏模式交互说明、API 信息Category: Page Type、Function name:ExternalPlugin.CanvasPage()、安装命令以及 Quartz 集成要点文件节点悬停预览、深色模式自适应。这个.canvas文件本身就可作为你编写自己画布时的模板参考。画布页如何被构建与嵌入源码级原理从页面类型分发器的实现可以还原画布页的完整生命周期见 quartz/plugins/pageTypes/dispatcher.ts匹配matchPageTypeDispatcher依次遍历所有页面类型插件调用其match({ slug, fileData, cfg })判断某文件是否属于该类型——.canvas扩展名在这里被识别虚拟页生成generate支持generate的页面类型会先产出虚拟页面并推入ctx.virtualPages使它们的元数据在渲染阶段对所有页面可见转贴transclusion支持populateVirtualPageHtmlAst会把虚拟页 Body 组件渲染成 HTML 并写入vfile.data.htmlAst从而支持![[file.canvas]]这类嵌入语法——即一个.canvas文件可以被嵌入到普通 Markdown 页面中展示。注释也明确指出Body 渲染失败时转贴会回退为仅显示标题输出emit每个页面按解析出的布局调用renderPage并写出.html。在partialEmit路径下只有变更过的页面会被增量重建见 quartz/plugins/pageTypes/dispatcher.ts。也就是说Canvas 页面不仅能作为独立页面访问还能通过 Quartz 的转贴机制嵌入到其他页面中与Base文件等虚拟页面类型协同工作。与 Quartz 生态的协作点Popover 预览文件节点悬停时显示目标页面预览前提是站点启用了enablePopovers见 docs/configuration.md 与 docs/features/popover previews.mdSPA 路由画布页与其他页面一样受enableSPA控制可在不刷新的情况下导航切换深色模式画布外观会随站点主题自适应布局系统侧边栏内的组件由layout.byPageType.canvas与layout.groups统一编排可与 docs/layout-components.md 中的 Flex、MobileOnly、DesktopOnly 等工具组件组合。自定义与扩展方向调整缩放与交互通过enableInteraction、initialZoom、minZoom、maxZoom控制画布浏览体验例如大画布可设置较小的initialZoom以便一眼总览全图替换页面框架用layout.byPageType.canvas.template覆盖为default、full-width或minimal让画布页融入站点的常规排版编写自定义框架参考 quartz/components/frames/ 下DefaultFrame.tsx、FullWidthFrame.tsx、MinimalFrame.tsx的实现为画布页定制专属框架并通过[data-frame]选择器编写作用域化的样式编写自己的 .canvas 文件以 docs/Canvas.canvas 为模板直接在内容目录中放置符合 JSON Canvas 1.0 规范的画布文件即可无需任何额外代码。参考链接速查功能总览docs/features/Canvas.md插件文档配置项与特性清单docs/plugins/CanvasPage.md演示画布docs/Canvas.canvas页面框架说明与解析顺序docs/layout.md插件配置与安装命令docs/configuration.md插件提供自定义框架指南docs/advanced/making plugins.md分发器实现quartz/plugins/pageTypes/dispatcher.ts框架注册表实现quartz/components/frames/registry.tsObsidian 模板默认启用 canvas-pagequartz/cli/templates/obsidian.yaml【免费下载链接】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），仅供参考