Quartz 日期元数据插件 CreatedModifiedDate 全解析frontmatter、Git 与文件系统三种日期来源的优先级与配置实战【免费下载链接】quartz a fast, batteries-included static-site generator that transforms Markdown content into fully functional websites项目地址: https://gitcode.com/GitHub_Trending/qua/quartz本指南系统讲解 Quartz 静态站点生成器中的日期元数据插件CreatedModifiedDate它如何从 frontmatter、Git 历史与文件系统三种数据源中确定一篇文档的创建created、修改modified与发布published日期如何通过priority与defaultDateType两个选项精确控制取数与展示行为以及日期数据最终如何被 Date.tsx 组件渲染、被 PageList.tsx 用于排序。阅读完本文你将掌握该插件的完整配置方式、frontmatter 日期字段的合法写法以及部署场景下选择正确日期来源的最佳实践。插件定位文档日期从哪来CreatedModifiedDate 是一个Transformer 类Category: Transformer的外部插件其职责是在构建流水线中为每个页面解析出三种日期created创建日期modified修改日期published发布日期它通过三种潜在数据源按优先级依次取值frontmatter 元数据、Git 历史与文件系统filesystem。该插件本身托管在quartz-community社区仓库quartz-community/created-modified-date并非内置插件需要安装后启用详见其官方插件说明 CreatedModifiedDate 页面。在 Quartz 5 的新版配置体系quartz.config.default.yaml中该插件以quartz-community/created-modified-date为 source 被声明为默认启用的 Transformer并设置了order: 10——这意味着它在各 Transformer 中较早执行保证后续依赖日期的组件如 ContentMeta、RecentNotes能拿到完整数据。安装与启用通过 CLI 添加外部插件由于 CreatedModifiedDate 是社区外部插件需要先安装再在配置中启用。安装命令由插件文档的 API 一节给出npx quartz plugin add github:quartz-community/created-modified-date安装机制的底层实现位于 install-plugins.ts它会读取quartz.js中导出的externalPlugins列表或回退解析quartz.config.yaml旧版为quartz.plugins.json中的plugins条目把启用状态enabled ! false的插件源交给 gitLoader.ts 执行 Git 克隆与安装。因此你也可以直接在配置文件的plugins列表里声明该插件并设置enabled: true。配置选项详解该插件接受以下两个配置选项priority日期来源的取值优先级含义按优先级从高到低列出需要咨询的数据源。可选值frontmatter、git、filesystem。默认值[frontmatter, git, filesystem]。处理逻辑为先读 frontmatter 中的日期字段若缺失则回退到 Git 提交历史通常是首次提交时间与最近提交时间若再缺失才使用文件系统的时间戳。默认顺序符合“以作者显式声明的元数据为准其次相信版本控制最后退化为文件 mtime”的常规预期。defaultDateType展示时使用哪种日期含义渲染页面元信息时默认展示的日期类型。可选值created、modified、published。默认值modified。该选项决定站点页面上“日期”一栏最终显示的是哪一个日期字段直接影响 Date.tsx 中的取值逻辑export function getDate(data: QuartzPluginData): Date | undefined { if (!data.defaultDateType) { throw new Error( Field defaultDateType was not set. Ensure the CreatedModifiedDate plugin is configured with a defaultDateType option. ..., ) } return data.dates?.[data.defaultDateType] }注意如果插件未配置defaultDateType构建/渲染时会直接抛出异常。同时QuartzPluginData定义见 vfile.ts上的dates字段是按created | modified | published三个键组织的数据结构见 Date.tsx 中ValidDateType keyof RequiredQuartzPluginData[dates]组件按defaultDateType指定的键从中取具体日期。默认配置示例来自仓库默认配置文件quartz.config.default.yaml 中该插件的完整配置如下可作为直接复制使用的参考- source: quartz-community/created-modified-date enabled: true options: defaultDateType: modified priority: - frontmatter - git - filesystem order: 10此外quartz/cli/templates 下的default.yaml、obsidian.yaml、blog.yaml、ttrpg.yaml四种站点模板也都内置了同样的defaultDateType: modified配置说明“以修改日期为默认展示”是 Quartz 生态的推荐默认行为。frontmatter 日期字段的合法写法当priority中包含frontmatter时插件会读取页面 frontmatter 中的日期字段。根据 Frontmatter 插件的字段定义表Quartz 支持的日期键及别名如下日期类型合法键别名按匹配先后取第一个说明Created创建created、date笔记的创建时间Modified修改modified、lastmod、updated、last-modified最后修改时间未设置时回退到createdPublished发布published、publishDate、date笔记的发布时间authoring-content 文档同时指出frontmatter 中的date字段一般使用YYYY-MM-DD字符串格式正是由CreatedModifiedDate插件负责解析的——title、tags、aliases、cssclasses归 Frontmatter 插件处理description归 Description 插件处理。因此若你在 frontmatter 中声明了日期但页面没有正确显示应先确认 CreatedModifiedDate 插件处于启用状态且priority包含frontmatter。一个完整的 frontmatter 示例--- title: 我的笔记 created: 2026-01-10 modified: 2026-02-18 published: 2026-02-01 ---日期数据的消费链路从解析到渲染与排序日期被插件解析进vfile.data.dates之后会在站点的多个位置被消费格式化与渲染Date.tsx 中的formatDate使用toLocaleDateString按year: numeric, month: short, day: 2-digit格式化日期并输出语义化的time datetime{...}标签locale取自站点的全局配置默认en-US。页面元信息ContentMeta 等页面组件调用getDate(data)拿到默认日期展示在文章头部。列表排序PageList.tsx 在排序 RecentNotes、标签页/文件夹页列表时通过getDate(f2)!.getTime() - getDate(f1)!.getTime()按日期倒序排列笔记并在每行以Date date{getDate(page)!} locale{cfg.locale} /渲染日期。因此一旦 CreatedModifiedDate 未配置或解析失败整个站点的日期展示与排序都会受影响。使用 Git / 文件系统日期来源时的注意事项插件文档对非 frontmatter 的日期来源给出了两条明确的警告实践中务必遵守[!warning]依赖git日期时必须把defaultDateType设为modified。 因为 Git 历史天然只能提供“文件何时被加入/提交”的信息将其作为created展示通常没有意义保持默认的modified才能得到合理的展示结果。[!warning]不同托管方式下filesystem日期可能不准。 本地文件的 mtime 经过 git 提交、CI 构建、CDN 缓存后最终服务器上文件的时间戳往往与本地不一致。如果你的站点通过 CI/CD 或容器化方式部署参见 hosting更可靠的做法是优先使用git或frontmatter来源以保证最终呈现的日期正确。与其他文档的关联插件的增删改与整体配置方法见 Configuration 页面。frontmatter 的语法与date字段说明见 authoring content。支持的 frontmatter 字段完整列表见 Frontmatter。该插件负责填充的dates数据最终由 Date.tsx 组件消费若渲染报错“Field defaultDateType was not set”请回到本插件的options.defaultDateType配置排查。API 速查Category: Transformer函数名:ExternalPlugin.CreatedModifiedDate()源码:quartz-community/created-modified-date外部社区仓库安装:npx quartz plugin add github:quartz-community/created-modified-date是否必须: 否required: false但若你的站点依赖日期展示或列表排序建议保持启用【免费下载链接】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），仅供参考