Quartz 路径系统深度解析从文件路径到 URL 的四类名义类型与转换链路【免费下载链接】quartz a fast, batteries-included static-site generator that transforms Markdown content into fully functional websites项目地址: https://gitcode.com/GitHub_Trending/qua/quartzQuartz 是一个将 Markdown 内容转换为完整静态网站的生成器其内部对路径的处理贯穿构建全流程磁盘上的文件路径、内容 slug、浏览器中的相对 URL 都各自拥有独立的类型系统。本篇指南以 docs/advanced/paths.md 为核心骨架结合 quartz/util/path.ts、quartz/processors/parse.ts 与 quartz/util/path.test.ts 中的源码与测试用例系统讲解 Quartz 的四类路径名义类型、品牌类型branded type实现原理、各转换函数的行为契约以及链接解析策略在 CLI 与配置层面的落地方式帮助读者在开发 Quartz 插件、排查链接问题时准确区分并正确使用每一种路径类型。为什么路径在静态站点生成器中如此复杂对于一个静态站点生成器路径可以来自完全不同的场景磁盘上某篇内容的完整文件路径如content/posts/hello.md一篇内容对应的slug如posts/hello页面之间互相引用的Markdown 链接浏览器地址栏中的相对 URL如../../posts/hello。它们语义各异却又都长成字符串的样子。如果把这一切都简单声明为string开发时极容易把一种路径误当成另一种路径使用——例如把服务端文件路径直接塞给浏览器侧的逻辑而 TypeScript 却无法在编译期发现错误。Quartz 的解决方案是引入一套**名义类型nominal types**系统为每种路径赋予独立类型并在构建管线的关键入口处强制类型守卫让路径混淆这类错误在编译期或构建早期就被暴露出来。用品牌类型模拟名义类型TypeScript 的类型别名type是结构化类型没有名义类型nominal type机制——两个结构完全相同的类型别名在类型检查时被认为是兼容的。这意味着即使为服务端 slug和客户端 slug分别定义了类型别名仍然可以互相赋值而不会被编译器拦截。为了模拟名义类型Quartz 采用**品牌类型branded type**技巧在字符串类型上交叉一个带有唯一品牌标记的字段。// 错误做法完全等价于 string无法区分 type FullSlug string // 正确做法附加品牌标记形成名义上的独立类型 type FullSlug string { __brand: full } // 这样下面这行代码将无法通过类型检查 const slug: FullSlug some random string其原理在于{ __brand: full }字段只存在于类型层面运行时字符串本身并不携带该字段因此任何普通字符串字面量都无法满足FullSlug的结构约束赋值即报错。这就让把客户端 slug 误当服务端 slug这类错误在类型系统内部被拦截。不过品牌类型并非万能。文档特别强调它只能防止类型系统内部的混用例如把服务端 slug 错当成客户端 slug却无法防止开发者在使用强制类型断言as把普通字符串强行转换成某种 slug 类型。因此在所有字符串进入路径系统的入口点entrypoint仍然需要开发者保持谨慎主动调用类型守卫或转换函数。在 Quartz 源码中这些入口点即下图中的六边形节点就是getFullSlug()、slugifyFilePath()、transformLink()等函数所在的位置。路径类型全景图文档给出了一张 mermaid 图完整描绘了所有路径来源、四类名义路径类型以及 quartz/util/path.ts 中负责在它们之间转换的函数从图中可以看出FullSlug是整个路径系统的枢纽图中加粗表示。浏览器一侧通过getFullSlug()从window.location得到当前页面的FullSlugMarkdown 文件一侧则通过slugifyFilePath()把磁盘文件路径转化为FullSlug。之后FullSlug可以再经simplifySlug()降级为SimpleSlug再经pathToRoot()或resolveRelative()得到最终的RelativeURL。这一设计在源码中的实现体现为path.ts从quartz-community/utils重新导出全部路径工具getFullSlug、slugifyFilePath、simplifySlug、pathToRoot、resolveRelative、transformLink等及全部类型FilePath、FullSlug、SimpleSlug、RelativeURL同时额外导出了normalizeRelativeURLs用于在客户端把文档中相对形式的href/src按当前地址重基见 quartz/util/path.ts。四类核心路径类型文档对四类主要路径类型给出了精确定义这是理解整个路径系统的关键类型核心约束典型示例FilePath磁盘上真实存在的文件路径不能是相对路径必须带有文件扩展名content/posts/hello.mdFullSlug不能是相对路径不允许前导/尾随斜杠最后一段可以是index。它是最通用的 slug 解释尽可能优先使用posts/hello、posts/indexSimpleSlug不能是相对路径末尾不应是/index不应带文件扩展名可以以尾随斜杠表示文件夹路径posts/、posts/helloRelativeURL必须以.或..开头以表示相对 URL末尾不应是/index不应带文件扩展名但可以包含尾随斜杠./posts/hello、../../这些约束并非纸面约定而是被硬编码进了类型守卫函数中并由 quartz/util/path.test.ts 中的typeguards测试组逐条验证。例如isSimpleSlug接受、abc、abc/、notindex/def拒绝//、index、/abc、abc/index、abc#anchor、abc?query1、index.md见 quartz/util/path.test.tsisRelativeURL接受.、..、./abc/def、./abc/def#an-anchor、./abc/def.pdf拒绝abc、/abc/def、./abc/def.html、./abc/def.md见 quartz/util/path.test.tsisFullSlug接受index、abc/def、html.energy、test.pdf拒绝相对路径、带锚点/查询串的字符串以及含空格的note with spaces见 quartz/util/path.test.tsisFilePath接受content/index.md、content/test.png拒绝../test.pdf、无扩展名的content/test见 quartz/util/path.test.ts。这些测试清晰地展示了每个类型的合法值域是理解路径语义的最佳参考。核心转换函数的行为契约path.test.ts的transforms测试组给出了每个转换函数最精确的输入输出契约下面逐一展开。simplifySlugFullSlug → SimpleSlug把FullSlug简化为SimpleSlug的核心逻辑是处理index段输入FullSlug输出SimpleSlugindex/abcabcabc/indexabc/abc/defabc/def可见abc/index被规范化为带尾随斜杠的文件夹路径abc/而顶级index则被规范化为/见 quartz/util/path.test.ts。slugifyFilePathFilePath → FullSlug这是磁盘文件 → 内容 slug的关键入口负责去掉扩展名、规范化特殊字符并实现 Obsidian 风格的文件夹笔记Folder Note约定输入FilePath输出FullSlugcontent/index.mdcontent/indexcontent/index.htmlcontent/indexcontent/_index.mdcontent/index/content/index.mdcontent/indexcontent/cool.pngcontent/cool.pngnote with spaces.mdnote-with-spacesnotes.with.dots.mdnotes.with.dotstest/special chars?.mdtest/special-charstest/special chars #3.mdtest/special-chars-3cool/what about rd?.mdcool/what-about-r-and-d值得注意的细节包括_index.md会被重写为index带空格和?、#、等特殊字符的文件名会被 slug 化?被删除、变成-and-而多段文件名中的点号如notes.with.dots.md会被保留不会与扩展名混淆。该函数还实现了Obsidian 文件夹笔记约定folder/folder.md形式的文件末两段同名会被视为该文件夹的落地页重写为folder/index例如characters/characters.md→characters/indexfiction/books/books.md→fiction/books/indexa/a/a.md→a/a/index同时有一系列边界规则顶级单段characters.md不重写末两段不同名characters/alice.md不重写更深层同名的characters/sub/characters.md也不重写而文件夹本身名叫index的情况index/index.md、docs/index/index.md保持原样见 quartz/util/path.test.ts。测试还验证了一个端到端一致性无论用户采用characters/index.md还是 Obsidian 的characters/characters.md约定simplifySlug(slugifyFilePath(...))最终都会得到相同的用户可见 URLcharacters/见 quartz/util/path.test.ts。在构建流程中slugifyFilePath被用于把每个 Markdown 文件的相对路径转换为 slug 并写入file.data.slug见 quartz/processors/parse.ts同时用于生成全站 slug 列表ctx.allSlugs见 quartz/build.ts和静态资源如图片、PDF的 slug 化见 quartz/plugins/emitters/assets.ts。pathToRootSimpleSlug → RelativeURL根据当前页面 slug 的深度计算回到站点根目录所需的相对路径输入FullSlug输出RelativeURLindex.abc.abc/def..abc/def/ghi../..abc/def/index../..规则很直观slug 有几层目录就向上回溯几级index段不增加层级深度见 quartz/util/path.test.ts。该函数主要用于定位全局资源如站点级样式、脚本、图标在每页输出 HTML 中的相对前缀。resolveRelativeFullSlug → RelativeURL计算从当前页面到目标页面的相对 URL是pathToRoot的通用化版本从顶级页index出发index → ./index → abc得./abcindex → abc/def得./abc/def从嵌套页abc/def出发→index得../→abc得../abc→abc/def得../abc/def→ghi/jkl得../ghi/jkl含index路径时abc/index → index得../abc/def/index → index得../../index → abc/index得./abc/见 quartz/util/path.test.ts。joinSegments安全拼接路径段joinSegments负责按/拼接路径段同时保留首尾斜杠与协议前缀joinSegments(a, b) // a/b joinSegments(a/, b/) // a/b/ joinSegments(/a, b) // /a/b joinSegments(/a/, b, /) // /a/b/ joinSegments(https://example.com, a) // https://example.com/a它支持协议说明符https://example.com后接段不会丢失//见 quartz/util/path.test.ts。链接转换transformLink 与三种解析策略Markdown 文件中的链接Links经transformLink()转换为相对 URL 是图中另一条关键链路。从源码看transformLink与transformInternalLink是内部链接转换的核心实现均从quartz-community/utils重新导出见 quartz/util/path.ts而transformInternalLink负责把笔记间链接规范化成相对 URL测试覆盖了锚点、查询串、index折叠、URL 编码空格与文件夹笔记约定等大量场景输入输出RelativeURL./index././index#abc./#abc./index.md./content/test.md./content/test../content/test.md../content/test/tags/./tags/content/with spaces./content/with-spacescontent/with spaces#and Anchor!./content/with-spaces#and-anchorcharacters/characters./characters/My%20Folder/My%20Note./my-folder/my-note完整用例见 quartz/util/path.test.ts。注意这里同样应用了文件夹笔记约定characters/characters会被折叠为./characters/My Folder/My Folder#heading会变成./my-folder/#heading锚点与查询串会被 slug 化并保留。transformLink的link strategies测试组则揭示了三种链接解析策略absolute/shortest/relative的完整行为矩阵见 quartz/util/path.test.ts。以页面a/b/c为例absolute 策略按 slug 的绝对路径计算相对引用a/b/d→../../a/b/da/b/index→../../a/b/index→../../shortest 策略先在allSlugs中查找能唯一定位目标的最短 slug如d解析为../../a/b/d、h解析为../../e/g/h找不到则退化为绝对路径relative 策略只处理当前目录内的链接d→./dindex→./对../../../形式的外部引用保持原样。从源码结构看TransformOptions包含strategy与allSlugs字段见 quartz/util/path.ts正是transformLink的配置输入allSlugs为shortest策略提供全站 slug 索引。三种策略在 CLI 与配置中的落地链接解析策略不仅是纯函数参数还贯通了 Quartz 的初始化 CLI 与 YAML 配置两个层面。在 quartz/cli/args.js 中quartz create提供了-l, --links参数取值限定为absolute/shortest/relative描述为strategy to resolve links。交互流程中见 quartz/cli/handlers.js使用obsidian或ttrpg模板时策略自动预设为shortest以匹配 Obsidian 的链接格式否则 CLI 会弹出选择提示默认推荐shortest。随后该策略被写入crawl-links插件的options.markdownLinkResolution字段并同时更新配置中的baseUrl见 quartz/cli/handlers.js。四个内置模板default.yaml、obsidian.yaml、blog.yaml、ttrpg.yaml均默认写入markdownLinkResolution: shortest。因此对于绝大多数用户shortest就是开箱即用的默认链接解析策略如需改为absolute或relative可在quartz.config.yaml中修改crawl-links插件的markdownLinkResolution选项。浏览器端入口getFullSlug 与 normalizeRelativeURLs回到图中的浏览器侧getFullSlug()从window.location提取当前页面的FullSlug是URL → 路径系统的客户端入口。它在 SPA 客户端脚本中被用于导航通知见 quartz/components/scripts/spa.inline.ts与normalizeRelativeURLs配合在无刷新跳转后将文档中./、../形式的href与src按新页面地址重基见 quartz/util/path.ts。这也解释了为什么文档强调FullSlug是最通用的解释——它同时是服务端构建与浏览器端 SPA 两条链路共享的中间表示。实践要点与排查建议综合文档、源码与测试可以沉淀出以下实践建议优先使用FullSlug它是路径系统的枢纽与最通用解释插件或组件中表达一篇内容时应优先采用避免在SimpleSlug/RelativeURL之间反复横跳。在入口点做显式转换品牌类型只能防类型系统内部混用任何string → 路径类型的转换都应通过slugifyFilePath、getFullSlug、transformLink等入口函数完成而不是直接as断言。记住三类约束的差异FilePath必须带扩展名FullSlug允许末段为indexSimpleSlug与RelativeURL用尾随斜杠表达文件夹语义且RelativeURL必须以./..开头。链接失效时先检查策略absolute/shortest/relative的输出差异巨大若发现构建产物中的链接不符合预期先确认quartz.config.yaml中crawl-links的markdownLinkResolution取值再对照 quartz/util/path.test.ts 的link strategies测试组逐条核验。利用测试作为行为文档path.test.ts的typeguards、transforms、link strategies、resolveRelative四个测试组是路径系统最精确、最可执行的规格说明任何对路径语义的疑问都应优先在此求证。通过本文的梳理可以看到Quartz 并没有把路径当作可以随意对待的字符串而是用品牌类型建立了严格的四类名义类型并用一套清晰的转换函数与测试矩阵将其固化下来。理解这套系统是深入 Quartz 插件开发与链接调试的坚实基础。【免费下载链接】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 路径系统深度解析：从文件路径到 URL 的四类名义类型与转换链路
Quartz 路径系统深度解析从文件路径到 URL 的四类名义类型与转换链路【免费下载链接】quartz a fast, batteries-included static-site generator that transforms Markdown content into fully functional websites项目地址: https://gitcode.com/GitHub_Trending/qua/quartzQuartz 是一个将 Markdown 内容转换为完整静态网站的生成器其内部对路径的处理贯穿构建全流程磁盘上的文件路径、内容 slug、浏览器中的相对 URL 都各自拥有独立的类型系统。本篇指南以 docs/advanced/paths.md 为核心骨架结合 quartz/util/path.ts、quartz/processors/parse.ts 与 quartz/util/path.test.ts 中的源码与测试用例系统讲解 Quartz 的四类路径名义类型、品牌类型branded type实现原理、各转换函数的行为契约以及链接解析策略在 CLI 与配置层面的落地方式帮助读者在开发 Quartz 插件、排查链接问题时准确区分并正确使用每一种路径类型。为什么路径在静态站点生成器中如此复杂对于一个静态站点生成器路径可以来自完全不同的场景磁盘上某篇内容的完整文件路径如content/posts/hello.md一篇内容对应的slug如posts/hello页面之间互相引用的Markdown 链接浏览器地址栏中的相对 URL如../../posts/hello。它们语义各异却又都长成字符串的样子。如果把这一切都简单声明为string开发时极容易把一种路径误当成另一种路径使用——例如把服务端文件路径直接塞给浏览器侧的逻辑而 TypeScript 却无法在编译期发现错误。Quartz 的解决方案是引入一套**名义类型nominal types**系统为每种路径赋予独立类型并在构建管线的关键入口处强制类型守卫让路径混淆这类错误在编译期或构建早期就被暴露出来。用品牌类型模拟名义类型TypeScript 的类型别名type是结构化类型没有名义类型nominal type机制——两个结构完全相同的类型别名在类型检查时被认为是兼容的。这意味着即使为服务端 slug和客户端 slug分别定义了类型别名仍然可以互相赋值而不会被编译器拦截。为了模拟名义类型Quartz 采用**品牌类型branded type**技巧在字符串类型上交叉一个带有唯一品牌标记的字段。// 错误做法完全等价于 string无法区分 type FullSlug string // 正确做法附加品牌标记形成名义上的独立类型 type FullSlug string { __brand: full } // 这样下面这行代码将无法通过类型检查 const slug: FullSlug some random string其原理在于{ __brand: full }字段只存在于类型层面运行时字符串本身并不携带该字段因此任何普通字符串字面量都无法满足FullSlug的结构约束赋值即报错。这就让把客户端 slug 误当服务端 slug这类错误在类型系统内部被拦截。不过品牌类型并非万能。文档特别强调它只能防止类型系统内部的混用例如把服务端 slug 错当成客户端 slug却无法防止开发者在使用强制类型断言as把普通字符串强行转换成某种 slug 类型。因此在所有字符串进入路径系统的入口点entrypoint仍然需要开发者保持谨慎主动调用类型守卫或转换函数。在 Quartz 源码中这些入口点即下图中的六边形节点就是getFullSlug()、slugifyFilePath()、transformLink()等函数所在的位置。路径类型全景图文档给出了一张 mermaid 图完整描绘了所有路径来源、四类名义路径类型以及 quartz/util/path.ts 中负责在它们之间转换的函数从图中可以看出FullSlug是整个路径系统的枢纽图中加粗表示。浏览器一侧通过getFullSlug()从window.location得到当前页面的FullSlugMarkdown 文件一侧则通过slugifyFilePath()把磁盘文件路径转化为FullSlug。之后FullSlug可以再经simplifySlug()降级为SimpleSlug再经pathToRoot()或resolveRelative()得到最终的RelativeURL。这一设计在源码中的实现体现为path.ts从quartz-community/utils重新导出全部路径工具getFullSlug、slugifyFilePath、simplifySlug、pathToRoot、resolveRelative、transformLink等及全部类型FilePath、FullSlug、SimpleSlug、RelativeURL同时额外导出了normalizeRelativeURLs用于在客户端把文档中相对形式的href/src按当前地址重基见 quartz/util/path.ts。四类核心路径类型文档对四类主要路径类型给出了精确定义这是理解整个路径系统的关键类型核心约束典型示例FilePath磁盘上真实存在的文件路径不能是相对路径必须带有文件扩展名content/posts/hello.mdFullSlug不能是相对路径不允许前导/尾随斜杠最后一段可以是index。它是最通用的 slug 解释尽可能优先使用posts/hello、posts/indexSimpleSlug不能是相对路径末尾不应是/index不应带文件扩展名可以以尾随斜杠表示文件夹路径posts/、posts/helloRelativeURL必须以.或..开头以表示相对 URL末尾不应是/index不应带文件扩展名但可以包含尾随斜杠./posts/hello、../../这些约束并非纸面约定而是被硬编码进了类型守卫函数中并由 quartz/util/path.test.ts 中的typeguards测试组逐条验证。例如isSimpleSlug接受、abc、abc/、notindex/def拒绝//、index、/abc、abc/index、abc#anchor、abc?query1、index.md见 quartz/util/path.test.tsisRelativeURL接受.、..、./abc/def、./abc/def#an-anchor、./abc/def.pdf拒绝abc、/abc/def、./abc/def.html、./abc/def.md见 quartz/util/path.test.tsisFullSlug接受index、abc/def、html.energy、test.pdf拒绝相对路径、带锚点/查询串的字符串以及含空格的note with spaces见 quartz/util/path.test.tsisFilePath接受content/index.md、content/test.png拒绝../test.pdf、无扩展名的content/test见 quartz/util/path.test.ts。这些测试清晰地展示了每个类型的合法值域是理解路径语义的最佳参考。核心转换函数的行为契约path.test.ts的transforms测试组给出了每个转换函数最精确的输入输出契约下面逐一展开。simplifySlugFullSlug → SimpleSlug把FullSlug简化为SimpleSlug的核心逻辑是处理index段输入FullSlug输出SimpleSlugindex/abcabcabc/indexabc/abc/defabc/def可见abc/index被规范化为带尾随斜杠的文件夹路径abc/而顶级index则被规范化为/见 quartz/util/path.test.ts。slugifyFilePathFilePath → FullSlug这是磁盘文件 → 内容 slug的关键入口负责去掉扩展名、规范化特殊字符并实现 Obsidian 风格的文件夹笔记Folder Note约定输入FilePath输出FullSlugcontent/index.mdcontent/indexcontent/index.htmlcontent/indexcontent/_index.mdcontent/index/content/index.mdcontent/indexcontent/cool.pngcontent/cool.pngnote with spaces.mdnote-with-spacesnotes.with.dots.mdnotes.with.dotstest/special chars?.mdtest/special-charstest/special chars #3.mdtest/special-chars-3cool/what about rd?.mdcool/what-about-r-and-d值得注意的细节包括_index.md会被重写为index带空格和?、#、等特殊字符的文件名会被 slug 化?被删除、变成-and-而多段文件名中的点号如notes.with.dots.md会被保留不会与扩展名混淆。该函数还实现了Obsidian 文件夹笔记约定folder/folder.md形式的文件末两段同名会被视为该文件夹的落地页重写为folder/index例如characters/characters.md→characters/indexfiction/books/books.md→fiction/books/indexa/a/a.md→a/a/index同时有一系列边界规则顶级单段characters.md不重写末两段不同名characters/alice.md不重写更深层同名的characters/sub/characters.md也不重写而文件夹本身名叫index的情况index/index.md、docs/index/index.md保持原样见 quartz/util/path.test.ts。测试还验证了一个端到端一致性无论用户采用characters/index.md还是 Obsidian 的characters/characters.md约定simplifySlug(slugifyFilePath(...))最终都会得到相同的用户可见 URLcharacters/见 quartz/util/path.test.ts。在构建流程中slugifyFilePath被用于把每个 Markdown 文件的相对路径转换为 slug 并写入file.data.slug见 quartz/processors/parse.ts同时用于生成全站 slug 列表ctx.allSlugs见 quartz/build.ts和静态资源如图片、PDF的 slug 化见 quartz/plugins/emitters/assets.ts。pathToRootSimpleSlug → RelativeURL根据当前页面 slug 的深度计算回到站点根目录所需的相对路径输入FullSlug输出RelativeURLindex.abc.abc/def..abc/def/ghi../..abc/def/index../..规则很直观slug 有几层目录就向上回溯几级index段不增加层级深度见 quartz/util/path.test.ts。该函数主要用于定位全局资源如站点级样式、脚本、图标在每页输出 HTML 中的相对前缀。resolveRelativeFullSlug → RelativeURL计算从当前页面到目标页面的相对 URL是pathToRoot的通用化版本从顶级页index出发index → ./index → abc得./abcindex → abc/def得./abc/def从嵌套页abc/def出发→index得../→abc得../abc→abc/def得../abc/def→ghi/jkl得../ghi/jkl含index路径时abc/index → index得../abc/def/index → index得../../index → abc/index得./abc/见 quartz/util/path.test.ts。joinSegments安全拼接路径段joinSegments负责按/拼接路径段同时保留首尾斜杠与协议前缀joinSegments(a, b) // a/b joinSegments(a/, b/) // a/b/ joinSegments(/a, b) // /a/b joinSegments(/a/, b, /) // /a/b/ joinSegments(https://example.com, a) // https://example.com/a它支持协议说明符https://example.com后接段不会丢失//见 quartz/util/path.test.ts。链接转换transformLink 与三种解析策略Markdown 文件中的链接Links经transformLink()转换为相对 URL 是图中另一条关键链路。从源码看transformLink与transformInternalLink是内部链接转换的核心实现均从quartz-community/utils重新导出见 quartz/util/path.ts而transformInternalLink负责把笔记间链接规范化成相对 URL测试覆盖了锚点、查询串、index折叠、URL 编码空格与文件夹笔记约定等大量场景输入输出RelativeURL./index././index#abc./#abc./index.md./content/test.md./content/test../content/test.md../content/test/tags/./tags/content/with spaces./content/with-spacescontent/with spaces#and Anchor!./content/with-spaces#and-anchorcharacters/characters./characters/My%20Folder/My%20Note./my-folder/my-note完整用例见 quartz/util/path.test.ts。注意这里同样应用了文件夹笔记约定characters/characters会被折叠为./characters/My Folder/My Folder#heading会变成./my-folder/#heading锚点与查询串会被 slug 化并保留。transformLink的link strategies测试组则揭示了三种链接解析策略absolute/shortest/relative的完整行为矩阵见 quartz/util/path.test.ts。以页面a/b/c为例absolute 策略按 slug 的绝对路径计算相对引用a/b/d→../../a/b/da/b/index→../../a/b/index→../../shortest 策略先在allSlugs中查找能唯一定位目标的最短 slug如d解析为../../a/b/d、h解析为../../e/g/h找不到则退化为绝对路径relative 策略只处理当前目录内的链接d→./dindex→./对../../../形式的外部引用保持原样。从源码结构看TransformOptions包含strategy与allSlugs字段见 quartz/util/path.ts正是transformLink的配置输入allSlugs为shortest策略提供全站 slug 索引。三种策略在 CLI 与配置中的落地链接解析策略不仅是纯函数参数还贯通了 Quartz 的初始化 CLI 与 YAML 配置两个层面。在 quartz/cli/args.js 中quartz create提供了-l, --links参数取值限定为absolute/shortest/relative描述为strategy to resolve links。交互流程中见 quartz/cli/handlers.js使用obsidian或ttrpg模板时策略自动预设为shortest以匹配 Obsidian 的链接格式否则 CLI 会弹出选择提示默认推荐shortest。随后该策略被写入crawl-links插件的options.markdownLinkResolution字段并同时更新配置中的baseUrl见 quartz/cli/handlers.js。四个内置模板default.yaml、obsidian.yaml、blog.yaml、ttrpg.yaml均默认写入markdownLinkResolution: shortest。因此对于绝大多数用户shortest就是开箱即用的默认链接解析策略如需改为absolute或relative可在quartz.config.yaml中修改crawl-links插件的markdownLinkResolution选项。浏览器端入口getFullSlug 与 normalizeRelativeURLs回到图中的浏览器侧getFullSlug()从window.location提取当前页面的FullSlug是URL → 路径系统的客户端入口。它在 SPA 客户端脚本中被用于导航通知见 quartz/components/scripts/spa.inline.ts与normalizeRelativeURLs配合在无刷新跳转后将文档中./、../形式的href与src按新页面地址重基见 quartz/util/path.ts。这也解释了为什么文档强调FullSlug是最通用的解释——它同时是服务端构建与浏览器端 SPA 两条链路共享的中间表示。实践要点与排查建议综合文档、源码与测试可以沉淀出以下实践建议优先使用FullSlug它是路径系统的枢纽与最通用解释插件或组件中表达一篇内容时应优先采用避免在SimpleSlug/RelativeURL之间反复横跳。在入口点做显式转换品牌类型只能防类型系统内部混用任何string → 路径类型的转换都应通过slugifyFilePath、getFullSlug、transformLink等入口函数完成而不是直接as断言。记住三类约束的差异FilePath必须带扩展名FullSlug允许末段为indexSimpleSlug与RelativeURL用尾随斜杠表达文件夹语义且RelativeURL必须以./..开头。链接失效时先检查策略absolute/shortest/relative的输出差异巨大若发现构建产物中的链接不符合预期先确认quartz.config.yaml中crawl-links的markdownLinkResolution取值再对照 quartz/util/path.test.ts 的link strategies测试组逐条核验。利用测试作为行为文档path.test.ts的typeguards、transforms、link strategies、resolveRelative四个测试组是路径系统最精确、最可执行的规格说明任何对路径语义的疑问都应优先在此求证。通过本文的梳理可以看到Quartz 并没有把路径当作可以随意对待的字符串而是用品牌类型建立了严格的四类名义类型并用一套清晰的转换函数与测试矩阵将其固化下来。理解这套系统是深入 Quartz 插件开发与链接调试的坚实基础。【免费下载链接】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），仅供参考