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.
baseURL.go content.go content_renderer.go emoji.go general.go hugo.go language.go path.go pathspec.go pygments.go url.go
FilePathSeparator as defined by os.Separator.
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")
ErrWalkRootTooShort = errors.New("Path too short. Stop walking.")
)var CurrentHugoVersion = HugoVersion{ Number: 0.25, PatchLevel: 0, Suffix: "-DEV", }
CurrentHugoVersion represents the current build version. This should be the only one.
SummaryDivider denotes where content summarization should end. The default is "<!--more-->".
var SummaryLength = 70SummaryLength is the length of the summary that Hugo extracts from a content.
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.
BytesToHTML converts bytes to type template.HTML.
CompareVersion compares the given version string or number against the running Hugo version. It returns -1 if the given version is less than, 0 if equal and 1 if greater than the running version.
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.
DiffStringSlices returns the difference between two string slices. Useful in tests. See: http://stackoverflow.com/questions/19374219/how-to-find-the-difference-between-two-slices-of-strings-in-golang
DirExists checks if a path exists and is a directory.
Emojify "emojifies" the input source. Note that the input byte slice will be modified if needed. See http://www.emoji-cheat-sheet.com/
Exists checks if a file or directory exists.
Ext takes a path and returns the extension, including the delmiter, i.e. ".md".
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"
ExtractTOC extracts Table of Contents from content.
FileContains checks if a file contains a specified string.
FileContainsAny checks if a file contains any of the specified strings.
Filename takes a path, strips out the extension, and returns the name of the file.
FindAvailablePort returns an available and valid TCP port.
FindCWD returns the current working directory from where the Hugo executable is run.
FirstUpper returns a string with the first character as upper case.
GetDottedRelativePath expects a relative path starting after the content directory. It returns a relative path with dots ("..") navigating up the path structure.
GetRealPath returns the real file path for the given path, whether it is a symlink or not.
GetRelativePath returns the relative path of a given path.
GetTempDir returns a temporary directory with the given sub path.
GuessSection returns the section given a source path. A section is the part between the root slash and the second slash or before the first slash.
GuessType attempts to guess the type of file from a given string.
HasAsciidoc returns whether Asciidoctor or Asciidoc is installed on this computer.
HasPygments checks to see if Pygments is installed and available on the system.
HasRst returns whether rst2html is installed on this computer.
Highlight takes some code and returns highlighted code.
InStringArray checks if a string is an element of a slice of strings and returns a boolean value.
func InitLoggers()
InitLoggers sets up the global distinct loggers.
IsAbsURL determines whether the given path points to an absolute URL.
IsDir checks if a given path is a directory.
IsEmpty checks if a given path is empty.
IsWhitespace determines if the given rune is whitespace.
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
MakeTitle converts the path given to a suitable title, trimming whitespace and replacing hyphens with whitespace.
Md5String takes a string and returns its MD5 hash.
NormalizeHugoFlags facilitates transitions of Hugo command-line flags, e.g. --baseUrl to --baseURL, --uglyUrls to --uglyURLs
PathPrep prepares the path using the uglify setting to create paths on either the form /section/name/index.html or /section/name.html.
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
PrettifyURL takes a URL string and returns a semantic, clean URL.
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
ReaderContains reports whether subslice is within r.
ReaderToBytes takes an io.Reader argument, reads from it and returns bytes.
ReaderToString is the same as ReaderToBytes, but returns a string.
ReplaceExtension takes a path and an extension, strips the old extension and returns the path with the new extension.
SafeWriteToDisk is the same as WriteToDisk but it also checks to see if file/directory already exists.
SanitizeURL sanitizes the input URL string.
SanitizeURLKeepTrailingSlash is the same as SanitizeURL, but will keep any trailing slash.
SliceToLower goes through the source slice and lowers all values.
StripHTML accepts a string, strips out all HTML tags and returns it.
SymbolicWalk is like filepath.Walk, but it supports the root being a symbolic link. It will still not follow symbolic links deeper down in the file structure
ToLowerMap makes all the keys in the given map lower cased and will do so recursively. Notes: * This will modify the map given. * Any nested map[interface{}]interface{} will be converted to map[string]interface{}.
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)).
TruncateWordsByRune truncates words by runes.
TruncateWordsToWholeSentence takes content and truncates to whole sentence limited by max number of words. It also returns whether it is truncated.
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
UniqueStrings returns a new slice with any duplicates removed.
WriteToDisk writes content to disk.
type BaseURL struct {
// contains filtered or unexported fields
}A BaseURL in Hugo is normally on the form scheme://path, but the form scheme: is also valid (mailto:hugo@rules.com).
Protocol is normally on the form "scheme://", i.e. "webcal://".
type Blackfriday struct {
Smartypants bool
AngledQuotes bool
Fractions bool
HrefTargetBlank bool
SmartDashes bool
LatexDashes bool
TaskLists bool
PlainIDAnchors bool
SourceRelativeLinksEval bool
SourceRelativeLinksProjectFolder string
Extensions []string
ExtensionsMask []string
}Blackfriday holds configuration values for Blackfriday rendering.
type ContentSpec struct {
// contains filtered or unexported fields
}func NewContentSpec(cfg config.Provider) *ContentSpec
func (c ContentSpec) NewBlackfriday() *Blackfriday
NewBlackfriday creates a new Blackfriday filled with site config or some sane defaults.
func (c ContentSpec) RenderBytes(ctx *RenderingContext) []byte
RenderBytes renders a []byte.
DistinctLogger ignores duplicate log statements.
func NewDistinctErrorLogger() *DistinctLogger
NewDistinctErrorLogger creates a new DistinctLogger that logs ERRORs
func NewDistinctFeedbackLogger() *DistinctLogger
NewDistinctFeedbackLogger creates a new DistinctLogger that can be used to give feedback to the user while not spamming with duplicates.
func NewDistinctWarnLogger() *DistinctLogger
NewDistinctWarnLogger creates a new DistinctLogger that logs WARNs
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 (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.
type HugoHTMLRenderer struct {
*RenderingContext
blackfriday.Renderer
}HugoHTMLRenderer wraps a blackfriday.Renderer, typically a blackfriday.Html Enabling Hugo to customise the rendering experience
List adds task list support to the Blackfriday renderer.
ListItem adds task list support to the Blackfriday renderer.
HugoMmarkHTMLRenderer wraps a mmark.Renderer, typically a mmark.html Enabling Hugo to customise the rendering experience
func (r *HugoMmarkHTMLRenderer) BlockCode(out *bytes.Buffer, text []byte, lang string, caption []byte, subfigure bool, callouts bool)
type HugoVersion struct {
// Major and minor version.
Number float32
// Increment this for bug releases
PatchLevel int
// HugoVersionSuffix is the suffix used in the Hugo version string.
// It will be blank for release versions.
Suffix string
}HugoVersion represents the Hugo build version.
func (v HugoVersion) Next() HugoVersion
Next returns the next Hugo release version.
func (v HugoVersion) NextPatchLevel(level int) HugoVersion
NextPatchLevel returns the next patch/bugfix Hugo version. This will be a patch increment on the previous Hugo version.
func (v HugoVersion) Prev() HugoVersion
Pre returns the previous Hugo release version.
func (v HugoVersion) ReleaseVersion() HugoVersion
ReleaseVersion represents the release version.
func (v HugoVersion) String() string
type Language struct {
Lang string
LanguageName string
Title string
Weight int
Cfg config.Provider
// contains filtered or unexported fields
}Get returns a value associated with the key relying on specified language. Get is case-insensitive for a key.
Get returns an interface. For a specific value use one of the Get____ methods.
GetBool returns the value associated with the key as a boolean.
GetInt returns the value associated with the key as an int.
GetString returns the value associated with the key as a string.
GetStringMap returns the value associated with the key as a map of interfaces.
GetStringMapString returns the value associated with the key as a map of strings.
IsSet checks whether the key is set in the language or the related config store.
Set sets the value for the key in the language's params.
SetParam sets param with the given key and value. SetParam is case-insensitive.
type PathSpec struct {
BaseURL
// The file systems to use
Fs *hugofs.Fs
// The config provider to use
Cfg config.Provider
// contains filtered or unexported fields
}PathSpec holds methods that decides how paths in URLs and files in Hugo should look like.
NewPathSpec creats a new PathSpec from the given filesystems and Language.
AbsPathify creates an absolute path if given a relative path. If already absolute, the path is just cleaned.
AbsURL creates an absolute URL from the relative path given and the BaseURL set in config.
GetLayoutDirPath returns the absolute path to the layout file dir for the current Hugo project.
GetRelativeThemeDir gets the relative root directory of the current theme, if there is one. If there is no theme, returns the empty string.
GetStaticDirPath returns the absolute path to the static file dir for the current Hugo project.
GetThemeDataDirPath returns the theme's data dir path if theme is set. If theme is set and the data dir doesn't exist, an error is returned.
GetThemeDir gets the root directory of the current theme, if there is one. If there is no theme, returns the empty string.
GetThemeI18nDirPath returns the theme's i18n dir path if theme is set. If theme is set and the i18n dir doesn't exist, an error is returned.
GetThemeStaticDirPath returns the theme's static dir path if theme is set. If theme is set and the static dir doesn't exist, an error is returned.
GetThemesDirPath gets the static files directory of the current theme, if there is one. Ignores underlying errors. TODO(bep) Candidate for deprecation?
LayoutDir returns the relative layout dir in the currenct Hugo project.
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
MakePathSanitized creates a Unicode-sanitized string, with the spaces replaced
MakeStaticPathRelative makes a relative path to the static files directory. It does so by taking either the project's static path or the theme's static path into consideration.
PaginatePath returns the configured root path used for paginator pages.
PrependBasePath prepends any baseURL sub-folder to the given resource if canonifyURLs is disabled. If canonifyURLs is set, we will globally prepend the absURL with any sub-folder, so avoid doing anything here to avoid getting double paths.
RelURL creates a URL relative to the BaseURL root. Note: The result URL will not include the context root if canonifyURLs is enabled.
Theme returns the theme name if set.
ThemeSet checks whether a theme is in use or not.
URLEscape escapes unicode letters.
URLPrep applies misc sanitation to the given URL.
URLize is similar to MakePath, but with Unicode handling Example:
uri: Vim (text editor) urlize: vim-text-editor
URLizeAndPrep applies misc sanitation to the given URL to get it in line with the Hugo standard.
URLizeFilename creates an URL from a filename by esacaping unicode letters and turn any filepath separator into forward slashes.
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.
WorkingDir returns the configured workingDir.
type RenderingContext struct {
Content []byte
PageFmt string
DocumentID string
DocumentName string
Config *Blackfriday
RenderTOC bool
FileResolver FileResolverFunc
LinkResolver LinkResolverFunc
Cfg config.Provider
}RenderingContext holds contextual information, like content and configuration, for a given content rendering. By creating you must set the Config, otherwise it will panic.
Package helpers imports 37 packages (graph) and is imported by 24 packages. Updated 2017-06-21. Refresh now. Tools for package owners.