Debian Codegraph @

resources/page/pagemeta/page_frontmatter.go

raw
1 // Copyright 2024 The Hugo Authors. All rights reserved.
2 //
3 // Licensed under the Apache License, Version 2.0 (the "License");
4 // you may not use this file except in compliance with the License.
5 // You may obtain a copy of the License at
6 // http://www.apache.org/licenses/LICENSE-2.0
7 //
8 // Unless required by applicable law or agreed to in writing, software
9 // distributed under the License is distributed on an "AS IS" BASIS,
10 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
11 // See the License for the specific language governing permissions and
12 // limitations under the License.
13
14 package pagemeta
15
16 import (
17 "errors"
18 "fmt"
19 "path"
20 "strings"
21 "time"
22
23 "github.com/gohugoio/hugo/common/hmaps"
24 "github.com/gohugoio/hugo/common/hreflect"
25 "github.com/gohugoio/hugo/common/hstrings"
26 "github.com/gohugoio/hugo/common/htime"
27 "github.com/gohugoio/hugo/common/hugio"
28 "github.com/gohugoio/hugo/common/loggers"
29 "github.com/gohugoio/hugo/common/paths"
30 "github.com/gohugoio/hugo/hugofs"
31 "github.com/gohugoio/hugo/hugofs/files"
32 "github.com/gohugoio/hugo/hugolib/sitesmatrix"
33 "github.com/gohugoio/hugo/markup"
34 "github.com/gohugoio/hugo/media"
35 "github.com/gohugoio/hugo/output"
36 "github.com/gohugoio/hugo/resources/kinds"
37 "github.com/gohugoio/hugo/resources/page"
38 "github.com/gohugoio/hugo/resources/resource"
39 "github.com/mitchellh/mapstructure"
40
41 "github.com/gohugoio/hugo/config"
42 "github.com/spf13/cast"
43 )
44
45 type DatesStrings struct {
46 Date string `json:"date"`
47 Lastmod string `json:"lastMod"`
48 PublishDate string `json:"publishDate"`
49 ExpiryDate string `json:"expiryDate"`
50 }
51
52 type Dates struct {
53 Date time.Time
54 Lastmod time.Time
55 PublishDate time.Time
56 ExpiryDate time.Time
57 }
58
59 func (d Dates) String() string {
60 fmtDate := func(t time.Time) string {
61 if t.IsZero() {
62 return "<zero>"
63 }
64 return t.Format(time.RFC3339)
65 }
66 return fmt.Sprintf("Date: %s, Lastmod: %s, PublishDate: %s, ExpiryDate: %s",
67 fmtDate(d.Date), fmtDate(d.Lastmod), fmtDate(d.PublishDate), fmtDate(d.ExpiryDate))
68 }
69
70 func (d Dates) IsDateOrLastModAfter(in Dates) bool {
71 return d.Date.After(in.Date) || d.Lastmod.After(in.Lastmod)
72 }
73
74 func (d *Dates) UpdateDateAndLastmodAndPublishDateIfAfter(in Dates) {
75 if in.Date.After(d.Date) {
76 d.Date = in.Date
77 }
78 if in.Lastmod.After(d.Lastmod) {
79 d.Lastmod = in.Lastmod
80 }
81
82 if in.PublishDate.After(d.PublishDate) && in.PublishDate.Before(htime.Now()) {
83 d.PublishDate = in.PublishDate
84 }
85 }
86
87 func (d Dates) IsAllDatesZero() bool {
88 return d.Date.IsZero() && d.Lastmod.IsZero() && d.PublishDate.IsZero() && d.ExpiryDate.IsZero()
89 }
90
91 const (
92 pageMetaKeySites = "sites"
93 pageMetaKeyMarkup = "markup"
94 )
95
96 func (pcfg *PageConfigEarly) SetMetaPreFromMap(ext string, frontmatter map[string]any, logger loggers.Logger, conf config.AllProvider) error {
97 if frontmatter != nil {
98 if err := pcfg.setFromFrontMatter(frontmatter); err != nil {
99 return err
100 }
101 }
102 return pcfg.resolveContentType(ext, conf.GetConfigSection("mediaTypes").(media.Types))
103 }
104
105 func (pcfg *PageConfigEarly) setFromFrontMatter(frontmatter map[string]any) error {
106 // Needed for case insensitive fetching of params values.
107 hmaps.PrepareParams(frontmatter)
108 pcfg.Frontmatter = frontmatter
109
110 if v, found := frontmatter[pageMetaKeyMarkup]; found {
111 pcfg.Content.Markup = cast.ToString(v)
112 }
113
114 if v, found := frontmatter[pageMetaKeySites]; found {
115 if err := mapstructure.WeakDecode(v, &pcfg.Sites); err != nil {
116 return fmt.Errorf("failed to decode sites from front matter: %w", err)
117 }
118 }
119 return nil
120 }
121
122 func (p *PageConfigEarly) setCascadeEarlyValueIfNotSet(key string, value any) (done bool) {
123 switch key {
124 case pageMetaKeySites:
125 p.Sites.SetFromParamsIfNotSet(value.(hmaps.Params))
126 }
127
128 return !p.Sites.Matrix.IsZero()
129 }
130
131 // Page config that needs to be set early.
132 type PageConfigEarly struct {
133 Kind string // The kind of page, e.g. "page", "section", "home" etc. This is usually derived from the content path.
134 Path string // The canonical path to the page, e.g. /sect/mypage. Note: Leading slash, no trailing slash, no extensions or language identifiers.
135 SourceEntryHash uint64 // The source entry hash for content adapters.
136
137 Sites sitesmatrix.Sites
138 Content Source // Content holds the content for this page.
139
140 Frontmatter hmaps.Params `mapstructure:"-" json:"-"` // The original front matter or content adapter map.
141
142 // Compiled values.
143 SitesMatrixAndComplements `mapstructure:"-" json:"-"`
144 IsFromContentAdapter bool `mapstructure:"-" json:"-"`
145 ContentMediaType media.Type `mapstructure:"-" json:"-"`
146 }
147
148 // PageConfig configures a Page, typically from front matter.
149 // Note that all the top level fields are reserved Hugo keywords.
150 // Any custom configuration needs to be set in the Params map.
151 type PageConfigLate struct {
152 Dates Dates `json:"-"` // Dates holds the four core dates for this page.
153 DatesStrings
154 Params hmaps.Params // User defined params.
155
156 Title string // The title of the page.
157 LinkTitle string // The link title of the page.
158 Type string // The content type of the page.
159 Layout string // The layout to use for to render this page.
160 Weight int // The weight of the page, used in sorting if set to a non-zero value.
161 URL string // The URL to the rendered page, e.g. /sect/mypage.html.
162 Slug string // The slug for this page.
163 Description string // The description for this page.
164 Summary string // The summary for this page.
165 Draft bool // Whether or not the content is a draft.
166 Headless bool `json:"-"` // Whether or not the page should be rendered.
167 IsCJKLanguage bool // Whether or not the content is in a CJK language.
168 TranslationKey string // The translation key for this page.
169 Keywords []string // The keywords for this page.
170 Aliases []string // The aliases for this page.
171 Outputs []string // The output formats to render this page in. If not set, the site's configured output formats for this page kind will be used.
172
173 FrontMatterOnlyValues `mapstructure:"-" json:"-"`
174
175 Sitemap config.SitemapConfig
176 Build BuildConfig
177 Menus any // Can be a string, []string or map[string]any.
178
179 // Set only for pages created from data files.
180 ContentAdapterData map[string]any `mapstructure:"-" json:"-"`
181
182 // Compiled values.
183 ConfiguredOutputFormats output.Formats `mapstructure:"-" json:"-"`
184 }
185
186 // SitesMatrixAndComplements holds a sites matrix and a sites complements configuration.
187 type SitesMatrixAndComplements struct {
188 SitesMatrix sitesmatrix.VectorStore `mapstructure:"-" json:"-"`
189 SitesComplements sitesmatrix.VectorStore `mapstructure:"-" json:"-"`
190 }
191
192 // MatchSiteVector checks whether the site vector matches the sites matrix.
193 func (p *SitesMatrixAndComplements) MatchSiteVector(siteVector sitesmatrix.Vector) bool {
194 return p.SitesMatrix.HasAnyVector(siteVector)
195 }
196
197 // MatchLanguageCoarse checks whether the language dimension matches either
198 // the sites matrix or the sites complements.
199 func (p *SitesMatrixAndComplements) MatchLanguageCoarse(siteVector sitesmatrix.Vector) bool {
200 i := siteVector.Language()
201 return p.SitesMatrix.HasLanguage(i) || p.SitesComplements.HasLanguage(i)
202 }
203
204 // MatchRoleCoarse checks whether the role dimension matches either
205 // the sites matrix or the sites complements.
206 func (p *SitesMatrixAndComplements) MatchRoleCoarse(siteVector sitesmatrix.Vector) bool {
207 i := siteVector.Role()
208 return p.SitesMatrix.HasRole(i) || p.SitesComplements.HasRole(i)
209 }
210
211 // MatchVersionCoarse checks whether the version dimension matches either
212 // the sites matrix or the sites complements.
213 func (p *SitesMatrixAndComplements) MatchVersionCoarse(siteVector sitesmatrix.Vector) bool {
214 i := siteVector.Version()
215 return p.SitesMatrix.HasVersion(i) || p.SitesComplements.HasVersion(i)
216 }
217
218 func (p *SitesMatrixAndComplements) MatchSiteVectorCoarse(siteVector sitesmatrix.Vector) bool {
219 return p.MatchLanguageCoarse(siteVector) && p.MatchSiteVectorCoarseExcludeLanguage(siteVector)
220 }
221
222 func (p *SitesMatrixAndComplements) MatchSiteVectorCoarseExcludeLanguage(siteVector sitesmatrix.Vector) bool {
223 return p.MatchRoleCoarse(siteVector) && p.MatchVersionCoarse(siteVector)
224 }
225
226 func DefaultPageConfig() *PageConfigLate {
227 return &PageConfigLate{
228 Build: DefaultBuildConfig,
229 }
230 }
231
232 func (p *PageConfigEarly) Init(pagesFromData bool) error {
233 if pagesFromData {
234 p.Path = strings.TrimPrefix(p.Path, "/")
235
236 if p.Path == "" && p.Kind != kinds.KindHome {
237 return fmt.Errorf("empty path is reserved for the home page")
238 }
239
240 if p.Content.Markup != "" {
241 return errors.New("markup must not be set, use mediaType")
242 }
243 }
244
245 return nil
246 }
247
248 func (p *PageConfigLate) Init() error {
249 return nil
250 }
251
252 func buildSitesComplementsFromSitesConfig(
253 conf config.AllProvider,
254 fim *hugofs.FileMeta,
255 sitesConfig sitesmatrix.Sites,
256 ) sitesmatrix.VectorStore {
257 if sitesConfig.Complements.IsZero() {
258 if fim != nil && fim.SitesComplements != nil {
259 return fim.SitesComplements
260 }
261 return sitesmatrix.NilStore
262 }
263 intsetsCfg := sitesmatrix.IntSetsConfig{
264 Globs: sitesConfig.Complements,
265 }
266
267 sitesComplements := sitesmatrix.NewIntSetsBuilder(conf.ConfiguredDimensions()).WithConfig(intsetsCfg)
268
269 if fim != nil && fim.SitesComplements != nil {
270 sitesComplements.WithDimensionsFromOtherIfNotSet(fim.SitesComplements)
271 }
272
273 return sitesComplements.Build()
274 }
275
276 func buildSitesMatrixFromSitesConfig(
277 conf config.AllProvider,
278 sitesMatrixBase sitesmatrix.VectorIterator,
279 sitesConfig sitesmatrix.Sites,
280 ) sitesmatrix.VectorStore {
281 if sitesConfig.Matrix.IsZero() && sitesMatrixBase != nil {
282 if sitesMatrixBase.LenVectors() == 1 {
283 return conf.ConfiguredDimensions().GetOrCreateSingleVectorStore(sitesMatrixBase.VectorSample())
284 }
285 return sitesmatrix.VectorIteratorToStore(sitesMatrixBase)
286 }
287
288 if conf.ConfiguredDimensions().IsSingleVector() {
289 return conf.ConfiguredDimensions().CommonSitesMatrix.DefaultSite
290 }
291
292 intsetsCfg := sitesmatrix.IntSetsConfig{
293 Globs: sitesConfig.Matrix,
294 }
295 sitesMatrixPage := sitesmatrix.NewIntSetsBuilder(conf.ConfiguredDimensions()).WithConfig(intsetsCfg)
296
297 if sitesMatrixBase != nil {
298 sitesMatrixPage.WithDimensionsFromOtherIfNotSet(sitesMatrixBase)
299 }
300 sitesMatrixPage.WithDefaultsIfNotSet()
301
302 matrix := sitesMatrixPage.Build()
303
304 return matrix
305 }
306
307 func (p *PageConfigEarly) CompileEarly(pi *paths.Path, cascades *page.PageMatcherParamsConfigs,
308 conf config.AllProvider, fim *hugofs.FileMeta, sitesMatrixBase sitesmatrix.VectorIterator, sitesMatrixBaseOnly bool,
309 ) error {
310 // First apply the cascades with no site filtering.
311 for cascade := range cascades.All() {
312 if cascade.Target.SitesMatrixCompiled != nil {
313 continue
314 }
315
316 if !cascade.Target.Match(p.Kind, pi.Base(), conf.Environment(), p.SitesMatrix) {
317 continue
318 }
319
320 for ck, cv := range cascade.Fields {
321 if done := p.setCascadeEarlyValueIfNotSet(ck, cv); done {
322 break
323 }
324 }
325
326 }
327
328 if sitesMatrixBaseOnly {
329 p.SitesMatrix = sitesmatrix.VectorIteratorToStore(sitesMatrixBase)
330 } else {
331 p.SitesMatrix = buildSitesMatrixFromSitesConfig(
332 conf,
333 sitesMatrixBase,
334 p.Sites,
335 )
336 }
337
338 // Finally apply the cascades with site filtering.
339 // These may also contain site specific settings,
340 // so preserve the original matrix for comparison.
341 sitesMatrixBefore := p.Sites.Matrix
342 var hadCascadeMatch bool
343
344 for cascade := range cascades.All() {
345 if cascade.Target.SitesMatrixCompiled == nil {
346 continue
347 }
348
349 if !cascade.Target.Match(p.Kind, pi.Base(), conf.Environment(), p.SitesMatrix) {
350 continue
351 }
352
353 hadCascadeMatch = true
354
355 for ck, cv := range cascade.Fields {
356 if done := p.setCascadeEarlyValueIfNotSet(ck, cv); done {
357 break
358 }
359 }
360
361 }
362
363 if hadCascadeMatch && !sitesMatrixBaseOnly && !sitesMatrixBefore.Equal(p.Sites.Matrix) {
364 // Matrix has changed, rebuild.
365 p.SitesMatrix = buildSitesMatrixFromSitesConfig(
366 conf,
367 sitesMatrixBase,
368 p.Sites,
369 )
370 }
371
372 p.SitesComplements = buildSitesComplementsFromSitesConfig(
373 conf,
374 fim,
375 p.Sites,
376 )
377
378 mediaTypes := conf.GetConfigSection("mediaTypes").(media.Types)
379 if err := p.resolveContentType(pi.Ext(), mediaTypes); err != nil {
380 return err
381 }
382
383 return nil
384 }
385
386 func (p *PageConfigEarly) CompileForPagesFromDataPre(basePath string, logger loggers.Logger, mediaTypes media.Types) error {
387 // In content adapters, we always get relative paths.
388 if basePath != "" {
389 p.Path = path.Join(basePath, p.Path)
390 }
391
392 if p.Kind == "" {
393 p.Kind = kinds.KindPage
394 }
395
396 // Note that NormalizePathStringBasic will make sure that we don't preserve the unnormalized path.
397 // We do that when we create pages from the file system; mostly for backward compatibility,
398 // but also because people tend to use use the filename to name their resources (with spaces and all),
399 // and this isn't relevant when creating resources from an API where it's easy to add textual meta data.
400 p.Path = paths.NormalizePathStringBasic(p.Path)
401
402 return p.resolveContentType("", mediaTypes)
403 }
404
405 func (p *PageConfigEarly) resolveContentType(ext string, mediaTypes media.Types) error {
406 if p.Content.Markup == "" && p.Content.MediaType == "" {
407 if ext == "" {
408 ext = "md"
409 }
410 p.ContentMediaType = MarkupToMediaType(ext, mediaTypes)
411 if p.ContentMediaType.IsZero() {
412 return fmt.Errorf("failed to resolve media type for suffix %q", ext)
413 }
414 }
415
416 var s string
417 if p.ContentMediaType.IsZero() {
418 if p.Content.MediaType != "" {
419 s = p.Content.MediaType
420 p.ContentMediaType, _ = mediaTypes.GetByType(s)
421 }
422
423 if p.ContentMediaType.IsZero() && p.Content.Markup != "" {
424 s = p.Content.Markup
425 p.ContentMediaType = MarkupToMediaType(s, mediaTypes)
426 }
427 }
428
429 if p.ContentMediaType.IsZero() {
430 return fmt.Errorf("failed to resolve media type for %q", s)
431 }
432
433 if p.Content.Markup == "" {
434 p.Content.Markup = p.ContentMediaType.SubType
435 }
436 return nil
437 }
438
439 // Compile sets up the page configuration after all fields have been set.
440 func (p *PageConfigLate) Compile(e *PageConfigEarly, logger loggers.Logger, outputFormats output.Formats) error {
441 if e.IsFromContentAdapter {
442 if err := mapstructure.WeakDecode(p.ContentAdapterData, p); err != nil {
443 err = fmt.Errorf("failed to decode page map: %w", err)
444 return err
445 }
446 }
447
448 if p.Params == nil {
449 p.Params = make(hmaps.Params)
450 } else {
451 hmaps.PrepareParams(p.Params)
452 }
453
454 if len(p.Outputs) > 0 {
455 outFormats, err := outputFormats.GetByNames(p.Outputs...)
456 if err != nil {
457 return fmt.Errorf("failed to resolve output formats %v: %w", p.Outputs, err)
458 } else {
459 p.ConfiguredOutputFormats = outFormats
460 }
461 }
462
463 return nil
464 }
465
466 // MarkupToMediaType converts a markup string to a media type.
467 func MarkupToMediaType(s string, mediaTypes media.Types) media.Type {
468 s = strings.ToLower(s)
469 mt, _ := mediaTypes.GetBestMatch(markup.ResolveMarkup(s))
470 return mt
471 }
472
473 type ResourceConfig struct {
474 Path string
475 Name string
476 Title string
477 Params hmaps.Params
478 Content Source
479 Sites sitesmatrix.Sites
480
481 // Compiled values.
482 ContentAdapterSourceEntryHash uint64 `mapstructure:"-" json:"-"`
483 PathInfo *paths.Path `mapstructure:"-" json:"-"`
484 ContentMediaType media.Type `mapstructure:"-" json:"-"`
485 SitesMatrixAndComplements `mapstructure:"-" json:"-"`
486 }
487
488 func (rc *ResourceConfig) Validate() error {
489 if rc.Content.Markup != "" {
490 return errors.New("markup must not be set, use mediaType")
491 }
492 return nil
493 }
494
495 func (rc *ResourceConfig) Compile(basePath string, fim hugofs.FileMetaInfo, conf config.AllProvider, mediaTypes media.Types) error {
496 if rc.Params != nil {
497 hmaps.PrepareParams(rc.Params)
498 }
499
500 // Note that NormalizePathStringBasic will make sure that we don't preserve the unnormalized path.
501 // We do that when we create resources from the file system; mostly for backward compatibility,
502 // but also because people tend to use use the filename to name their resources (with spaces and all),
503 // and this isn't relevant when creating resources from an API where it's easy to add textual meta data.
504 rc.Path = paths.NormalizePathStringBasic(path.Join(basePath, rc.Path))
505 rc.PathInfo = conf.PathParser().Parse(files.ComponentFolderContent, rc.Path)
506 if rc.Content.MediaType != "" {
507 var found bool
508 rc.ContentMediaType, found = mediaTypes.GetByType(rc.Content.MediaType)
509 if !found {
510 return fmt.Errorf("media type %q not found", rc.Content.MediaType)
511 }
512 }
513
514 var sitesMatrixFile sitesmatrix.VectorStore
515 if fim != nil {
516 sitesMatrixFile = fim.Meta().SitesMatrix
517 }
518
519 rc.SitesMatrix = buildSitesMatrixFromSitesConfig(
520 conf,
521 sitesMatrixFile,
522 rc.Sites,
523 )
524
525 rc.SitesComplements = buildSitesComplementsFromSitesConfig(
526 conf,
527 fim.Meta(),
528 rc.Sites,
529 )
530
531 return nil
532 }
533
534 type Source struct {
535 // MediaType is the media type of the content.
536 MediaType string
537
538 // The markup used in Value. Only used in front matter.
539 Markup string
540
541 // The content.
542 Value any
543 }
544
545 func (s Source) IsZero() bool {
546 return !hreflect.IsTruthful(s.Value)
547 }
548
549 func (s Source) IsResourceValue() bool {
550 _, ok := s.Value.(resource.Resource)
551 return ok
552 }
553
554 func (s Source) ValueAsString() string {
555 if s.Value == nil {
556 return ""
557 }
558 ss, err := cast.ToStringE(s.Value)
559 if err != nil {
560 panic(fmt.Errorf("content source: failed to convert %T to string: %s", s.Value, err))
561 }
562 return ss
563 }
564
565 func (s Source) ValueAsOpenReadSeekCloser() hugio.OpenReadSeekCloser {
566 content := s.ValueAsString()
567 return func() (hugio.ReadSeekCloser, error) {
568 return hugio.NewReadSeekerNoOpCloserFromString(content), nil
569 }
570 }
571
572 // FrontMatterOnlyValues holds values that can only be set via front matter.
573 type FrontMatterOnlyValues struct {
574 ResourcesMeta []map[string]any
575 }
576
577 // FrontMatterHandler maps front matter into Page fields and .Params.
578 // Note that we currently have only extracted the date logic.
579 type FrontMatterHandler struct {
580 fmConfig FrontmatterConfig
581
582 contentAdapterDatesHandler func(d *FrontMatterDescriptor) error
583
584 dateHandler frontMatterFieldHandler
585 lastModHandler frontMatterFieldHandler
586 publishDateHandler frontMatterFieldHandler
587 expiryDateHandler frontMatterFieldHandler
588
589 // A map of all date keys configured, including any custom.
590 allDateKeys map[string]bool
591
592 logger loggers.Logger
593 }
594
595 // FrontMatterDescriptor describes how to handle front matter for a given Page.
596 // It has pointers to values in the receiving page which gets updated.
597 type FrontMatterDescriptor struct {
598 // This is the Page's base filename (BaseFilename), e.g. page.md., or
599 // if page is a leaf bundle, the bundle folder name (ContentBaseName).
600 BaseFilename string
601
602 // The Page's path if the page is backed by a file, else its title.
603 PathOrTitle string
604
605 // The content file's mod time.
606 ModTime time.Time
607
608 // May be set from the author date in Git.
609 GitAuthorDate time.Time
610
611 PageConfigEarly *PageConfigEarly
612
613 // The below will be modified.
614 PageConfigLate *PageConfigLate
615 Location *time.Location // The Location to use to parse dates without time zone info.
616 }
617
618 var dateFieldAliases = map[string][]string{
619 fmDate: {},
620 fmLastmod: {"modified"},
621 fmPubDate: {"pubdate", "published"},
622 fmExpiryDate: {"unpublishdate"},
623 }
624
625 // HandleDates updates all the dates given the current configuration and the
626 // supplied front matter params. Note that this requires all lower-case keys
627 // in the params map.
628 func (f FrontMatterHandler) HandleDates(d *FrontMatterDescriptor) error {
629 if d.PageConfigLate == nil {
630 panic("missing pageConfig")
631 }
632
633 if d.PageConfigEarly.IsFromContentAdapter {
634 if f.contentAdapterDatesHandler == nil {
635 panic("missing content adapter date handler")
636 }
637 return f.contentAdapterDatesHandler(d)
638 }
639
640 if f.dateHandler == nil {
641 panic("missing date handler")
642 }
643
644 if _, err := f.dateHandler(d); err != nil {
645 return err
646 }
647
648 if _, err := f.lastModHandler(d); err != nil {
649 return err
650 }
651
652 if _, err := f.publishDateHandler(d); err != nil {
653 return err
654 }
655
656 if _, err := f.expiryDateHandler(d); err != nil {
657 return err
658 }
659
660 return nil
661 }
662
663 // IsDateKey returns whether the given front matter key is considered a date by the current
664 // configuration.
665 func (f FrontMatterHandler) IsDateKey(key string) bool {
666 return f.allDateKeys[key]
667 }
668
669 // dateAndSlugFromBaseFilename returns a time.Time value (resolved to the
670 // default system location) and a slug, extracted by parsing the provided path.
671 // Parsing supports YYYY-MM-DD-HH-MM-SS and YYYY-MM-DD date/time formats.
672 // Within the YYYY-MM-DD-HH-MM-SS format, the date and time values may be
673 // separated by any character including a space (e.g., YYYY-MM-DD HH-MM-SS).
674 func dateAndSlugFromBaseFilename(location *time.Location, path string) (time.Time, string) {
675 base, _ := paths.FileAndExt(path)
676
677 if len(base) < 10 {
678 // Not long enough to start with a YYYY-MM-DD date.
679 return time.Time{}, ""
680 }
681
682 // Delimiters allowed between the date and the slug.
683 delimiters := " -_"
684
685 if len(base) >= 19 {
686 // Attempt to parse a YYYY-MM-DD-HH-MM-SS date-time prefix.
687 ds := base[:10]
688 ts := strings.ReplaceAll(base[11:19], "-", ":")
689
690 d, err := htime.ToTimeInDefaultLocationE(ds+"T"+ts, location)
691 if err == nil {
692 return d, strings.Trim(base[19:], delimiters)
693 }
694 }
695
696 // Attempt to parse a YYYY-MM-DD date prefix.
697 ds := base[:10]
698
699 d, err := htime.ToTimeInDefaultLocationE(ds, location)
700 if err == nil {
701 return d, strings.Trim(base[10:], delimiters)
702 }
703
704 // If no date is defined, return the zero time instant.
705 return time.Time{}, ""
706 }
707
708 type frontMatterFieldHandler func(d *FrontMatterDescriptor) (bool, error)
709
710 func (f FrontMatterHandler) newChainedFrontMatterFieldHandler(handlers ...frontMatterFieldHandler) frontMatterFieldHandler {
711 return func(d *FrontMatterDescriptor) (bool, error) {
712 for _, h := range handlers {
713 // First successful handler wins.
714 success, err := h(d)
715 if err != nil {
716 f.logger.Errorln(err)
717 } else if success {
718 return true, nil
719 }
720 }
721 return false, nil
722 }
723 }
724
725 type FrontmatterConfig struct {
726 // Controls how the Date is set from front matter.
727 Date []string
728 // Controls how the Lastmod is set from front matter.
729 Lastmod []string
730 // Controls how the PublishDate is set from front matter.
731 PublishDate []string
732 // Controls how the ExpiryDate is set from front matter.
733 ExpiryDate []string
734 }
735
736 const (
737 // These are all the date handler identifiers
738 // All identifiers not starting with a ":" maps to a front matter parameter.
739 fmDate = "date"
740 fmPubDate = "publishdate"
741 fmLastmod = "lastmod"
742 fmExpiryDate = "expirydate"
743
744 // Gets date from filename, e.g 218-02-22-mypage.md
745 fmFilename = ":filename"
746
747 // Gets date from file OS mod time.
748 fmModTime = ":filemodtime"
749
750 // Gets date from Git
751 fmGitAuthorDate = ":git"
752 )
753
754 // This is the config you get when doing nothing.
755 func newDefaultFrontmatterConfig() FrontmatterConfig {
756 return FrontmatterConfig{
757 Date: []string{fmDate, fmPubDate, fmLastmod},
758 Lastmod: []string{fmGitAuthorDate, fmLastmod, fmDate, fmPubDate},
759 PublishDate: []string{fmPubDate, fmDate},
760 ExpiryDate: []string{fmExpiryDate},
761 }
762 }
763
764 func DecodeFrontMatterConfig(cfg config.Provider) (FrontmatterConfig, error) {
765 c := newDefaultFrontmatterConfig()
766 defaultConfig := c
767
768 if cfg.IsSet("frontmatter") {
769 fm := cfg.GetStringMap("frontmatter")
770 for k, v := range fm {
771 loki := strings.ToLower(k)
772 switch loki {
773 case fmDate:
774 c.Date = toLowerSlice(v)
775 case fmPubDate:
776 c.PublishDate = toLowerSlice(v)
777 case fmLastmod:
778 c.Lastmod = toLowerSlice(v)
779 case fmExpiryDate:
780 c.ExpiryDate = toLowerSlice(v)
781 }
782 }
783 }
784
785 expander := func(c, d []string) []string {
786 out := expandDefaultValues(c, d)
787 out = addDateFieldAliases(out)
788 return out
789 }
790
791 c.Date = expander(c.Date, defaultConfig.Date)
792 c.PublishDate = expander(c.PublishDate, defaultConfig.PublishDate)
793 c.Lastmod = expander(c.Lastmod, defaultConfig.Lastmod)
794 c.ExpiryDate = expander(c.ExpiryDate, defaultConfig.ExpiryDate)
795
796 return c, nil
797 }
798
799 func addDateFieldAliases(values []string) []string {
800 var complete []string
801
802 for _, v := range values {
803 complete = append(complete, v)
804 if aliases, found := dateFieldAliases[v]; found {
805 complete = append(complete, aliases...)
806 }
807 }
808 return hstrings.UniqueStringsReuse(complete)
809 }
810
811 func expandDefaultValues(values []string, defaults []string) []string {
812 var out []string
813 for _, v := range values {
814 if v == ":default" {
815 out = append(out, defaults...)
816 } else {
817 out = append(out, v)
818 }
819 }
820 return out
821 }
822
823 func toLowerSlice(in any) []string {
824 out := cast.ToStringSlice(in)
825 for i := range out {
826 out[i] = strings.ToLower(out[i])
827 }
828
829 return out
830 }
831
832 // NewFrontmatterHandler creates a new FrontMatterHandler with the given logger and configuration.
833 // If no logger is provided, one will be created.
834 func NewFrontmatterHandler(logger loggers.Logger, frontMatterConfig FrontmatterConfig) (FrontMatterHandler, error) {
835 if logger == nil {
836 logger = loggers.NewDefault()
837 }
838
839 allDateKeys := make(map[string]bool)
840 addKeys := func(vals []string) {
841 for _, k := range vals {
842 if !strings.HasPrefix(k, ":") {
843 allDateKeys[k] = true
844 }
845 }
846 }
847
848 addKeys(frontMatterConfig.Date)
849 addKeys(frontMatterConfig.ExpiryDate)
850 addKeys(frontMatterConfig.Lastmod)
851 addKeys(frontMatterConfig.PublishDate)
852
853 f := FrontMatterHandler{logger: logger, fmConfig: frontMatterConfig, allDateKeys: allDateKeys}
854
855 if err := f.createHandlers(); err != nil {
856 return f, err
857 }
858
859 return f, nil
860 }
861
862 func (f *FrontMatterHandler) createHandlers() error {
863 var err error
864
865 if f.contentAdapterDatesHandler, err = f.createContentAdapterDatesHandler(f.fmConfig); err != nil {
866 return err
867 }
868
869 if f.dateHandler, err = f.createDateHandler(f.fmConfig.Date,
870 func(d *FrontMatterDescriptor, t time.Time) {
871 d.PageConfigLate.Dates.Date = t
872 setParamIfNotSet(fmDate, t, d)
873 }); err != nil {
874 return err
875 }
876
877 if f.lastModHandler, err = f.createDateHandler(f.fmConfig.Lastmod,
878 func(d *FrontMatterDescriptor, t time.Time) {
879 setParamIfNotSet(fmLastmod, t, d)
880 d.PageConfigLate.Dates.Lastmod = t
881 }); err != nil {
882 return err
883 }
884
885 if f.publishDateHandler, err = f.createDateHandler(f.fmConfig.PublishDate,
886 func(d *FrontMatterDescriptor, t time.Time) {
887 setParamIfNotSet(fmPubDate, t, d)
888 d.PageConfigLate.Dates.PublishDate = t
889 }); err != nil {
890 return err
891 }
892
893 if f.expiryDateHandler, err = f.createDateHandler(f.fmConfig.ExpiryDate,
894 func(d *FrontMatterDescriptor, t time.Time) {
895 setParamIfNotSet(fmExpiryDate, t, d)
896 d.PageConfigLate.Dates.ExpiryDate = t
897 }); err != nil {
898 return err
899 }
900
901 return nil
902 }
903
904 func setParamIfNotSet(key string, value any, d *FrontMatterDescriptor) {
905 if _, found := d.PageConfigLate.Params[key]; found {
906 return
907 }
908 d.PageConfigLate.Params[key] = value
909 }
910
911 func (f FrontMatterHandler) createContentAdapterDatesHandler(fmcfg FrontmatterConfig) (func(d *FrontMatterDescriptor) error, error) {
912 setTime := func(key string, value time.Time, in *PageConfigLate) {
913 switch key {
914 case fmDate:
915 in.Dates.Date = value
916 case fmLastmod:
917 in.Dates.Lastmod = value
918 case fmPubDate:
919 in.Dates.PublishDate = value
920 case fmExpiryDate:
921 in.Dates.ExpiryDate = value
922 }
923 }
924
925 getTime := func(key string, in *PageConfigLate) time.Time {
926 switch key {
927 case fmDate:
928 return in.Dates.Date
929 case fmLastmod:
930 return in.Dates.Lastmod
931 case fmPubDate:
932 return in.Dates.PublishDate
933 case fmExpiryDate:
934 return in.Dates.ExpiryDate
935 }
936 return time.Time{}
937 }
938
939 createSetter := func(identifiers []string, date string) func(pcfg *PageConfigLate) {
940 var getTimes []func(in *PageConfigLate) time.Time
941 for _, identifier := range identifiers {
942 if strings.HasPrefix(identifier, ":") {
943 continue
944 }
945 switch identifier {
946 case fmDate:
947 getTimes = append(getTimes, func(in *PageConfigLate) time.Time {
948 return getTime(fmDate, in)
949 })
950 case fmLastmod:
951 getTimes = append(getTimes, func(in *PageConfigLate) time.Time {
952 return getTime(fmLastmod, in)
953 })
954 case fmPubDate:
955 getTimes = append(getTimes, func(in *PageConfigLate) time.Time {
956 return getTime(fmPubDate, in)
957 })
958 case fmExpiryDate:
959 getTimes = append(getTimes, func(in *PageConfigLate) time.Time {
960 return getTime(fmExpiryDate, in)
961 })
962 }
963 }
964
965 return func(pcfg *PageConfigLate) {
966 for _, get := range getTimes {
967 if t := get(pcfg); !t.IsZero() {
968 setTime(date, t, pcfg)
969 return
970 }
971 }
972 }
973 }
974
975 setDate := createSetter(fmcfg.Date, fmDate)
976 setLastmod := createSetter(fmcfg.Lastmod, fmLastmod)
977 setPublishDate := createSetter(fmcfg.PublishDate, fmPubDate)
978 setExpiryDate := createSetter(fmcfg.ExpiryDate, fmExpiryDate)
979
980 fn := func(d *FrontMatterDescriptor) error {
981 pcfg := d.PageConfigLate
982 setDate(pcfg)
983 setLastmod(pcfg)
984 setPublishDate(pcfg)
985 setExpiryDate(pcfg)
986 return nil
987 }
988 return fn, nil
989 }
990
991 func (f FrontMatterHandler) createDateHandler(identifiers []string, setter func(d *FrontMatterDescriptor, t time.Time)) (frontMatterFieldHandler, error) {
992 var h *frontmatterFieldHandlers
993 var handlers []frontMatterFieldHandler
994
995 for _, identifier := range identifiers {
996 switch identifier {
997 case fmFilename:
998 handlers = append(handlers, h.newDateFilenameHandler(setter))
999 case fmModTime:
1000 handlers = append(handlers, h.newDateModTimeHandler(setter))
1001 case fmGitAuthorDate:
1002 handlers = append(handlers, h.newDateGitAuthorDateHandler(setter))
1003 default:
1004 handlers = append(handlers, h.newDateFieldHandler(identifier, setter))
1005 }
1006 }
1007
1008 return f.newChainedFrontMatterFieldHandler(handlers...), nil
1009 }
1010
1011 type frontmatterFieldHandlers int
1012
1013 func (f *frontmatterFieldHandlers) newDateFieldHandler(key string, setter func(d *FrontMatterDescriptor, t time.Time)) frontMatterFieldHandler {
1014 return func(d *FrontMatterDescriptor) (bool, error) {
1015 v, found := d.PageConfigEarly.Frontmatter[key]
1016 if found {
1017 d.PageConfigLate.Params[key] = v
1018 } else {
1019 // Reentry from previous handlers.
1020 v, found = d.PageConfigLate.Params[key]
1021 }
1022
1023 if !found || v == "" || v == nil {
1024 return false, nil
1025 }
1026
1027 var date time.Time
1028 if vt, ok := v.(time.Time); ok && vt.Location() == d.Location {
1029 date = vt
1030 } else {
1031 var err error
1032 date, err = htime.ToTimeInDefaultLocationE(v, d.Location)
1033 if err != nil {
1034 return false, fmt.Errorf("the %q front matter field is not a parsable date: see %s", key, d.PathOrTitle)
1035 }
1036 d.PageConfigLate.Params[key] = date
1037 }
1038
1039 // We map several date keys to one, so, for example,
1040 // "expirydate", "unpublishdate" will all set .ExpiryDate (first found).
1041 setter(d, date)
1042
1043 return true, nil
1044 }
1045 }
1046
1047 func (f *frontmatterFieldHandlers) newDateFilenameHandler(setter func(d *FrontMatterDescriptor, t time.Time)) frontMatterFieldHandler {
1048 return func(d *FrontMatterDescriptor) (bool, error) {
1049 date, slug := dateAndSlugFromBaseFilename(d.Location, d.BaseFilename)
1050 if date.IsZero() {
1051 return false, nil
1052 }
1053
1054 setter(d, date)
1055
1056 if _, found := d.PageConfigEarly.Frontmatter["slug"]; !found {
1057 // Use slug from filename
1058 d.PageConfigLate.Slug = slug
1059 }
1060
1061 return true, nil
1062 }
1063 }
1064
1065 func (f *frontmatterFieldHandlers) newDateModTimeHandler(setter func(d *FrontMatterDescriptor, t time.Time)) frontMatterFieldHandler {
1066 return func(d *FrontMatterDescriptor) (bool, error) {
1067 if d.ModTime.IsZero() {
1068 return false, nil
1069 }
1070 setter(d, d.ModTime)
1071 return true, nil
1072 }
1073 }
1074
1075 func (f *frontmatterFieldHandlers) newDateGitAuthorDateHandler(setter func(d *FrontMatterDescriptor, t time.Time)) frontMatterFieldHandler {
1076 return func(d *FrontMatterDescriptor) (bool, error) {
1077 if d.GitAuthorDate.IsZero() {
1078 return false, nil
1079 }
1080 setter(d, d.GitAuthorDate)
1081 return true, nil
1082 }
1083 }