Hugo 页面日期Page.Datefront matter 日期解析、time.Format本地化与源码实现解析【免费下载链接】hugoThe world’s fastest framework for building websites.项目地址: https://gitcode.com/gh_mirrors/hu/hugo导读本文围绕 Hugo 页面方法Date展开讲解它如何返回页面在 front matter 中声明的日期、为什么该返回值是time.Time类型以及如何通过time.Format进行格式化与本地化输出。同时结合当前 Hugo 仓库源码page__meta.go与测试用例dates_test.go、page_test.go深入说明Date的底层取值逻辑、front matter 日期配置项[frontmatter]的优先级机制与真实使用场景。读完本文你将能在自己的 Hugo 站点中正确设置、回退、格式化并多语言本地化页面日期。方法签名与返回值类型Date是 Hugo 页面对象Page上的一个方法其完整签名为项目值方法名Date返回类型time.TimeGo 标准库时间类型签名PAGE.Date在 Hugo 官方文档中该方法对应的元信息为returnType: time.Time、signatures: [PAGE.Date]见 docs/content/en/methods/page/Date.md 头部 front matter。正因为返回的是 Go 的time.Time值模板中可以对它做三类操作直接用time.Format函数格式化为字符串传给time相关的任意方法使用如比较、计算时间差传给 Hugo 内置的任意time函数族处理time.Now、time.AsTime等或配合dateFormat等旧式函数。在 front matter 中设置日期Date方法最常见的取值来源是页面 front matter 中的date字段。以下是一个标准的 TOML front matter 示例该示例来自 Date.mdtitle Article 1 date 2023-10-19T00:40:04-07:00注意这里使用了带时区偏移的 RFC 3339 时间格式2023-10-19T00:40:04-07:00。时区偏移-07:00会保留在time.Time值中直接影响time.Format的本地化输出。日期字段在 YAML、TOML、JSON 等 front matter 格式中均可设置Hugo 统一将它们解析为time.Time--- title: Article 1 date: 2023-10-19T00:40:04-07:00 ---在模板中使用{{ .Date | time.Format :date_medium }} → Oct 19, 2023time.Format支持 Go 布局字符串如2006-01-02以及 Hugo 预定义的快捷格式如:date_medium后者还会遵循站点的language配置自动本地化。[!NOTE]date字段在 front matter 中通常被视为“创建日期”但你可以通过站点配置改变它的含义及其对站点行为如排序、RSS、sitemap 等的影响。详细说明见本文“日期解析顺序配置”一节及 config/allconfig/alldecoders.go 中的frontmatter解码实现。源码视角Date的底层实现从源码看Date方法最终读取的是页面配置中的Dates.Date字段// hugolib/page__meta.go func (m *pageMeta) Date() time.Time { return m.pageConfig.Dates.Date }与之并列的还有PublishDate、ExpiryDate、Lastmod三个日期方法它们分别读取Dates结构体中的PublishDate、ExpiryDate、Lastmod字段见 page__meta.go。这说明 Hugo 将页面相关的多个日期统一放在Dates结构中Date只是其中第一个维度。真正的日期解析发生在构建阶段Hugo 在setMetaPostParams中构造一个pagemeta.FrontMatterDescriptor其中包含页面配置、基础文件名、文件修改时间ModTime、Git 提交作者时间GitAuthorDate、站点语言时区Location与页面路径/标题然后调用frontmatterHandler.HandleDates完成日期赋值见 page__meta.go。从这段实现可以推断Date的取值不限于 front matter 的date字段还可能与文件名、文件修改时间、Git 时间相关具体由配置决定Location站点语言时区被传入解析器因此同一时间戳在不同语言/时区站点下会按各自时区解释原始日期值会被保存一份datesOriginal以便增量重建时重复聚合计算见 page__meta.go。日期解析顺序配置front matter 回退机制如果 front matter 中没有定义dateHugo 默认会使用文件系统的创建/修改时间等作为回退。这一行为可通过站点配置的[frontmatter]段完全定制。配置项语法为数组按优先级从高到低排列Hugo 会依次尝试直到取到有效值# hugo.toml [frontmatter] date [date, :filename, :fileModTime] lastmod [:git, lastmod, date] publishDate [publishDate, date] expiryDate [expiryDate]支持的取值包括取值含义date/publishDate/lastmod/expiryDate读取 front matter 中对应字段名:filename从内容文件名解析日期如2012-02-21-noslug.md会解析出2012-02-21:fileModTime使用文件的修改时间:git使用 Git 提交作者时间:lastmod使用 front matter 的lastmod字段:default使用 Hugo 内置默认值该配置在站点加载阶段通过pagemeta.DecodeFrontMatterConfig解码见 config/allconfig/alldecoders.go。测试验证:filename与:fileModTime回退仓库中的 page_test.go 通过TestPageWithFrontMatterConfig验证了回退逻辑。测试对每个日期处理器依次运行配置为[frontmatter] date [:filename, date]并创建内容文件content/section/2012-02-21-noslug.md与content/section/2012-02-22-slug.md二者 front matter 中均无date字段仅含lastMod。测试断言使用:filename时noSlug.Date().Year()等于2012说明 Hugo 成功从文件名解析出了日期若 front matter 中存在date则date字段优先级高于:filename配置数组中date位于:filename之后作为回退项Lastmod仍取 front matter 中的lastMod: 2018-02-28与Date走不同的配置链。这组测试同时印证了Date与Lastmod是相互独立的取值逻辑分别受frontmatter.date与frontmatter.lastmod配置控制。时区、多语言与本地化输出Date返回的time.Time携带时区信息time.Format在渲染时会结合站点的语言与时区设置进行本地化。仓库中的 dates_test.go 提供了两个典型验证场景多语言本地化TestDateFormatMultilingual见 dates_test.go站点配置defaultContentLanguage en且defaultContentLanguageInSubDir true同一页面date: 2021-07-18在英文与挪威语nn两个语言下分别渲染为Date: July 18, 2021 # en Date: 18. juli 2021 # nn这证明time.Format :date_long会依据当前语言自动选择日期显示习惯无需手写多套模板。时区解析TestTimeZones见 dates_test.go测试覆盖 YAML 与 TOML 两种 front matter 格式并同时声明date、lastMod、publishDate、expiryDate四个字段验证带/不带时间的日期字符串如2024-07-18与2024-07-18 15:28:01均能被正确解析为time.Time。实际站点中的典型用法article time datetime{{ .Date.Format 2006-01-02T15:04:05Z07:00 }} {{ .Date | time.Format :date_full }} /time /articledatetime属性使用机器可读的 ISO 8601 格式利于 SEO 与无障碍可见文本使用:date_full之类的人类可读格式。常见使用模式与注意事项1. 按日期排序默认情况下Hugo 使用Date作为正则页面排序的主要依据之一{{ range .Site.RegularPages.ByDate }} li{{ .Title }} — {{ .Date | time.Format 2006-01-02 }}/li {{ end }}2. 判断日期是否已设置front matter 未提供任何有效日期来源时Date返回零值时间。可用IsZero判断{{ if not .Date.IsZero }} time{{ .Date | time.Format :date_medium }}/time {{ end }}3. 配置回退避免零值与其在模板中判断零值更推荐在配置中预设回退链例如让内容文件日期始终有值[frontmatter] date [date, :filename, :fileModTime]这样即使作者忘记在 front matter 写dateDate也会从文件名或文件修改时间取得有效值保证 RSS、sitemap、归档列表等依赖日期的输出始终可用。4. 时间值可用于任意time方法因为返回类型是time.Time可以直接调用 Go 时间 API{{ $age : now.Sub .Date }} {{ $years : div (int $age.Hours) 8760 }}now.Sub返回time.Duration可继续做算术与格式化。与相邻日期方法的关系Date与页面的另外三个日期方法共同构成完整的时间体系均定义于 page__meta.go方法读取字段典型语义DateDates.Date创建/发布时间PublishDateDates.PublishDate发布时间未来时间可用于预发布LastmodDates.Lastmod最后修改时间ExpiryDateDates.ExpiryDate过期时间过期后页面不再发布四个方法都返回time.Time各自的取值优先级均可通过[frontmatter]配置独立定制例如让lastmod优先使用 Git 提交时间[frontmatter] lastmod [:git, lastmod, :fileModTime, date]小结Page.Date是 Hugo 模板中最常用的时间入口它在 front matter 中声明、以time.Time返回并通过time.Format完成格式化与多语言本地化。从源码看它最终读取pageConfig.Dates.Date解析过程由frontmatterHandler.HandleDates统一驱动且支持通过[frontmatter]配置为date、:filename、:fileModTime、:git等多级回退链。测试用例dates_test.go、page_test.go分别验证了多语言日期本地化、时区解析与文件名/文件时间回退行为。掌握Date及其配置即可正确处理站点中日期的排序、归档、RSS 与多语言展示问题。延伸阅读front matter 日期配置说明本文关联文档page__meta.goDate/PublishDate/Lastmod/ExpiryDate的实现dates_test.go多语言与时区解析测试page_test.gofront matter 日期配置回退测试alldecoders.gofrontmatter配置解码入口【免费下载链接】hugoThe world’s fastest framework for building websites.项目地址: https://gitcode.com/gh_mirrors/hu/hugo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Hugo 页面日期（Page.Date）：front matter 日期解析、`time.Format` 本地化与源码实现解析
Hugo 页面日期Page.Datefront matter 日期解析、time.Format本地化与源码实现解析【免费下载链接】hugoThe world’s fastest framework for building websites.项目地址: https://gitcode.com/gh_mirrors/hu/hugo导读本文围绕 Hugo 页面方法Date展开讲解它如何返回页面在 front matter 中声明的日期、为什么该返回值是time.Time类型以及如何通过time.Format进行格式化与本地化输出。同时结合当前 Hugo 仓库源码page__meta.go与测试用例dates_test.go、page_test.go深入说明Date的底层取值逻辑、front matter 日期配置项[frontmatter]的优先级机制与真实使用场景。读完本文你将能在自己的 Hugo 站点中正确设置、回退、格式化并多语言本地化页面日期。方法签名与返回值类型Date是 Hugo 页面对象Page上的一个方法其完整签名为项目值方法名Date返回类型time.TimeGo 标准库时间类型签名PAGE.Date在 Hugo 官方文档中该方法对应的元信息为returnType: time.Time、signatures: [PAGE.Date]见 docs/content/en/methods/page/Date.md 头部 front matter。正因为返回的是 Go 的time.Time值模板中可以对它做三类操作直接用time.Format函数格式化为字符串传给time相关的任意方法使用如比较、计算时间差传给 Hugo 内置的任意time函数族处理time.Now、time.AsTime等或配合dateFormat等旧式函数。在 front matter 中设置日期Date方法最常见的取值来源是页面 front matter 中的date字段。以下是一个标准的 TOML front matter 示例该示例来自 Date.mdtitle Article 1 date 2023-10-19T00:40:04-07:00注意这里使用了带时区偏移的 RFC 3339 时间格式2023-10-19T00:40:04-07:00。时区偏移-07:00会保留在time.Time值中直接影响time.Format的本地化输出。日期字段在 YAML、TOML、JSON 等 front matter 格式中均可设置Hugo 统一将它们解析为time.Time--- title: Article 1 date: 2023-10-19T00:40:04-07:00 ---在模板中使用{{ .Date | time.Format :date_medium }} → Oct 19, 2023time.Format支持 Go 布局字符串如2006-01-02以及 Hugo 预定义的快捷格式如:date_medium后者还会遵循站点的language配置自动本地化。[!NOTE]date字段在 front matter 中通常被视为“创建日期”但你可以通过站点配置改变它的含义及其对站点行为如排序、RSS、sitemap 等的影响。详细说明见本文“日期解析顺序配置”一节及 config/allconfig/alldecoders.go 中的frontmatter解码实现。源码视角Date的底层实现从源码看Date方法最终读取的是页面配置中的Dates.Date字段// hugolib/page__meta.go func (m *pageMeta) Date() time.Time { return m.pageConfig.Dates.Date }与之并列的还有PublishDate、ExpiryDate、Lastmod三个日期方法它们分别读取Dates结构体中的PublishDate、ExpiryDate、Lastmod字段见 page__meta.go。这说明 Hugo 将页面相关的多个日期统一放在Dates结构中Date只是其中第一个维度。真正的日期解析发生在构建阶段Hugo 在setMetaPostParams中构造一个pagemeta.FrontMatterDescriptor其中包含页面配置、基础文件名、文件修改时间ModTime、Git 提交作者时间GitAuthorDate、站点语言时区Location与页面路径/标题然后调用frontmatterHandler.HandleDates完成日期赋值见 page__meta.go。从这段实现可以推断Date的取值不限于 front matter 的date字段还可能与文件名、文件修改时间、Git 时间相关具体由配置决定Location站点语言时区被传入解析器因此同一时间戳在不同语言/时区站点下会按各自时区解释原始日期值会被保存一份datesOriginal以便增量重建时重复聚合计算见 page__meta.go。日期解析顺序配置front matter 回退机制如果 front matter 中没有定义dateHugo 默认会使用文件系统的创建/修改时间等作为回退。这一行为可通过站点配置的[frontmatter]段完全定制。配置项语法为数组按优先级从高到低排列Hugo 会依次尝试直到取到有效值# hugo.toml [frontmatter] date [date, :filename, :fileModTime] lastmod [:git, lastmod, date] publishDate [publishDate, date] expiryDate [expiryDate]支持的取值包括取值含义date/publishDate/lastmod/expiryDate读取 front matter 中对应字段名:filename从内容文件名解析日期如2012-02-21-noslug.md会解析出2012-02-21:fileModTime使用文件的修改时间:git使用 Git 提交作者时间:lastmod使用 front matter 的lastmod字段:default使用 Hugo 内置默认值该配置在站点加载阶段通过pagemeta.DecodeFrontMatterConfig解码见 config/allconfig/alldecoders.go。测试验证:filename与:fileModTime回退仓库中的 page_test.go 通过TestPageWithFrontMatterConfig验证了回退逻辑。测试对每个日期处理器依次运行配置为[frontmatter] date [:filename, date]并创建内容文件content/section/2012-02-21-noslug.md与content/section/2012-02-22-slug.md二者 front matter 中均无date字段仅含lastMod。测试断言使用:filename时noSlug.Date().Year()等于2012说明 Hugo 成功从文件名解析出了日期若 front matter 中存在date则date字段优先级高于:filename配置数组中date位于:filename之后作为回退项Lastmod仍取 front matter 中的lastMod: 2018-02-28与Date走不同的配置链。这组测试同时印证了Date与Lastmod是相互独立的取值逻辑分别受frontmatter.date与frontmatter.lastmod配置控制。时区、多语言与本地化输出Date返回的time.Time携带时区信息time.Format在渲染时会结合站点的语言与时区设置进行本地化。仓库中的 dates_test.go 提供了两个典型验证场景多语言本地化TestDateFormatMultilingual见 dates_test.go站点配置defaultContentLanguage en且defaultContentLanguageInSubDir true同一页面date: 2021-07-18在英文与挪威语nn两个语言下分别渲染为Date: July 18, 2021 # en Date: 18. juli 2021 # nn这证明time.Format :date_long会依据当前语言自动选择日期显示习惯无需手写多套模板。时区解析TestTimeZones见 dates_test.go测试覆盖 YAML 与 TOML 两种 front matter 格式并同时声明date、lastMod、publishDate、expiryDate四个字段验证带/不带时间的日期字符串如2024-07-18与2024-07-18 15:28:01均能被正确解析为time.Time。实际站点中的典型用法article time datetime{{ .Date.Format 2006-01-02T15:04:05Z07:00 }} {{ .Date | time.Format :date_full }} /time /articledatetime属性使用机器可读的 ISO 8601 格式利于 SEO 与无障碍可见文本使用:date_full之类的人类可读格式。常见使用模式与注意事项1. 按日期排序默认情况下Hugo 使用Date作为正则页面排序的主要依据之一{{ range .Site.RegularPages.ByDate }} li{{ .Title }} — {{ .Date | time.Format 2006-01-02 }}/li {{ end }}2. 判断日期是否已设置front matter 未提供任何有效日期来源时Date返回零值时间。可用IsZero判断{{ if not .Date.IsZero }} time{{ .Date | time.Format :date_medium }}/time {{ end }}3. 配置回退避免零值与其在模板中判断零值更推荐在配置中预设回退链例如让内容文件日期始终有值[frontmatter] date [date, :filename, :fileModTime]这样即使作者忘记在 front matter 写dateDate也会从文件名或文件修改时间取得有效值保证 RSS、sitemap、归档列表等依赖日期的输出始终可用。4. 时间值可用于任意time方法因为返回类型是time.Time可以直接调用 Go 时间 API{{ $age : now.Sub .Date }} {{ $years : div (int $age.Hours) 8760 }}now.Sub返回time.Duration可继续做算术与格式化。与相邻日期方法的关系Date与页面的另外三个日期方法共同构成完整的时间体系均定义于 page__meta.go方法读取字段典型语义DateDates.Date创建/发布时间PublishDateDates.PublishDate发布时间未来时间可用于预发布LastmodDates.Lastmod最后修改时间ExpiryDateDates.ExpiryDate过期时间过期后页面不再发布四个方法都返回time.Time各自的取值优先级均可通过[frontmatter]配置独立定制例如让lastmod优先使用 Git 提交时间[frontmatter] lastmod [:git, lastmod, :fileModTime, date]小结Page.Date是 Hugo 模板中最常用的时间入口它在 front matter 中声明、以time.Time返回并通过time.Format完成格式化与多语言本地化。从源码看它最终读取pageConfig.Dates.Date解析过程由frontmatterHandler.HandleDates统一驱动且支持通过[frontmatter]配置为date、:filename、:fileModTime、:git等多级回退链。测试用例dates_test.go、page_test.go分别验证了多语言日期本地化、时区解析与文件名/文件时间回退行为。掌握Date及其配置即可正确处理站点中日期的排序、归档、RSS 与多语言展示问题。延伸阅读front matter 日期配置说明本文关联文档page__meta.goDate/PublishDate/Lastmod/ExpiryDate的实现dates_test.go多语言与时区解析测试page_test.gofront matter 日期配置回退测试alldecoders.gofrontmatter配置解码入口【免费下载链接】hugoThe world’s fastest framework for building websites.项目地址: https://gitcode.com/gh_mirrors/hu/hugo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考