hugo: github.com/gohugoio/hugo/helpers Index | Files

package helpers

import "github.com/gohugoio/hugo/helpers"

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.

Index

Package Files

content.go docshelper.go emoji.go general.go path.go pathspec.go processing_stats.go url.go

Constants

❖
const FilePathSeparator = string(filepath.Separator)

FilePathSeparator as defined by os.Separator.

Variables

❖
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()

    // DistinctFeedbackLog can be used to avoid spamming the logs with info messages.
    DistinctFeedbackLog = NewDistinctFeedbackLogger()
)
❖
var (
    // ErrThemeUndefined is returned when a theme has not be defined by the user.
    ErrThemeUndefined = errors.New("no theme set")
)
❖
var SummaryDivider = []byte("<!--more-->")

SummaryDivider denotes where content summarization should end. The default is "<!--more-->".

func AddContextRoot Uses

❖
func AddContextRoot(baseURL, relativePath string) string

AddContextRoot adds the context root to an URL if it's not already set. For relative URL entries on sites with a base url with a context root set (i.e. http://example.com/mysite), relative URLs must not include the context root if canonifyURLs is enabled. But if it's disabled, it must be set.

func AddTrailingSlash Uses

❖
func AddTrailingSlash(path string) string

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

func BytesToHTML Uses

❖
func BytesToHTML(b []byte) template.HTML

BytesToHTML converts bytes to type template.HTML.

func Deprecated Uses

❖
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 Uses

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

DirExists checks if a path exists and is a directory.

func Emoji Uses

❖
func Emoji(key string) []byte

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

func Emojify Uses

❖
func Emojify(source []byte) []byte

Emojify "emojifies" the input source. Note that the input byte slice will be modified if needed. See http://www.emoji-cheat-sheet.com/

func Exists Uses

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

Exists checks if a file or directory exists.

func Ext Uses

❖
func Ext(in string) string

Ext takes a path and returns the extension, including the delmiter, i.e. ".md".

func ExtNoDelimiter Uses

❖
func ExtNoDelimiter(in string) string

ExtNoDelimiter takes a path and returns the extension, excluding the delmiter, i.e. "md".

func ExtractRootPaths Uses

❖
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 Uses

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

ExtractTOC extracts Table of Contents from content.

func FileAndExt Uses

❖
func FileAndExt(in string) (string, string)

FileAndExt takes a path and returns the file and extension separated, the extension including the delmiter, i.e. ".md".

func FileAndExtNoDelimiter Uses

❖
func FileAndExtNoDelimiter(in string) (string, string)

FileAndExtNoDelimiter takes a path and returns the file and extension separated, the extension excluding the delmiter, e.g "md".

func FileContains Uses

❖
func FileContains(filename string, subslice []byte, fs afero.Fs) (bool, error)

FileContains checks if a file contains a specified string.

func FileContainsAny Uses

❖
func FileContainsAny(filename string, subslices [][]byte, fs afero.Fs) (bool, error)

FileContainsAny checks if a file contains any of the specified strings.

func Filename Uses

❖
func Filename(in string) (name string)

Filename takes a file path, strips out the extension, and returns the name of the file.

func FindAvailablePort Uses

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

FindAvailablePort returns an available and valid TCP port.

func FindCWD Uses

❖
func FindCWD() (string, error)

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

func FirstUpper Uses

❖
func FirstUpper(s string) string

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

func GetCacheDir Uses

❖
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 Uses

❖
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 GetRelativePath Uses

❖
func GetRelativePath(path, base string) (final string, err error)

GetRelativePath returns the relative path of a given path.

func GetTempDir Uses

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

GetTempDir returns a temporary directory with the given sub path.

func GetTitleFunc Uses

❖
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 https://www.apstylebook.com/) - "Chicago" (see http://www.chicagomanualofstyle.org/home.html)

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

func HasStringsPrefix Uses

❖
func HasStringsPrefix(s, prefix []string) bool

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

func HasStringsSuffix Uses

❖
func HasStringsSuffix(s, suffix []string) bool

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

func HashString Uses

❖
func HashString(elements ...interface{}) string

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

func InStringArray Uses

❖
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 Uses

❖
func InitLoggers()

InitLoggers resets the global distinct loggers.

func IsAbsURL Uses

❖
func IsAbsURL(path string) bool

IsAbsURL determines whether the given path points to an absolute URL.

func IsDir Uses

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

IsDir checks if a given path is a directory.

func IsEmpty Uses

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

IsEmpty checks if a given path is empty.

func IsWhitespace Uses

❖
func IsWhitespace(r rune) bool

IsWhitespace determines if the given rune is whitespace.

func LstatIfPossible Uses

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

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

func MD5FromFileFast Uses

❖
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 Uses

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

MD5FromReader creates a MD5 hash from the given reader.

func MD5String Uses

❖
func MD5String(f string) string

MD5String takes a string and returns its MD5 hash.

❖
func MakePermalink(host, plink string) *url.URL

MakePermalink combines base URL with content path to create full URL paths. Example 

base:   http://spf13.com/
path:   post/how-i-blog
result: http://spf13.com/post/how-i-blog

func MakeTitle Uses

❖
func MakeTitle(inpath string) string

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

func NormalizeHugoFlags Uses

❖
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 Uses

❖
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 Uses

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

OpenFilesForWriting opens all the given filenames for writing.

func PathAndExt Uses

❖
func PathAndExt(in string) (string, string)

PathAndExt is the same as FileAndExt, but it uses the path package.

func PathNoExt Uses

❖
func PathNoExt(in string) string

PathNoExt takes a path, strips out the extension, and returns the name of the file.

func PathPrep Uses

❖
func PathPrep(ugly bool, in string) string

PathPrep prepares the path using the uglify setting to create paths on either the form /section/name/index.html or /section/name.html.

func PrettifyPath Uses

❖
func PrettifyPath(in string) string

PrettifyPath is the same as PrettifyURLPath but for file paths. 

/section/name.html       becomes /section/name/index.html
/section/name/           becomes /section/name/index.html
/section/name/index.html becomes /section/name/index.html

func PrettifyURL Uses

❖
func PrettifyURL(in string) string

PrettifyURL takes a URL string and returns a semantic, clean URL.

func PrettifyURLPath Uses

❖
func PrettifyURLPath(in string) string

PrettifyURLPath takes a URL path to a content and converts it to enable pretty URLs. 

/section/name.html       becomes /section/name/index.html
/section/name/           becomes /section/name/index.html
/section/name/index.html becomes /section/name/index.html

func PrintFs Uses

❖
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 Uses

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

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

func ReaderContains Uses

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

ReaderContains reports whether subslice is within r.

func ReaderToBytes Uses

❖
func ReaderToBytes(lines io.Reader) []byte

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

func ReaderToString Uses

❖
func ReaderToString(lines io.Reader) string

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

func ReplaceExtension Uses

❖
func ReplaceExtension(path string, newExt string) string

ReplaceExtension takes a path and an extension, strips the old extension and returns the path with the new extension.

func SafeWriteToDisk Uses

❖
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 Uses

❖
func SanitizeURL(in string) string

SanitizeURL sanitizes the input URL string.

func SanitizeURLKeepTrailingSlash Uses

❖
func SanitizeURLKeepTrailingSlash(in string) string

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

func SliceToLower Uses

❖
func SliceToLower(s []string) []string

SliceToLower goes through the source slice and lowers all values.

func StripHTML Uses

❖
func StripHTML(s string) string

StripHTML accepts a string, strips out all HTML tags and returns it.

func SymbolicWalk Uses

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

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

func ToSlashTrimLeading Uses

❖
func ToSlashTrimLeading(s string) string

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

func TotalWords Uses

❖
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 Uglify Uses

❖
func Uglify(in string) string

Uglify does the opposite of PrettifyURLPath(). 

/section/name/index.html becomes /section/name.html
/section/name/           becomes /section/name.html
/section/name.html       becomes /section/name.html

func UniqueStrings Uses

❖
func UniqueStrings(s []string) []string

UniqueStrings returns a new slice with any duplicates removed.

func UniqueStringsReuse Uses

❖
func UniqueStringsReuse(s []string) []string

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

func UniqueStringsSorted Uses

❖
func UniqueStringsSorted(s []string) []string

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

func WriteToDisk Uses

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

WriteToDisk writes content to disk.

type ContentSpec Uses

❖
type ContentSpec struct {
    Converters       markup.ConverterProvider
    MardownConverter converter.Converter // Markdown converter with no document context

    BuildFuture  bool
    BuildExpired bool
    BuildDrafts  bool

    Cfg config.Provider
    // contains filtered or unexported fields
}

ContentSpec provides functionality to render markdown content.

func NewContentSpec Uses

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

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

func (*ContentSpec) RenderMarkdown Uses

❖
func (c *ContentSpec) RenderMarkdown(src []byte) ([]byte, error)

func (*ContentSpec) ResolveMarkup Uses

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

func (*ContentSpec) SanitizeAnchorName Uses

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

func (*ContentSpec) TrimShortHTML Uses

❖
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 Uses

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

TruncateWordsByRune truncates words by runes.

func (*ContentSpec) TruncateWordsToWholeSentence Uses

❖
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 Uses

❖
type DistinctLogger struct {
    sync.RWMutex
    // contains filtered or unexported fields
}

DistinctLogger ignores duplicate log statements.

func NewDistinctErrorLogger Uses

❖
func NewDistinctErrorLogger() *DistinctLogger

NewDistinctErrorLogger creates a new DistinctLogger that logs ERRORs

func NewDistinctFeedbackLogger Uses

❖
func NewDistinctFeedbackLogger() *DistinctLogger

NewDistinctFeedbackLogger creates a new DistinctLogger that can be used to give feedback to the user while not spamming with duplicates.

func NewDistinctLogger Uses

❖
func NewDistinctLogger(logger LogPrinter) *DistinctLogger

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

func NewDistinctWarnLogger Uses

❖
func NewDistinctWarnLogger() *DistinctLogger

NewDistinctWarnLogger creates a new DistinctLogger that logs WARNs

func (*DistinctLogger) Printf Uses

❖
func (l *DistinctLogger) Printf(format string, v ...interface{})

Printf will log the string returned from fmt.Sprintf given the arguments, but not if it has been logged before. Note: A newline is appended.

func (*DistinctLogger) Println Uses

❖
func (l *DistinctLogger) Println(v ...interface{})

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

func (*DistinctLogger) Reset Uses

❖
func (l *DistinctLogger) Reset()

type LogPrinter Uses

❖
type LogPrinter interface {
    // Println is the only common method that works in all of JWWs loggers.
    Println(a ...interface{})
}

LogPrinter is the common interface of the JWWs loggers.

type NamedSlice Uses

❖
type NamedSlice struct {
    Name  string
    Slice []string
}

func ExtractAndGroupRootPaths Uses

❖
func ExtractAndGroupRootPaths(paths []string) []NamedSlice

func (NamedSlice) String Uses

❖
func (n NamedSlice) String() string

type PathSpec Uses

❖
type PathSpec struct {
    *paths.Paths
    *filesystems.BaseFs

    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 Uses

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

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

func NewPathSpecWithBaseBaseFsProvided Uses

❖
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 Uses

❖
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 Uses

❖
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 Uses

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

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

func (*PathSpec) MakePathsSanitized Uses

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

MakePathsSanitized applies MakePathSanitized on every item in the slice

func (*PathSpec) PermalinkForBaseURL Uses

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

PermalinkForBaseURL creates a permalink from the given link and baseURL.

func (*PathSpec) PrependBasePath Uses

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

PrependBasePath prepends any baseURL sub-folder to the given resource

func (*PathSpec) RelURL Uses

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

RelURL creates a URL relative to the BaseURL root. Note: The result URL will not include the context root if canonifyURLs is enabled.

func (*PathSpec) URLEscape Uses

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

URLEscape escapes unicode letters.

func (*PathSpec) URLPrep Uses

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

URLPrep applies misc sanitation to the given URL.

func (*PathSpec) URLize Uses

❖
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 Uses

❖
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 Uses

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

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

func (*PathSpec) UnicodeSanitize Uses

❖
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, Uniccode accents are also removed. Spaces will be replaced with a single hyphen, and sequential hyphens will be reduced to one.

type ProcessingStats Uses

❖
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 Uses

❖
func NewProcessingStats(name string) *ProcessingStats

NewProcessingStats returns a new ProcessingStats instance.

func (*ProcessingStats) Add Uses

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

Add adds an amount to a given counter.

func (*ProcessingStats) Incr Uses

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

Incr increments a given counter.

func (*ProcessingStats) Table Uses

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

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

Package helpers imports 42 packages (graph) and is imported by 870 packages. Updated 2020-06-25. Refresh now. Tools for package owners.