page

package
v0.0.0-...-5b3a7c8 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 13, 2022 License: Apache-2.0 Imports: 30 Imported by: 0

Documentation

Overview

Package page contains the core interfaces and types for the Page resource, a core component in Hugo.

Index

Constants

View Source 
const (
	KindPage = "page"

	KindHome    = "home"
	KindSection = "section"

	// Note tha before Hugo 0.73 these were confusingly named
	// taxonomy (now: term)
	// taxonomyTerm (now: taxonomy)
	KindTaxonomy = "taxonomy"
	KindTerm     = "term"
)

Variables

View Source 
var (
	NopPage Page = new(nopPage)
	NilPage *nopPage
)
View Source 
var (
	// DefaultPageSort is the default sort func for pages in Hugo:
	// Order by Ordinal, Weight, Date, LinkTitle and then full file path.
	DefaultPageSort = func(p1, p2 Page) bool {
		o1, o2 := getOrdinals(p1, p2)
		if o1 != o2 && o1 != -1 && o2 != -1 {
			return o1 < o2
		}
		if p1.Weight() == p2.Weight() {
			if p1.Date().Unix() == p2.Date().Unix() {
				c := collatorStringCompare(func(p Page) string { return p.LinkTitle() }, p1, p2)
				if c == 0 {
					if p1.File().IsZero() || p2.File().IsZero() {
						return p1.File().IsZero()
					}
					return compare.LessStrings(p1.File().Filename(), p2.File().Filename())
				}
				return c < 0
			}
			return p1.Date().Unix() > p2.Date().Unix()
		}

		if p2.Weight() == 0 {
			return true
		}

		if p1.Weight() == 0 {
			return false
		}

		return p1.Weight() < p2.Weight()
	}
)

Functions

func GetKind 

func GetKind(s string) string

GetKind gets the page kind given a string, empty if not found.

func NewZeroFile 

func NewZeroFile() source.File

func ResolvePagerSize 

func ResolvePagerSize(cfg config.Provider, options ...any) (int, error)

func SortByDefault 

func SortByDefault(pages Pages)

SortByDefault sorts pages by the default sort.

Types

type AlternativeOutputFormatsProvider 

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
}

AlternativeOutputFormatsProvider provides alternative output formats for a Page.

type ChildCareProvider 

type ChildCareProvider interface {
	Pages() Pages

	// 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

	// RegularPagesRecursive returns all regular pages below the current
	// section.
	RegularPagesRecursive() Pages

	Resources() resource.Resources
}

ChildCareProvider provides accessors to child resources.

type ContentProvider 

type ContentProvider interface {
	Content() (any, error)

	// Plain returns the Page Content stripped of HTML markup.
	Plain() string

	// PlainWords returns a string slice from splitting Plain using https://pkg.go.dev/strings#Fields.
	PlainWords() []string

	// Summary returns a generated summary of the content.
	// The breakpoint can be set manually by inserting a summary separator in the source file.
	Summary() template.HTML

	// Truncated returns whether the Summary  is truncated or not.
	Truncated() bool

	// FuzzyWordCount returns the approximate number of words in the content.
	FuzzyWordCount() int

	// WordCount returns the number of words in the content.
	WordCount() int

	// ReadingTime returns the reading time based on the length of plain text.
	ReadingTime() int

	// Len returns the length of the content.
	Len() int
}

ContentProvider provides the content related values for a Page.

type Data 

type Data map[string]any

Data represents the .Data element in a Page in Hugo. We make this a type so we can do lazy loading of .Data.Pages

func (Data) Pages 

func (d Data) Pages() Pages

Pages returns the pages stored with key "pages". If this is a func, it will be invoked.

type FileProvider 

type FileProvider interface {
	File() source.File
}

FileProvider provides the source file.

type GetPageProvider 

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)

	// GetPageWithTemplateInfo is for internal use only.
	GetPageWithTemplateInfo(info tpl.Info, ref string) (Page, error)
}

GetPageProvider provides the GetPage method.

type InSectionPositioner 

type InSectionPositioner interface {
	NextInSection() Page
	PrevInSection() Page
}

InSectionPositioner provides section navigation.

type LazyContentProvider 

type LazyContentProvider struct {
	// contains filtered or unexported fields
}

LazyContentProvider initializes itself when read. Each method of the ContentProvider interface initializes a content provider and shares it with other methods.

Used in cases where we cannot guarantee whether the content provider will be needed. Must create via NewLazyContentProvider.

func NewLazyContentProvider 

func NewLazyContentProvider(f func() (OutputFormatContentProvider, error)) *LazyContentProvider

NewLazyContentProvider returns a LazyContentProvider initialized with function f. The resulting LazyContentProvider calls f in order to retrieve a ContentProvider

func (*LazyContentProvider) Content 

func (lcp *LazyContentProvider) Content() (any, error)

func (*LazyContentProvider) FuzzyWordCount 

func (lcp *LazyContentProvider) FuzzyWordCount() int

func (*LazyContentProvider) Len 

func (lcp *LazyContentProvider) Len() int

func (*LazyContentProvider) Plain 

func (lcp *LazyContentProvider) Plain() string

func (*LazyContentProvider) PlainWords 

func (lcp *LazyContentProvider) PlainWords() []string

func (*LazyContentProvider) ReadingTime 

func (lcp *LazyContentProvider) ReadingTime() int

func (*LazyContentProvider) RenderString 

func (lcp *LazyContentProvider) RenderString(args ...any) (template.HTML, error)

func (*LazyContentProvider) Reset 

func (lcp *LazyContentProvider) Reset()

func (*LazyContentProvider) Summary 

func (lcp *LazyContentProvider) Summary() template.HTML

func (*LazyContentProvider) TableOfContents 

func (lcp *LazyContentProvider) TableOfContents() template.HTML

func (*LazyContentProvider) Truncated 

func (lcp *LazyContentProvider) Truncated() bool

func (*LazyContentProvider) WordCount 

func (lcp *LazyContentProvider) WordCount() int

type OutputFormat 

type OutputFormat struct {
	// Rel contains a value that can be used to construct a rel link.
	// This is value is fetched from the output format definition.
	// Note that for pages with only one output format,
	// this method will always return "canonical".
	// As an example, the AMP output format will, by default, return "amphtml".
	//
	// See:
	// https://www.ampproject.org/docs/guides/deploy/discovery
	//
	// Most other output formats will have "alternate" as value for this.
	Rel string

	Format output.Format
	// contains filtered or unexported fields
}

OutputFormat links to a representation of a resource.

func NewOutputFormat 

func NewOutputFormat(relPermalink, permalink string, isCanonical bool, f output.Format) OutputFormat
func (o OutputFormat) Permalink() string

Permalink returns the absolute permalink to this output format. 

func (o OutputFormat) RelPermalink() string

RelPermalink returns the relative permalink to this output format.

type OutputFormatContentProvider 

type OutputFormatContentProvider interface {
	ContentProvider
	TableOfContentsProvider
	PageRenderProvider
}

OutputFormatContentProvider represents the method set that is "outputFormat aware" and that we provide lazy initialization for in case they get invoked outside of their normal rendering context, e.g. via .Translations. Note that this set is currently not complete, but should cover the most common use cases. For the others, the implementation will be from the page.NoopPage.

type OutputFormats 

type OutputFormats []OutputFormat

OutputFormats holds a list of the relevant output formats for a given page.

func (OutputFormats) Get 

func (o OutputFormats) Get(name string) *OutputFormat

Get gets a OutputFormat given its name, i.e. json, html etc. It returns nil if none found.

type OutputFormatsProvider 

type OutputFormatsProvider interface {
	OutputFormats() OutputFormats
}

OutputFormatsProvider provides the OutputFormats of a Page.

type Page 

type Page interface {
	ContentProvider
	TableOfContentsProvider
	PageWithoutContent
}

Page is the core interface in Hugo.

type PageGroup 

type PageGroup struct {
	// The key, typically a year or similar.
	Key any

	// The Pages in this group.
	Pages
}

PageGroup represents a group of pages, grouped by the key. The key is typically a year or similar.

type PageMatcher 

type PageMatcher struct {
	// A Glob pattern matching the content path below /content.
	// Expects Unix-styled slashes.
	// Note that this is the virtual path, so it starts at the mount root
	// with a leading "/".
	Path string

	// A Glob pattern matching the Page's Kind(s), e.g. "{home,section}"
	Kind string

	// A Glob pattern matching the Page's language, e.g. "{en,sv}".
	Lang string

	// A Glob pattern matching the Page's Environment, e.g. "{production,development}".
	Environment string
}

A PageMatcher can be used to match a Page with Glob patterns. Note that the pattern matching is case insensitive.

func (PageMatcher) Matches 

func (m PageMatcher) Matches(p Page) bool

Matches returns whether p matches this matcher.

type PageMetaProvider 

type PageMetaProvider interface {
	// Dated The 4 page dates
	resource.Dated

	// Description A configured description.
	Description() string

	// IsHome returns whether this is the home page.
	IsHome() bool

	// Kind The Page Kind. One of page, home, section, taxonomy, term.
	Kind() string

	// Layout The configured layout to use to render this page. Typically set in front matter.
	Layout() string

	// LinkTitle 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.
	Param(key any) (any, error)

	// 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

	// Pathc This is just a temporary bridge method. Use Path in templates.
	// Pathc is for internal usage only.
	Pathc() string

	// Slug The slug, typically defined in front matter.
	Slug() string

	// IsSection returns whether this is a section
	IsSection() bool

	// Section returns the first path element below the content root.
	Section() string

	// SectionsEntries Returns a slice of sections (directories if it's a file) to this
	// Page.
	SectionsEntries() []string

	// SectionsPath is SectionsEntries joined with a /.
	SectionsPath() string

	// 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

	// Weight The configured weight, used as the first sort value in the default
	// page sort if non-zero.
	Weight() int
}

PageMetaProvider provides page metadata, typically provided via front matter.

type PageRenderProvider 

type PageRenderProvider interface {
	RenderString(args ...any) (template.HTML, error)
}

PageRenderProvider provides a way for a Page to render content.

type PageWithoutContent 

type PageWithoutContent interface {
	resource.Resource
	PageMetaProvider

	// FileProvider For pages backed by a file.
	FileProvider

	// OutputFormatsProvider Output formats
	OutputFormatsProvider

	TreeProvider

	SitesProvider
	identity.Provider
	PaginatorProvider
	PageRenderProvider
	AlternativeOutputFormatsProvider
}

PageWithoutContent is the Page without any of the content methods.

type Pager 

type Pager struct {
	*Paginator
	// contains filtered or unexported fields
}

Pager represents one of the elements in a paginator. The number, starting on 1, represents its place.

func (Pager) String 

func (p Pager) String() string

type Pages 

type Pages []Page

Pages is a slice of Page objects. This is the most common list type in Hugo.

func ToPages 

func ToPages(seq any) (Pages, error)

ToPages tries to convert seq into Pages.

func (Pages) Len 

func (p Pages) Len() int

Len returns the number of pages in the list.

type PagesFactory 

type PagesFactory func() Pages

PagesFactory somehow creates some Pages. We do a lot of lazy Pages initialization in Hugo, so we need a type.

type PagesGroup 

type PagesGroup []PageGroup

PagesGroup represents a list of page groups. This is what you get when doing page grouping in the templates.

func ToPagesGroup 

func ToPagesGroup(seq any) (PagesGroup, error)

ToPagesGroup tries to convert seq into a PagesGroup.

func (PagesGroup) Len 

func (psg PagesGroup) Len() int

Len returns the number of pages in the page group.

type Paginator 

type Paginator struct {
	// contains filtered or unexported fields
}

func Paginate 

func Paginate(td TargetPathDescriptor, seq any, pagerSize int) (*Paginator, error)

func (*Paginator) Pagers 

func (p *Paginator) Pagers() pagers

Pagers returns a list of pagers that can be used to build a pagination menu.

type PaginatorProvider 

type PaginatorProvider interface {
	Paginator(options ...any) (*Pager, error)
	Paginate(seq any, options ...any) (*Pager, error)
}

PaginatorProvider provides two ways to create a page paginator.

type Positioner 

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
}

Positioner provides next/prev navigation.

type RawContentProvider 

type RawContentProvider interface {
	RawContent() string
}

RawContentProvider provides the raw, unprocessed content of the page.

type RefProvider 

type RefProvider interface {
	Ref(argsm map[string]any) (string, error)

	// RefFrom is for internal use only.
	RefFrom(argsm map[string]any, source any) (string, error)

	RelRef(argsm map[string]any) (string, error)

	// RefFrom is for internal use only.
	RelRefFrom(argsm map[string]any, source any) (string, error)
}

RefProvider provides the methods needed to create reflinks to pages.

type RelatedDocsHandler 

type RelatedDocsHandler struct {
	// contains filtered or unexported fields
}

type RelatedKeywordsProvider 

type RelatedKeywordsProvider interface {
	// Make it indexable as a related.Document
	// RelatedKeywords is meant for internal usage only.
	RelatedKeywords(cfg related.IndexConfig) ([]related.Keyword, error)
}

RelatedKeywordsProvider allows a Page to be indexed.

type ShortcodeInfoProvider 

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
}

ShortcodeInfoProvider provides info about the shortcodes in a Page.

type Site 

type Site interface {
	// RegularPages Returns all the regular Pages in this Site.
	RegularPages() Pages

	// Pages Returns all Pages in this Site.
	Pages() Pages

	// Home A shortcut to the home page.
	Home() Page

	// Title Returns the configured title for this Site.
	Title() string

	// Current Returns Site currently rendering.
	Current() Site

	// BaseURL Returns the BaseURL for this Site.
	BaseURL() template.URL

	// Data Returns a map of all the data inside /data.
	Data() map[string]any
}

Site represents a site in the build. This is currently a very narrow interface, but the actual implementation will be richer, see hugolib.SiteInfo.

type Sites 

type Sites []Site

Sites represents an ordered list of sites (languages).

type SitesProvider 

type SitesProvider interface {
	Site() Site
	Sites() Sites
}

SitesProvider provide accessors to get sites.

type TableOfContentsProvider 

type TableOfContentsProvider interface {
	TableOfContents() template.HTML
}

TableOfContentsProvider provides the table of contents for a Page.

type TargetPathDescriptor 

type TargetPathDescriptor struct {
	PathSpec *helpers.PathSpec

	Type output.Format
	Kind string

	Sections []string

	// For regular content pages this is either
	// 1) the Slug, if set,
	// 2) the file base name (TranslationBaseName).
	BaseName string

	// Source directory.
	Dir string

	// Typically a language prefix added to file paths.
	PrefixFilePath string

	// Typically a language prefix added to links.
	PrefixLink string

	// If in multihost mode etc., every link/path needs to be prefixed, even
	// if set in URL.
	ForcePrefix bool

	// URL from front matter if set. Will override any Slug etc.
	URL string

	// Used to create paginator links.
	Addends string

	// The expanded permalink if defined for the section, ready to use.
	ExpandedPermalink string
}

TargetPathDescriptor describes how a file path for a given resource should look like on the file system. The same descriptor is then later used to create both the permalinks and the relative links, paginator URLs etc.

The big motivating behind this is to have only one source of truth for URLs, and by that also get rid of most of the fragile string parsing/encoding etc.

type TargetPaths 

type TargetPaths struct {

	// Where to store the file on disk relative to the publish dir. OS slashes.
	TargetFilename string

	// The directory to write sub-resources of the above.
	SubResourceBaseTarget string

	// The base for creating links to sub-resources of the above.
	SubResourceBaseLink string

	// The relative permalink to this resources. Unix slashes.
	Link string
}

TODO(bep) move this type.

func CreateTargetPaths 

func CreateTargetPaths(d TargetPathDescriptor) (tp TargetPaths)

func (TargetPaths) PermalinkForOutputFormat 

func (p TargetPaths) PermalinkForOutputFormat(s *helpers.PathSpec, f output.Format) string
func (p TargetPaths) RelPermalink(s *helpers.PathSpec) string

type TreeProvider 

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.
	IsAncestor(other any) (bool, error)

	// 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.
	IsDescendant(other any) (bool, error)

	// 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.
	InSection(other any) (bool, error)

	// 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

	// Page returns a reference to the Page itself, kept here mostly
	// for legacy reasons.
	Page() Page
}

TreeProvider provides section tree navigation.

type WeightedPage 

type WeightedPage struct {
	Weight int
	Page
	// contains filtered or unexported fields
}

A WeightedPage is a Page with a weight.

type WeightedPages 

type WeightedPages []WeightedPage

WeightedPages is a list of Pages with their corresponding (and relative) weight [{Weight: 30, Page: *1}, {Weight: 40, Page: *2}]

func (WeightedPages) Page 

func (p WeightedPages) Page() Page

Page will return the Page (of Kind taxonomyList) that represents this set of pages. This method will panic if p is empty, as that should never happen.

func (WeightedPages) Pages 

func (wp WeightedPages) Pages() Pages

Pages returns the Pages in this weighted page set.

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.