Version: v0.107.0 Latest Latest

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

Go to latest
Published: Nov 24, 2022 License: Apache-2.0 Imports: 43 Imported by: 642



Package helpers implements general utility functions that work with and on content. The helper functions defined here lay down the foundation of how Hugo works with files and filepaths, and perform string operations on content.



View Source
const FilePathSeparator = string(filepath.Separator)

FilePathSeparator as defined by os.Separator.


View Source
var (
	// DistinctErrorLog can be used to avoid spamming the logs with errors.
	DistinctErrorLog = NewDistinctErrorLogger()

	// DistinctWarnLog can be used to avoid spamming the logs with warnings.
	DistinctWarnLog = NewDistinctWarnLogger()


func AddTrailingSlash added in v0.71.1

func AddTrailingSlash(path string) string

AddTrailingSlash adds a trailing Unix styled slash (/) if not already there.

func BytesToHTML

func BytesToHTML(b []byte) template.HTML

BytesToHTML converts bytes to type template.HTML.

func Deprecated

func Deprecated(item, alternative string, err bool)

Deprecated informs about a deprecation, but only once for a given set of arguments' values. If the err flag is enabled, it logs as an ERROR (will exit with -1) and the text will point at the next Hugo release. The idea is two remove an item in two Hugo releases to give users and theme authors plenty of time to fix their templates.

func DirExists

func DirExists(path string, fs afero.Fs) (bool, error)

DirExists checks if a path exists and is a directory.

func Emoji added in v0.54.0

func Emoji(key string) []byte

Emoji returns the emojy given a key, e.g. ":smile:", nil if not found.

func Emojify

func Emojify(source []byte) []byte

Emojify "emojifies" the input source. Note that the input byte slice will be modified if needed. See

func Exists

func Exists(path string, fs afero.Fs) (bool, error)

Exists checks if a file or directory exists.

func ExtractRootPaths

func ExtractRootPaths(paths []string) []string

ExtractRootPaths extracts the root paths from the supplied list of paths. The resulting root path will not contain any file separators, but there may be duplicates. So "/content/section/" becomes "content"

func ExtractTOC

func ExtractTOC(content []byte) (newcontent []byte, toc []byte)

ExtractTOC extracts Table of Contents from content.

func FindAvailablePort

func FindAvailablePort() (*net.TCPAddr, error)

FindAvailablePort returns an available and valid TCP port.

func FindCWD

func FindCWD() (string, error)

FindCWD returns the current working directory from where the Hugo executable is run.

func FirstUpper

func FirstUpper(s string) string

FirstUpper returns a string with the first character as upper case.

func GetCacheDir added in v0.54.0

func GetCacheDir(fs afero.Fs, cfg config.Provider) (string, error)

GetCacheDir returns a cache dir from the given filesystem and config. The dir will be created if it does not exist.

func GetDottedRelativePath

func GetDottedRelativePath(inPath string) string

GetDottedRelativePath expects a relative path starting after the content directory. It returns a relative path with dots ("..") navigating up the path structure.

func GetTempDir

func GetTempDir(subPath string, fs afero.Fs) string

GetTempDir returns a temporary directory with the given sub path.

func GetTitleFunc added in v0.27.1

func GetTitleFunc(style string) func(s string) string

GetTitleFunc returns a func that can be used to transform a string to title case.

The supported styles are

- "Go" (strings.Title) - "AP" (see - "Chicago" (see

If an unknown or empty style is provided, AP style is what you get.

func HasStringsPrefix added in v0.25.1

func HasStringsPrefix(s, prefix []string) bool

HasStringsPrefix tests whether the string slice s begins with prefix slice s.

func HasStringsSuffix added in v0.25.1

func HasStringsSuffix(s, suffix []string) bool

HasStringsSuffix tests whether the string slice s ends with suffix slice s.

func HashString added in v0.61.0

func HashString(elements ...any) string

HashString returns a hash from the given elements. It will panic if the hash cannot be calculated.

func InStringArray

func InStringArray(arr []string, el string) bool

InStringArray checks if a string is an element of a slice of strings and returns a boolean value.

func InitLoggers

func InitLoggers()

InitLoggers resets the global distinct loggers.

func IsDir

func IsDir(path string, fs afero.Fs) (bool, error)

IsDir checks if a given path is a directory.

func IsEmpty

func IsEmpty(path string, fs afero.Fs) (bool, error)

IsEmpty checks if a given path is empty, meaning it doesn't contain any regular files.

func IsWhitespace

func IsWhitespace(r rune) bool

IsWhitespace determines if the given rune is whitespace.

func LstatIfPossible added in v0.38.1

func LstatIfPossible(fs afero.Fs, path string) (os.FileInfo, error)

LstatIfPossible can be used to call Lstat if possible, else Stat.

func MD5FromFileFast added in v0.32.1

func MD5FromFileFast(r io.ReadSeeker) (string, error)

MD5FromFileFast creates a MD5 hash from the given file. It only reads parts of the file for speed, so don't use it if the files are very subtly different. It will not close the file.

func MD5FromReader added in v0.54.0

func MD5FromReader(r io.Reader) (string, error)

MD5FromReader creates a MD5 hash from the given reader.

func MD5String added in v0.32.1

func MD5String(f string) string

MD5String takes a string and returns its MD5 hash.

func MakeTitle

func MakeTitle(inpath string) string

MakeTitle converts the path given to a suitable title, trimming whitespace and replacing hyphens with whitespace.

func NewDistinctErrorLogger

func NewDistinctErrorLogger() loggers.Logger

NewDistinctErrorLogger creates a new DistinctLogger that logs ERRORs

func NewDistinctLogger added in v0.42.1

func NewDistinctLogger(logger loggers.Logger) loggers.Logger

NewDistinctLogger creates a new DistinctLogger that logs to the provided logger.

func NewDistinctWarnLogger added in v0.20.1

func NewDistinctWarnLogger() loggers.Logger

NewDistinctWarnLogger creates a new DistinctLogger that logs WARNs

func NormalizeHugoFlags

func NormalizeHugoFlags(f *pflag.FlagSet, name string) pflag.NormalizedName

NormalizeHugoFlags facilitates transitions of Hugo command-line flags, e.g. --baseUrl to --baseURL, --uglyUrls to --uglyURLs

func OpenFileForWriting added in v0.47.1

func OpenFileForWriting(fs afero.Fs, filename string) (afero.File, error)

OpenFileForWriting opens or creates the given file. If the target directory does not exist, it gets created.

func OpenFilesForWriting added in v0.47.1

func OpenFilesForWriting(fs afero.Fs, filenames ...string) (io.WriteCloser, error)

OpenFilesForWriting opens all the given filenames for writing.

func PrintFs added in v0.42.1

func PrintFs(fs afero.Fs, path string, w io.Writer)

PrintFs prints the given filesystem to the given writer starting from the given path. This is useful for debugging.

func ProcessingStatsTable added in v0.32.1

func ProcessingStatsTable(w io.Writer, stats ...*ProcessingStats)

ProcessingStatsTable writes a table-formatted representation of stats to w.

func ReaderContains

func ReaderContains(r io.Reader, subslice []byte) bool

ReaderContains reports whether subslice is within r.

func ReaderToBytes

func ReaderToBytes(lines io.Reader) []byte

ReaderToBytes takes an io.Reader argument, reads from it and returns bytes.

func ReaderToString

func ReaderToString(lines io.Reader) string

ReaderToString is the same as ReaderToBytes, but returns a string.

func SafeWriteToDisk

func SafeWriteToDisk(inpath string, r io.Reader, fs afero.Fs) (err error)

SafeWriteToDisk is the same as WriteToDisk but it also checks to see if file/directory already exists.

func SanitizeURL

func SanitizeURL(in string) string

SanitizeURL sanitizes the input URL string.

func SanitizeURLKeepTrailingSlash

func SanitizeURLKeepTrailingSlash(in string) string

SanitizeURLKeepTrailingSlash is the same as SanitizeURL, but will keep any trailing slash.

func SliceToLower

func SliceToLower(s []string) []string

SliceToLower goes through the source slice and lowers all values.

func SymbolicWalk

func SymbolicWalk(fs afero.Fs, root string, walker hugofs.WalkFunc) error

SymbolicWalk is like filepath.Walk, but it follows symbolic links.

func TCPListen added in v0.96.0

func TCPListen() (net.Listener, *net.TCPAddr, error)

TCPListen starts listening on a valid TCP port.

func ToSlashTrimLeading added in v0.45.1

func ToSlashTrimLeading(s string) string

ToSlashTrimLeading is just a filepath.ToSlaas with an added / prefix trimmer.

func TotalWords

func TotalWords(s string) int

TotalWords counts instance of one or more consecutive white space characters, as defined by unicode.IsSpace, in s. This is a cheaper way of word counting than the obvious len(strings.Fields(s)).

func UniqueStrings

func UniqueStrings(s []string) []string

UniqueStrings returns a new slice with any duplicates removed.

func UniqueStringsReuse added in v0.56.0

func UniqueStringsReuse(s []string) []string

UniqueStringsReuse returns a slice with any duplicates removed. It will modify the input slice.

func UniqueStringsSorted added in v0.56.0

func UniqueStringsSorted(s []string) []string

UniqueStringsReuse returns a sorted slice with any duplicates removed. It will modify the input slice.

func WriteToDisk

func WriteToDisk(inpath string, r io.Reader, fs afero.Fs) (err error)

WriteToDisk writes content to disk.


type ContentSpec added in v0.20.1

type ContentSpec struct {
	Converters markup.ConverterProvider

	BuildFuture  bool
	BuildExpired bool
	BuildDrafts  bool

	Cfg config.Provider
	// contains filtered or unexported fields

ContentSpec provides functionality to render markdown content.

func NewContentSpec added in v0.20.1

func NewContentSpec(cfg config.Provider, logger loggers.Logger, contentFs afero.Fs, ex *hexec.Exec) (*ContentSpec, error)

NewContentSpec returns a ContentSpec initialized with the appropriate fields from the given config.Provider.

func (*ContentSpec) ResolveMarkup added in v0.60.0

func (c *ContentSpec) ResolveMarkup(in string) string

func (*ContentSpec) SanitizeAnchorName added in v0.62.2

func (c *ContentSpec) SanitizeAnchorName(s string) string

func (*ContentSpec) TrimShortHTML added in v0.55.0

func (c *ContentSpec) TrimShortHTML(input []byte) []byte

TrimShortHTML removes the <p>/</p> tags from HTML input in the situation where said tags are the only <p> tags in the input and enclose the content of the input (whitespace excluded).

func (*ContentSpec) TruncateWordsByRune added in v0.30.1

func (c *ContentSpec) TruncateWordsByRune(in []string) (string, bool)

TruncateWordsByRune truncates words by runes.

func (*ContentSpec) TruncateWordsToWholeSentence added in v0.30.1

func (c *ContentSpec) TruncateWordsToWholeSentence(s string) (string, bool)

TruncateWordsToWholeSentence takes content and truncates to whole sentence limited by max number of words. It also returns whether it is truncated.

type DistinctLogger

type DistinctLogger struct {
	// contains filtered or unexported fields

DistinctLogger ignores duplicate log statements.

func (*DistinctLogger) Debugf added in v0.84.0

func (l *DistinctLogger) Debugf(format string, v ...any)

func (*DistinctLogger) Debugln added in v0.84.0

func (l *DistinctLogger) Debugln(v ...any)

func (*DistinctLogger) Errorf added in v0.84.0

func (l *DistinctLogger) Errorf(format string, v ...any)

func (*DistinctLogger) Errorln added in v0.84.0

func (l *DistinctLogger) Errorln(v ...any)

func (*DistinctLogger) Infof added in v0.84.0

func (l *DistinctLogger) Infof(format string, v ...any)

func (*DistinctLogger) Infoln added in v0.84.0

func (l *DistinctLogger) Infoln(v ...any)

func (*DistinctLogger) Printf

func (l *DistinctLogger) Printf(format string, v ...any)

Printf will log the string returned from fmt.Sprintf given the arguments, but not if it has been logged before.

func (*DistinctLogger) Println

func (l *DistinctLogger) Println(v ...any)

Println will log the string returned from fmt.Sprintln given the arguments, but not if it has been logged before.

func (*DistinctLogger) Reset added in v0.59.0

func (l *DistinctLogger) Reset()

func (*DistinctLogger) Warnf added in v0.84.0

func (l *DistinctLogger) Warnf(format string, v ...any)

func (*DistinctLogger) Warnln added in v0.84.0

func (l *DistinctLogger) Warnln(v ...any)

type NamedSlice added in v0.56.0

type NamedSlice struct {
	Name  string
	Slice []string

func ExtractAndGroupRootPaths added in v0.56.0

func ExtractAndGroupRootPaths(paths []string) []NamedSlice

func (NamedSlice) String added in v0.56.0

func (n NamedSlice) String() string

type PathSpec

type PathSpec struct {

	ProcessingStats *ProcessingStats

	// The file systems to use
	Fs *hugofs.Fs

	// The config provider to use
	Cfg config.Provider

PathSpec holds methods that decides how paths in URLs and files in Hugo should look like.

func NewPathSpec added in v0.20.1

func NewPathSpec(fs *hugofs.Fs, cfg config.Provider, logger loggers.Logger) (*PathSpec, error)

NewPathSpec creates a new PathSpec from the given filesystems and language.

func NewPathSpecWithBaseBaseFsProvided added in v0.42.1

func NewPathSpecWithBaseBaseFsProvided(fs *hugofs.Fs, cfg config.Provider, logger loggers.Logger, baseBaseFs *filesystems.BaseFs) (*PathSpec, error)

NewPathSpecWithBaseBaseFsProvided creats a new PathSpec from the given filesystems and language. If an existing BaseFs is provided, parts of that is reused.

func (*PathSpec) AbsURL

func (p *PathSpec) AbsURL(in string, addLanguage bool) string

AbsURL creates an absolute URL from the relative path given and the BaseURL set in config.

func (*PathSpec) MakePath

func (p *PathSpec) MakePath(s string) string

MakePath takes a string with any characters and replace it so the string could be used in a path. It does so by creating a Unicode-sanitized string, with the spaces replaced, whilst preserving the original casing of the string. E.g. Social Media -> Social-Media

func (*PathSpec) MakePathSanitized

func (p *PathSpec) MakePathSanitized(s string) string

MakePathSanitized creates a Unicode-sanitized string, with the spaces replaced

func (*PathSpec) MakePathsSanitized added in v0.55.0

func (p *PathSpec) MakePathsSanitized(paths []string)

MakePathsSanitized applies MakePathSanitized on every item in the slice

func (*PathSpec) PermalinkForBaseURL added in v0.32.1

func (p *PathSpec) PermalinkForBaseURL(link, baseURL string) string

PermalinkForBaseURL creates a permalink from the given link and baseURL.

func (*PathSpec) PrependBasePath added in v0.20.1

func (p *PathSpec) PrependBasePath(rel string, isAbs bool) string

PrependBasePath prepends any baseURL sub-folder to the given resource

func (*PathSpec) RelURL

func (p *PathSpec) RelURL(in string, addLanguage bool) string

func (*PathSpec) URLEscape added in v0.20.1

func (p *PathSpec) URLEscape(uri string) string

URLEscape escapes unicode letters.

func (*PathSpec) URLPrep

func (p *PathSpec) URLPrep(in string) string

URLPrep applies misc sanitation to the given URL.

func (*PathSpec) URLize

func (p *PathSpec) URLize(uri string) string

URLize is similar to MakePath, but with Unicode handling Example:

uri: Vim (text editor)
urlize: vim-text-editor

func (*PathSpec) URLizeAndPrep

func (p *PathSpec) URLizeAndPrep(in string) string

URLizeAndPrep applies misc sanitation to the given URL to get it in line with the Hugo standard.

func (*PathSpec) URLizeFilename added in v0.20.1

func (p *PathSpec) URLizeFilename(filename string) string

URLizeFilename creates an URL from a filename by escaping unicode letters and turn any filepath separator into forward slashes.

func (*PathSpec) UnicodeSanitize

func (p *PathSpec) UnicodeSanitize(s string) string

UnicodeSanitize sanitizes string to be used in Hugo URL's, allowing only a predefined set of special Unicode characters. If RemovePathAccents configuration flag is enabled, Unicode accents are also removed. Hyphens in the original input are maintained. Spaces will be replaced with a single hyphen, and sequential replacement hyphens will be reduced to one.

type ProcessingStats added in v0.32.1

type ProcessingStats struct {
	Name string

	Pages           uint64
	PaginatorPages  uint64
	Static          uint64
	ProcessedImages uint64
	Files           uint64
	Aliases         uint64
	Sitemaps        uint64
	Cleaned         uint64

ProcessingStats represents statistics about a site build.

func NewProcessingStats added in v0.32.1

func NewProcessingStats(name string) *ProcessingStats

NewProcessingStats returns a new ProcessingStats instance.

func (*ProcessingStats) Add added in v0.32.1

func (s *ProcessingStats) Add(counter *uint64, amount int)

Add adds an amount to a given counter.

func (*ProcessingStats) Incr added in v0.32.1

func (s *ProcessingStats) Incr(counter *uint64)

Incr increments a given counter.

func (*ProcessingStats) Table added in v0.32.1

func (s *ProcessingStats) Table(w io.Writer)

Table writes a table-formatted representation of the stats in a ProcessingStats instance to w.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL