2019-01-02 11:33:26 +00:00
|
|
|
// Copyright 2019 The Hugo Authors. All rights reserved.
|
|
|
|
//
|
|
|
|
// Licensed under the Apache License, Version 2.0 (the "License");
|
|
|
|
// you may not use this file except in compliance with the License.
|
|
|
|
// You may obtain a copy of the License at
|
|
|
|
// http://www.apache.org/licenses/LICENSE-2.0
|
|
|
|
//
|
|
|
|
// Unless required by applicable law or agreed to in writing, software
|
|
|
|
// distributed under the License is distributed on an "AS IS" BASIS,
|
|
|
|
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
|
|
// See the License for the specific language governing permissions and
|
|
|
|
// limitations under the License.
|
|
|
|
|
|
|
|
// Package page contains the core interfaces and types for the Page resource,
|
|
|
|
// a core component in Hugo.
|
|
|
|
package page
|
|
|
|
|
|
|
|
import (
|
|
|
|
"html/template"
|
|
|
|
|
2020-09-07 13:07:10 +00:00
|
|
|
"github.com/gohugoio/hugo/identity"
|
|
|
|
|
2019-01-02 11:33:26 +00:00
|
|
|
"github.com/bep/gitmap"
|
|
|
|
"github.com/gohugoio/hugo/config"
|
2020-09-07 13:07:10 +00:00
|
|
|
"github.com/gohugoio/hugo/tpl"
|
2019-01-02 11:33:26 +00:00
|
|
|
|
|
|
|
"github.com/gohugoio/hugo/common/maps"
|
|
|
|
"github.com/gohugoio/hugo/compare"
|
2019-09-10 09:26:34 +00:00
|
|
|
"github.com/gohugoio/hugo/hugofs/files"
|
2019-01-02 11:33:26 +00:00
|
|
|
|
|
|
|
"github.com/gohugoio/hugo/navigation"
|
|
|
|
"github.com/gohugoio/hugo/related"
|
|
|
|
"github.com/gohugoio/hugo/resources/resource"
|
|
|
|
"github.com/gohugoio/hugo/source"
|
|
|
|
)
|
|
|
|
|
|
|
|
// Clear clears any global package state.
|
|
|
|
func Clear() error {
|
|
|
|
spc.clear()
|
|
|
|
return nil
|
|
|
|
}
|
|
|
|
|
|
|
|
// AlternativeOutputFormatsProvider provides alternative output formats for a
|
|
|
|
// Page.
|
|
|
|
type AlternativeOutputFormatsProvider interface {
|
|
|
|
// AlternativeOutputFormats gives the alternative output formats for the
|
|
|
|
// current output.
|
|
|
|
// Note that we use the term "alternative" and not "alternate" here, as it
|
|
|
|
// does not necessarily replace the other format, it is an alternative representation.
|
|
|
|
AlternativeOutputFormats() OutputFormats
|
|
|
|
}
|
|
|
|
|
|
|
|
// AuthorProvider provides author information.
|
|
|
|
type AuthorProvider interface {
|
2022-04-20 15:08:01 +00:00
|
|
|
// Deprecated.
|
2019-01-02 11:33:26 +00:00
|
|
|
Author() Author
|
2022-04-20 15:08:01 +00:00
|
|
|
// Deprecated.
|
2019-01-02 11:33:26 +00:00
|
|
|
Authors() AuthorList
|
|
|
|
}
|
|
|
|
|
|
|
|
// ChildCareProvider provides accessors to child resources.
|
|
|
|
type ChildCareProvider interface {
|
|
|
|
Pages() Pages
|
2019-08-03 15:27:40 +00:00
|
|
|
|
|
|
|
// RegularPages returns a list of pages of kind 'Page'.
|
|
|
|
// In Hugo 0.57 we changed the Pages method so it returns all page
|
|
|
|
// kinds, even sections. If you want the old behaviour, you can
|
|
|
|
// use RegularPages.
|
|
|
|
RegularPages() Pages
|
|
|
|
|
2020-03-16 10:37:57 +00:00
|
|
|
// RegularPagesRecursive returns all regular pages below the current
|
|
|
|
// section.
|
|
|
|
RegularPagesRecursive() Pages
|
|
|
|
|
2019-01-02 11:33:26 +00:00
|
|
|
Resources() resource.Resources
|
|
|
|
}
|
|
|
|
|
|
|
|
// ContentProvider provides the content related values for a Page.
|
|
|
|
type ContentProvider interface {
|
2022-03-17 21:03:27 +00:00
|
|
|
Content() (any, error)
|
2022-04-21 08:59:13 +00:00
|
|
|
|
|
|
|
// Plain returns the Page Content stripped of HTML markup.
|
2019-01-02 11:33:26 +00:00
|
|
|
Plain() string
|
2022-04-21 08:59:13 +00:00
|
|
|
|
|
|
|
// PlainWords returns a string slice from splitting Plain using https://pkg.go.dev/strings#Fields.
|
2019-01-02 11:33:26 +00:00
|
|
|
PlainWords() []string
|
2022-04-21 08:59:13 +00:00
|
|
|
|
|
|
|
// Summary returns a generated summary of the content.
|
|
|
|
// The breakpoint can be set manually by inserting a summary separator in the source file.
|
2019-01-02 11:33:26 +00:00
|
|
|
Summary() template.HTML
|
2022-04-21 08:59:13 +00:00
|
|
|
|
|
|
|
// Truncated returns whether the Summary is truncated or not.
|
2019-01-02 11:33:26 +00:00
|
|
|
Truncated() bool
|
2022-04-21 08:59:13 +00:00
|
|
|
|
|
|
|
// FuzzyWordCount returns the approximate number of words in the content.
|
2019-01-02 11:33:26 +00:00
|
|
|
FuzzyWordCount() int
|
2022-04-21 08:59:13 +00:00
|
|
|
|
|
|
|
// WordCount returns the number of words in the content.
|
2019-01-02 11:33:26 +00:00
|
|
|
WordCount() int
|
2022-04-21 08:59:13 +00:00
|
|
|
|
|
|
|
// ReadingTime returns the reading time based on the length of plain text.
|
2019-01-02 11:33:26 +00:00
|
|
|
ReadingTime() int
|
2022-04-21 08:59:13 +00:00
|
|
|
|
|
|
|
// Len returns the length of the content.
|
2019-01-02 11:33:26 +00:00
|
|
|
Len() int
|
|
|
|
}
|
|
|
|
|
|
|
|
// FileProvider provides the source file.
|
|
|
|
type FileProvider interface {
|
|
|
|
File() source.File
|
|
|
|
}
|
|
|
|
|
|
|
|
// GetPageProvider provides the GetPage method.
|
|
|
|
type GetPageProvider interface {
|
|
|
|
// GetPage looks up a page for the given ref.
|
|
|
|
// {{ with .GetPage "blog" }}{{ .Title }}{{ end }}
|
|
|
|
//
|
|
|
|
// This will return nil when no page could be found, and will return
|
|
|
|
// an error if the ref is ambiguous.
|
|
|
|
GetPage(ref string) (Page, error)
|
2020-09-07 13:07:10 +00:00
|
|
|
|
|
|
|
// GetPageWithTemplateInfo is for internal use only.
|
|
|
|
GetPageWithTemplateInfo(info tpl.Info, ref string) (Page, error)
|
2019-01-02 11:33:26 +00:00
|
|
|
}
|
|
|
|
|
|
|
|
// GitInfoProvider provides Git info.
|
|
|
|
type GitInfoProvider interface {
|
|
|
|
GitInfo() *gitmap.GitInfo
|
2022-02-27 18:40:07 +00:00
|
|
|
CodeOwners() []string
|
2019-01-02 11:33:26 +00:00
|
|
|
}
|
|
|
|
|
|
|
|
// InSectionPositioner provides section navigation.
|
|
|
|
type InSectionPositioner interface {
|
|
|
|
NextInSection() Page
|
|
|
|
PrevInSection() Page
|
|
|
|
}
|
|
|
|
|
|
|
|
// InternalDependencies is considered an internal interface.
|
|
|
|
type InternalDependencies interface {
|
2022-04-20 15:08:01 +00:00
|
|
|
// GetRelatedDocsHandler is for internal use only.
|
2019-01-02 11:33:26 +00:00
|
|
|
GetRelatedDocsHandler() *RelatedDocsHandler
|
|
|
|
}
|
|
|
|
|
|
|
|
// OutputFormatsProvider provides the OutputFormats of a Page.
|
|
|
|
type OutputFormatsProvider interface {
|
|
|
|
OutputFormats() OutputFormats
|
|
|
|
}
|
|
|
|
|
|
|
|
// Page is the core interface in Hugo.
|
|
|
|
type Page interface {
|
|
|
|
ContentProvider
|
|
|
|
TableOfContentsProvider
|
|
|
|
PageWithoutContent
|
|
|
|
}
|
|
|
|
|
|
|
|
// PageMetaProvider provides page metadata, typically provided via front matter.
|
|
|
|
type PageMetaProvider interface {
|
|
|
|
// The 4 page dates
|
|
|
|
resource.Dated
|
|
|
|
|
|
|
|
// Aliases forms the base for redirects generation.
|
|
|
|
Aliases() []string
|
|
|
|
|
2022-04-21 08:59:13 +00:00
|
|
|
// BundleType returns the bundle type: `leaf`, `branch` or an empty string.
|
2019-09-10 09:26:34 +00:00
|
|
|
BundleType() files.ContentClass
|
2019-01-02 11:33:26 +00:00
|
|
|
|
|
|
|
// A configured description.
|
|
|
|
Description() string
|
|
|
|
|
|
|
|
// Whether this is a draft. Will only be true if run with the --buildDrafts (-D) flag.
|
|
|
|
Draft() bool
|
|
|
|
|
|
|
|
// IsHome returns whether this is the home page.
|
|
|
|
IsHome() bool
|
|
|
|
|
|
|
|
// Configured keywords.
|
|
|
|
Keywords() []string
|
|
|
|
|
2020-06-16 13:43:50 +00:00
|
|
|
// The Page Kind. One of page, home, section, taxonomy, term.
|
2019-01-02 11:33:26 +00:00
|
|
|
Kind() string
|
|
|
|
|
|
|
|
// The configured layout to use to render this page. Typically set in front matter.
|
|
|
|
Layout() string
|
|
|
|
|
|
|
|
// The title used for links.
|
|
|
|
LinkTitle() string
|
|
|
|
|
|
|
|
// IsNode returns whether this is an item of one of the list types in Hugo,
|
|
|
|
// i.e. not a regular content
|
|
|
|
IsNode() bool
|
|
|
|
|
|
|
|
// IsPage returns whether this is a regular content
|
|
|
|
IsPage() bool
|
|
|
|
|
|
|
|
// Param looks for a param in Page and then in Site config.
|
2022-03-17 21:03:27 +00:00
|
|
|
Param(key any) (any, error)
|
2019-01-02 11:33:26 +00:00
|
|
|
|
|
|
|
// Path gets the relative path, including file name and extension if relevant,
|
|
|
|
// to the source of this Page. It will be relative to any content root.
|
|
|
|
Path() string
|
|
|
|
|
2022-01-04 12:07:10 +00:00
|
|
|
// This is just a temporary bridge method. Use Path in templates.
|
2022-04-20 15:11:27 +00:00
|
|
|
// Pathc is for internal usage only.
|
2022-01-04 12:07:10 +00:00
|
|
|
Pathc() string
|
|
|
|
|
2019-01-02 11:33:26 +00:00
|
|
|
// The slug, typically defined in front matter.
|
|
|
|
Slug() string
|
|
|
|
|
|
|
|
// This page's language code. Will be the same as the site's.
|
|
|
|
Lang() string
|
|
|
|
|
|
|
|
// IsSection returns whether this is a section
|
|
|
|
IsSection() bool
|
|
|
|
|
|
|
|
// Section returns the first path element below the content root.
|
|
|
|
Section() string
|
|
|
|
|
|
|
|
// Returns a slice of sections (directories if it's a file) to this
|
|
|
|
// Page.
|
|
|
|
SectionsEntries() []string
|
|
|
|
|
|
|
|
// SectionsPath is SectionsEntries joined with a /.
|
|
|
|
SectionsPath() string
|
|
|
|
|
|
|
|
// Sitemap returns the sitemap configuration for this page.
|
|
|
|
Sitemap() config.Sitemap
|
|
|
|
|
|
|
|
// Type is a discriminator used to select layouts etc. It is typically set
|
|
|
|
// in front matter, but will fall back to the root section.
|
|
|
|
Type() string
|
|
|
|
|
|
|
|
// The configured weight, used as the first sort value in the default
|
|
|
|
// page sort if non-zero.
|
|
|
|
Weight() int
|
|
|
|
}
|
|
|
|
|
2019-11-27 12:42:36 +00:00
|
|
|
// PageRenderProvider provides a way for a Page to render content.
|
2019-01-02 11:33:26 +00:00
|
|
|
type PageRenderProvider interface {
|
2019-11-27 12:42:36 +00:00
|
|
|
Render(layout ...string) (template.HTML, error)
|
2022-03-17 21:03:27 +00:00
|
|
|
RenderString(args ...any) (template.HTML, error)
|
2019-01-02 11:33:26 +00:00
|
|
|
}
|
|
|
|
|
|
|
|
// PageWithoutContent is the Page without any of the content methods.
|
|
|
|
type PageWithoutContent interface {
|
|
|
|
RawContentProvider
|
|
|
|
resource.Resource
|
|
|
|
PageMetaProvider
|
|
|
|
resource.LanguageProvider
|
|
|
|
|
|
|
|
// For pages backed by a file.
|
|
|
|
FileProvider
|
|
|
|
|
2019-04-05 14:52:37 +00:00
|
|
|
GitInfoProvider
|
|
|
|
|
2019-01-02 11:33:26 +00:00
|
|
|
// Output formats
|
|
|
|
OutputFormatsProvider
|
|
|
|
AlternativeOutputFormatsProvider
|
|
|
|
|
|
|
|
// Tree navigation
|
|
|
|
ChildCareProvider
|
|
|
|
TreeProvider
|
|
|
|
|
2019-07-31 12:36:36 +00:00
|
|
|
// Horizontal navigation
|
2019-01-02 11:33:26 +00:00
|
|
|
InSectionPositioner
|
|
|
|
PageRenderProvider
|
|
|
|
PaginatorProvider
|
|
|
|
Positioner
|
|
|
|
navigation.PageMenusProvider
|
|
|
|
|
|
|
|
// TODO(bep)
|
|
|
|
AuthorProvider
|
|
|
|
|
|
|
|
// Page lookups/refs
|
|
|
|
GetPageProvider
|
|
|
|
RefProvider
|
|
|
|
|
|
|
|
resource.TranslationKeyProvider
|
|
|
|
TranslationsProvider
|
|
|
|
|
|
|
|
SitesProvider
|
|
|
|
|
|
|
|
// Helper methods
|
|
|
|
ShortcodeInfoProvider
|
|
|
|
compare.Eqer
|
2022-02-22 13:42:33 +00:00
|
|
|
|
|
|
|
// Scratch returns a Scratch that can be used to store temporary state.
|
|
|
|
// Note that this Scratch gets reset on server rebuilds. See Store() for a variant that survives.
|
2019-01-02 11:33:26 +00:00
|
|
|
maps.Scratcher
|
2022-02-22 13:42:33 +00:00
|
|
|
|
|
|
|
// Store returns a Scratch that can be used to store temporary state.
|
|
|
|
// In contrast to Scratch(), this Scratch is not reset on server rebuilds.
|
|
|
|
Store() *maps.Scratch
|
|
|
|
|
2019-01-02 11:33:26 +00:00
|
|
|
RelatedKeywordsProvider
|
|
|
|
|
2020-02-19 08:16:27 +00:00
|
|
|
// GetTerms gets the terms of a given taxonomy,
|
|
|
|
// e.g. GetTerms("categories")
|
|
|
|
GetTerms(taxonomy string) Pages
|
|
|
|
|
2020-09-07 13:07:10 +00:00
|
|
|
// Used in change/dependency tracking.
|
|
|
|
identity.Provider
|
|
|
|
|
2019-01-02 11:33:26 +00:00
|
|
|
DeprecatedWarningPageMethods
|
|
|
|
}
|
|
|
|
|
|
|
|
// Positioner provides next/prev navigation.
|
|
|
|
type Positioner interface {
|
|
|
|
Next() Page
|
|
|
|
Prev() Page
|
|
|
|
|
|
|
|
// Deprecated: Use Prev. Will be removed in Hugo 0.57
|
|
|
|
PrevPage() Page
|
|
|
|
|
|
|
|
// Deprecated: Use Next. Will be removed in Hugo 0.57
|
|
|
|
NextPage() Page
|
|
|
|
}
|
|
|
|
|
|
|
|
// RawContentProvider provides the raw, unprocessed content of the page.
|
|
|
|
type RawContentProvider interface {
|
|
|
|
RawContent() string
|
|
|
|
}
|
|
|
|
|
|
|
|
// RefProvider provides the methods needed to create reflinks to pages.
|
|
|
|
type RefProvider interface {
|
2022-03-17 21:03:27 +00:00
|
|
|
Ref(argsm map[string]any) (string, error)
|
2022-04-20 15:11:27 +00:00
|
|
|
|
|
|
|
// RefFrom is for internal use only.
|
2022-03-17 21:03:27 +00:00
|
|
|
RefFrom(argsm map[string]any, source any) (string, error)
|
2022-04-20 15:11:27 +00:00
|
|
|
|
2022-03-17 21:03:27 +00:00
|
|
|
RelRef(argsm map[string]any) (string, error)
|
2022-04-20 15:11:27 +00:00
|
|
|
|
|
|
|
// RefFrom is for internal use only.
|
2022-03-17 21:03:27 +00:00
|
|
|
RelRefFrom(argsm map[string]any, source any) (string, error)
|
2019-01-02 11:33:26 +00:00
|
|
|
}
|
|
|
|
|
|
|
|
// RelatedKeywordsProvider allows a Page to be indexed.
|
|
|
|
type RelatedKeywordsProvider interface {
|
|
|
|
// Make it indexable as a related.Document
|
2022-04-20 15:11:27 +00:00
|
|
|
// RelatedKeywords is meant for internal usage only.
|
2019-01-02 11:33:26 +00:00
|
|
|
RelatedKeywords(cfg related.IndexConfig) ([]related.Keyword, error)
|
|
|
|
}
|
|
|
|
|
|
|
|
// ShortcodeInfoProvider provides info about the shortcodes in a Page.
|
|
|
|
type ShortcodeInfoProvider interface {
|
|
|
|
// HasShortcode return whether the page has a shortcode with the given name.
|
|
|
|
// This method is mainly motivated with the Hugo Docs site's need for a list
|
|
|
|
// of pages with the `todo` shortcode in it.
|
|
|
|
HasShortcode(name string) bool
|
|
|
|
}
|
|
|
|
|
|
|
|
// SitesProvider provide accessors to get sites.
|
|
|
|
type SitesProvider interface {
|
|
|
|
Site() Site
|
|
|
|
Sites() Sites
|
|
|
|
}
|
|
|
|
|
|
|
|
// TableOfContentsProvider provides the table of contents for a Page.
|
|
|
|
type TableOfContentsProvider interface {
|
|
|
|
TableOfContents() template.HTML
|
|
|
|
}
|
|
|
|
|
|
|
|
// TranslationsProvider provides access to any translations.
|
|
|
|
type TranslationsProvider interface {
|
|
|
|
|
|
|
|
// IsTranslated returns whether this content file is translated to
|
|
|
|
// other language(s).
|
|
|
|
IsTranslated() bool
|
|
|
|
|
|
|
|
// AllTranslations returns all translations, including the current Page.
|
|
|
|
AllTranslations() Pages
|
|
|
|
|
|
|
|
// Translations returns the translations excluding the current Page.
|
|
|
|
Translations() Pages
|
|
|
|
}
|
|
|
|
|
|
|
|
// TreeProvider provides section tree navigation.
|
|
|
|
type TreeProvider interface {
|
|
|
|
|
|
|
|
// IsAncestor returns whether the current page is an ancestor of the given
|
|
|
|
// Note that this method is not relevant for taxonomy lists and taxonomy terms pages.
|
2022-03-17 21:03:27 +00:00
|
|
|
IsAncestor(other any) (bool, error)
|
2019-01-02 11:33:26 +00:00
|
|
|
|
|
|
|
// CurrentSection returns the page's current section or the page itself if home or a section.
|
|
|
|
// Note that this will return nil for pages that is not regular, home or section pages.
|
|
|
|
CurrentSection() Page
|
|
|
|
|
|
|
|
// IsDescendant returns whether the current page is a descendant of the given
|
|
|
|
// Note that this method is not relevant for taxonomy lists and taxonomy terms pages.
|
2022-03-17 21:03:27 +00:00
|
|
|
IsDescendant(other any) (bool, error)
|
2019-01-02 11:33:26 +00:00
|
|
|
|
|
|
|
// FirstSection returns the section on level 1 below home, e.g. "/docs".
|
|
|
|
// For the home page, this will return itself.
|
|
|
|
FirstSection() Page
|
|
|
|
|
|
|
|
// InSection returns whether the given page is in the current section.
|
|
|
|
// Note that this will always return false for pages that are
|
|
|
|
// not either regular, home or section pages.
|
2022-03-17 21:03:27 +00:00
|
|
|
InSection(other any) (bool, error)
|
2019-01-02 11:33:26 +00:00
|
|
|
|
|
|
|
// Parent returns a section's parent section or a page's section.
|
|
|
|
// To get a section's subsections, see Page's Sections method.
|
|
|
|
Parent() Page
|
|
|
|
|
|
|
|
// Sections returns this section's subsections, if any.
|
|
|
|
// Note that for non-sections, this method will always return an empty list.
|
|
|
|
Sections() Pages
|
2019-03-25 06:54:10 +00:00
|
|
|
|
|
|
|
// Page returns a reference to the Page itself, kept here mostly
|
|
|
|
// for legacy reasons.
|
|
|
|
Page() Page
|
2019-01-02 11:33:26 +00:00
|
|
|
}
|
|
|
|
|
|
|
|
// DeprecatedWarningPageMethods lists deprecated Page methods that will trigger
|
|
|
|
// a WARNING if invoked.
|
|
|
|
// This was added in Hugo 0.55.
|
2022-03-17 21:03:27 +00:00
|
|
|
type DeprecatedWarningPageMethods any // This was emptied in Hugo 0.93.0.
|
2019-01-02 11:33:26 +00:00
|
|
|
|
|
|
|
// Move here to trigger ERROR instead of WARNING.
|
|
|
|
// TODO(bep) create wrappers and put into the Page once it has some methods.
|
2022-03-17 21:03:27 +00:00
|
|
|
type DeprecatedErrorPageMethods any
|