page.go (12202B)
1 // Copyright 2019 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 page contains the core interfaces and types for the Page resource,
15 // a core component in Hugo.
16 package page
17
18 import (
19 "html/template"
20
21 "github.com/gohugoio/hugo/identity"
22
23 "github.com/bep/gitmap"
24 "github.com/gohugoio/hugo/config"
25 "github.com/gohugoio/hugo/tpl"
26
27 "github.com/gohugoio/hugo/common/maps"
28 "github.com/gohugoio/hugo/compare"
29 "github.com/gohugoio/hugo/hugofs/files"
30
31 "github.com/gohugoio/hugo/navigation"
32 "github.com/gohugoio/hugo/related"
33 "github.com/gohugoio/hugo/resources/resource"
34 "github.com/gohugoio/hugo/source"
35 )
36
37 // Clear clears any global package state.
38 func Clear() error {
39 spc.clear()
40 return nil
41 }
42
43 // AlternativeOutputFormatsProvider provides alternative output formats for a
44 // Page.
45 type AlternativeOutputFormatsProvider interface {
46 // AlternativeOutputFormats gives the alternative output formats for the
47 // current output.
48 // Note that we use the term "alternative" and not "alternate" here, as it
49 // does not necessarily replace the other format, it is an alternative representation.
50 AlternativeOutputFormats() OutputFormats
51 }
52
53 // AuthorProvider provides author information.
54 type AuthorProvider interface {
55 // Deprecated.
56 Author() Author
57 // Deprecated.
58 Authors() AuthorList
59 }
60
61 // ChildCareProvider provides accessors to child resources.
62 type ChildCareProvider interface {
63 Pages() Pages
64
65 // RegularPages returns a list of pages of kind 'Page'.
66 // In Hugo 0.57 we changed the Pages method so it returns all page
67 // kinds, even sections. If you want the old behaviour, you can
68 // use RegularPages.
69 RegularPages() Pages
70
71 // RegularPagesRecursive returns all regular pages below the current
72 // section.
73 RegularPagesRecursive() Pages
74
75 Resources() resource.Resources
76 }
77
78 // ContentProvider provides the content related values for a Page.
79 type ContentProvider interface {
80 Content() (any, error)
81
82 // Plain returns the Page Content stripped of HTML markup.
83 Plain() string
84
85 // PlainWords returns a string slice from splitting Plain using https://pkg.go.dev/strings#Fields.
86 PlainWords() []string
87
88 // Summary returns a generated summary of the content.
89 // The breakpoint can be set manually by inserting a summary separator in the source file.
90 Summary() template.HTML
91
92 // Truncated returns whether the Summary is truncated or not.
93 Truncated() bool
94
95 // FuzzyWordCount returns the approximate number of words in the content.
96 FuzzyWordCount() int
97
98 // WordCount returns the number of words in the content.
99 WordCount() int
100
101 // ReadingTime returns the reading time based on the length of plain text.
102 ReadingTime() int
103
104 // Len returns the length of the content.
105 Len() int
106 }
107
108 // FileProvider provides the source file.
109 type FileProvider interface {
110 File() source.File
111 }
112
113 // GetPageProvider provides the GetPage method.
114 type GetPageProvider interface {
115 // GetPage looks up a page for the given ref.
116 // {{ with .GetPage "blog" }}{{ .Title }}{{ end }}
117 //
118 // This will return nil when no page could be found, and will return
119 // an error if the ref is ambiguous.
120 GetPage(ref string) (Page, error)
121
122 // GetPageWithTemplateInfo is for internal use only.
123 GetPageWithTemplateInfo(info tpl.Info, ref string) (Page, error)
124 }
125
126 // GitInfoProvider provides Git info.
127 type GitInfoProvider interface {
128 GitInfo() *gitmap.GitInfo
129 CodeOwners() []string
130 }
131
132 // InSectionPositioner provides section navigation.
133 type InSectionPositioner interface {
134 NextInSection() Page
135 PrevInSection() Page
136 }
137
138 // InternalDependencies is considered an internal interface.
139 type InternalDependencies interface {
140 // GetRelatedDocsHandler is for internal use only.
141 GetRelatedDocsHandler() *RelatedDocsHandler
142 }
143
144 // OutputFormatsProvider provides the OutputFormats of a Page.
145 type OutputFormatsProvider interface {
146 OutputFormats() OutputFormats
147 }
148
149 // Page is the core interface in Hugo.
150 type Page interface {
151 ContentProvider
152 TableOfContentsProvider
153 PageWithoutContent
154 }
155
156 // PageMetaProvider provides page metadata, typically provided via front matter.
157 type PageMetaProvider interface {
158 // The 4 page dates
159 resource.Dated
160
161 // Aliases forms the base for redirects generation.
162 Aliases() []string
163
164 // BundleType returns the bundle type: `leaf`, `branch` or an empty string.
165 BundleType() files.ContentClass
166
167 // A configured description.
168 Description() string
169
170 // Whether this is a draft. Will only be true if run with the --buildDrafts (-D) flag.
171 Draft() bool
172
173 // IsHome returns whether this is the home page.
174 IsHome() bool
175
176 // Configured keywords.
177 Keywords() []string
178
179 // The Page Kind. One of page, home, section, taxonomy, term.
180 Kind() string
181
182 // The configured layout to use to render this page. Typically set in front matter.
183 Layout() string
184
185 // The title used for links.
186 LinkTitle() string
187
188 // IsNode returns whether this is an item of one of the list types in Hugo,
189 // i.e. not a regular content
190 IsNode() bool
191
192 // IsPage returns whether this is a regular content
193 IsPage() bool
194
195 // Param looks for a param in Page and then in Site config.
196 Param(key any) (any, error)
197
198 // Path gets the relative path, including file name and extension if relevant,
199 // to the source of this Page. It will be relative to any content root.
200 Path() string
201
202 // This is just a temporary bridge method. Use Path in templates.
203 // Pathc is for internal usage only.
204 Pathc() string
205
206 // The slug, typically defined in front matter.
207 Slug() string
208
209 // This page's language code. Will be the same as the site's.
210 Lang() string
211
212 // IsSection returns whether this is a section
213 IsSection() bool
214
215 // Section returns the first path element below the content root.
216 Section() string
217
218 // Returns a slice of sections (directories if it's a file) to this
219 // Page.
220 SectionsEntries() []string
221
222 // SectionsPath is SectionsEntries joined with a /.
223 SectionsPath() string
224
225 // Sitemap returns the sitemap configuration for this page.
226 Sitemap() config.Sitemap
227
228 // Type is a discriminator used to select layouts etc. It is typically set
229 // in front matter, but will fall back to the root section.
230 Type() string
231
232 // The configured weight, used as the first sort value in the default
233 // page sort if non-zero.
234 Weight() int
235 }
236
237 // PageRenderProvider provides a way for a Page to render content.
238 type PageRenderProvider interface {
239 Render(layout ...string) (template.HTML, error)
240 RenderString(args ...any) (template.HTML, error)
241 }
242
243 // PageWithoutContent is the Page without any of the content methods.
244 type PageWithoutContent interface {
245 RawContentProvider
246 resource.Resource
247 PageMetaProvider
248 resource.LanguageProvider
249
250 // For pages backed by a file.
251 FileProvider
252
253 GitInfoProvider
254
255 // Output formats
256 OutputFormatsProvider
257 AlternativeOutputFormatsProvider
258
259 // Tree navigation
260 ChildCareProvider
261 TreeProvider
262
263 // Horizontal navigation
264 InSectionPositioner
265 PageRenderProvider
266 PaginatorProvider
267 Positioner
268 navigation.PageMenusProvider
269
270 // TODO(bep)
271 AuthorProvider
272
273 // Page lookups/refs
274 GetPageProvider
275 RefProvider
276
277 resource.TranslationKeyProvider
278 TranslationsProvider
279
280 SitesProvider
281
282 // Helper methods
283 ShortcodeInfoProvider
284 compare.Eqer
285
286 // Scratch returns a Scratch that can be used to store temporary state.
287 // Note that this Scratch gets reset on server rebuilds. See Store() for a variant that survives.
288 maps.Scratcher
289
290 // Store returns a Scratch that can be used to store temporary state.
291 // In contrast to Scratch(), this Scratch is not reset on server rebuilds.
292 Store() *maps.Scratch
293
294 RelatedKeywordsProvider
295
296 // GetTerms gets the terms of a given taxonomy,
297 // e.g. GetTerms("categories")
298 GetTerms(taxonomy string) Pages
299
300 // Used in change/dependency tracking.
301 identity.Provider
302
303 DeprecatedWarningPageMethods
304 }
305
306 // Positioner provides next/prev navigation.
307 type Positioner interface {
308 Next() Page
309 Prev() Page
310
311 // Deprecated: Use Prev. Will be removed in Hugo 0.57
312 PrevPage() Page
313
314 // Deprecated: Use Next. Will be removed in Hugo 0.57
315 NextPage() Page
316 }
317
318 // RawContentProvider provides the raw, unprocessed content of the page.
319 type RawContentProvider interface {
320 RawContent() string
321 }
322
323 // RefProvider provides the methods needed to create reflinks to pages.
324 type RefProvider interface {
325 Ref(argsm map[string]any) (string, error)
326
327 // RefFrom is for internal use only.
328 RefFrom(argsm map[string]any, source any) (string, error)
329
330 RelRef(argsm map[string]any) (string, error)
331
332 // RefFrom is for internal use only.
333 RelRefFrom(argsm map[string]any, source any) (string, error)
334 }
335
336 // RelatedKeywordsProvider allows a Page to be indexed.
337 type RelatedKeywordsProvider interface {
338 // Make it indexable as a related.Document
339 // RelatedKeywords is meant for internal usage only.
340 RelatedKeywords(cfg related.IndexConfig) ([]related.Keyword, error)
341 }
342
343 // ShortcodeInfoProvider provides info about the shortcodes in a Page.
344 type ShortcodeInfoProvider interface {
345 // HasShortcode return whether the page has a shortcode with the given name.
346 // This method is mainly motivated with the Hugo Docs site's need for a list
347 // of pages with the `todo` shortcode in it.
348 HasShortcode(name string) bool
349 }
350
351 // SitesProvider provide accessors to get sites.
352 type SitesProvider interface {
353 Site() Site
354 Sites() Sites
355 }
356
357 // TableOfContentsProvider provides the table of contents for a Page.
358 type TableOfContentsProvider interface {
359 TableOfContents() template.HTML
360 }
361
362 // TranslationsProvider provides access to any translations.
363 type TranslationsProvider interface {
364
365 // IsTranslated returns whether this content file is translated to
366 // other language(s).
367 IsTranslated() bool
368
369 // AllTranslations returns all translations, including the current Page.
370 AllTranslations() Pages
371
372 // Translations returns the translations excluding the current Page.
373 Translations() Pages
374 }
375
376 // TreeProvider provides section tree navigation.
377 type TreeProvider interface {
378
379 // IsAncestor returns whether the current page is an ancestor of the given
380 // Note that this method is not relevant for taxonomy lists and taxonomy terms pages.
381 IsAncestor(other any) (bool, error)
382
383 // CurrentSection returns the page's current section or the page itself if home or a section.
384 // Note that this will return nil for pages that is not regular, home or section pages.
385 CurrentSection() Page
386
387 // IsDescendant returns whether the current page is a descendant of the given
388 // Note that this method is not relevant for taxonomy lists and taxonomy terms pages.
389 IsDescendant(other any) (bool, error)
390
391 // FirstSection returns the section on level 1 below home, e.g. "/docs".
392 // For the home page, this will return itself.
393 FirstSection() Page
394
395 // InSection returns whether the given page is in the current section.
396 // Note that this will always return false for pages that are
397 // not either regular, home or section pages.
398 InSection(other any) (bool, error)
399
400 // Parent returns a section's parent section or a page's section.
401 // To get a section's subsections, see Page's Sections method.
402 Parent() Page
403
404 // Sections returns this section's subsections, if any.
405 // Note that for non-sections, this method will always return an empty list.
406 Sections() Pages
407
408 // Page returns a reference to the Page itself, kept here mostly
409 // for legacy reasons.
410 Page() Page
411 }
412
413 // DeprecatedWarningPageMethods lists deprecated Page methods that will trigger
414 // a WARNING if invoked.
415 // This was added in Hugo 0.55.
416 type DeprecatedWarningPageMethods any // This was emptied in Hugo 0.93.0.
417
418 // Move here to trigger ERROR instead of WARNING.
419 // TODO(bep) create wrappers and put into the Page once it has some methods.
420 type DeprecatedErrorPageMethods any