Documentation ¶
Overview ¶
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 ¶
- Constants
- Variables
- func AddContextRoot(baseURL, relativePath string) string
- func BytesToHTML(b []byte) template.HTML
- func CompareVersion(version interface{}) int
- func Deprecated(object, item, alternative string, err bool)
- func DiffStringSlices(slice1 []string, slice2 []string) []string
- func DirExists(path string, fs afero.Fs) (bool, error)
- func DoArithmetic(a, b interface{}, op rune) (interface{}, error)
- func Emojify(source []byte) []byte
- func Exists(path string, fs afero.Fs) (bool, error)
- func ExtractRootPaths(paths []string) []string
- func ExtractTOC(content []byte) (newcontent []byte, toc []byte)
- func FileContains(filename string, subslice []byte, fs afero.Fs) (bool, error)
- func FileContainsAny(filename string, subslices [][]byte, fs afero.Fs) (bool, error)
- func Filename(in string) (name string)
- func FindAvailablePort() (*net.TCPAddr, error)
- func FindCWD() (string, error)
- func FirstUpper(s string) string
- func GetDottedRelativePath(inPath string) string
- func GetRealPath(fs afero.Fs, path string) (string, error)
- func GetRelativePath(path, base string) (final string, err error)
- func GetTempDir(subPath string, fs afero.Fs) string
- func GuessSection(in string) string
- func GuessType(in string) string
- func HasAsciidoc() bool
- func HasPygments() bool
- func HasRst() bool
- func Highlight(cfg config.Provider, code, lang, optsStr string) string
- func HugoReleaseVersion() string
- func HugoVersion() string
- func InStringArray(arr []string, el string) bool
- func InitLoggers()
- func IsAbsURL(path string) bool
- func IsDir(path string, fs afero.Fs) (bool, error)
- func IsEmpty(path string, fs afero.Fs) (bool, error)
- func IsWhitespace(r rune) bool
- func MakePermalink(host, plink string) *url.URL
- func MakeTitle(inpath string) string
- func Md5String(f string) string
- func NextHugoReleaseVersion() string
- func NormalizeHugoFlags(f *pflag.FlagSet, name string) pflag.NormalizedName
- func PathPrep(ugly bool, in string) string
- func PrettifyPath(in string) string
- func PrettifyURL(in string) string
- func PrettifyURLPath(in string) string
- func ReaderContains(r io.Reader, subslice []byte) bool
- func ReaderToBytes(lines io.Reader) []byte
- func ReaderToString(lines io.Reader) string
- func ReplaceExtension(path string, newExt string) string
- func SafeWriteToDisk(inpath string, r io.Reader, fs afero.Fs) (err error)
- func SanitizeURL(in string) string
- func SanitizeURLKeepTrailingSlash(in string) string
- func Seq(args ...interface{}) ([]int, error)
- func SliceToLower(s []string) []string
- func StripHTML(s string) string
- func SymbolicWalk(fs afero.Fs, root string, walker filepath.WalkFunc) error
- func ToLowerMap(m map[string]interface{})
- func TotalWords(s string) int
- func TruncateWordsByRune(words []string, max int) (string, bool)
- func TruncateWordsToWholeSentence(s string, max int) (string, bool)
- func Uglify(in string) string
- func UniqueStrings(s []string) []string
- func WriteToDisk(inpath string, r io.Reader, fs afero.Fs) (err error)
- type BaseURL
- type Blackfriday
- type ContentSpec
- type DistinctLogger
- type FileResolverFunc
- type HugoHTMLRenderer
- func (r *HugoHTMLRenderer) BlockCode(out *bytes.Buffer, text []byte, lang string)
- func (r *HugoHTMLRenderer) Image(out *bytes.Buffer, link []byte, title []byte, alt []byte)
- func (r *HugoHTMLRenderer) Link(out *bytes.Buffer, link []byte, title []byte, content []byte)
- func (r *HugoHTMLRenderer) List(out *bytes.Buffer, text func() bool, flags int)
- func (r *HugoHTMLRenderer) ListItem(out *bytes.Buffer, text []byte, flags int)
- type HugoMmarkHTMLRenderer
- type Language
- func (l *Language) Get(key string) interface{}
- func (l *Language) GetBool(key string) bool
- func (l *Language) GetInt(key string) int
- func (l *Language) GetString(key string) string
- func (l *Language) GetStringMap(key string) map[string]interface{}
- func (l *Language) GetStringMapString(key string) map[string]string
- func (l *Language) IsSet(key string) bool
- func (l *Language) Params() map[string]interface{}
- func (l *Language) Set(key string, value interface{})
- func (l *Language) SetParam(k string, v interface{})
- func (l *Language) String() string
- type Languages
- type LinkResolverFunc
- type PathSpec
- func (p *PathSpec) AbsPathify(inPath string) string
- func (p *PathSpec) AbsURL(in string, addLanguage bool) string
- func (p *PathSpec) GetLayoutDirPath() string
- func (p *PathSpec) GetRelativeThemeDir() string
- func (p *PathSpec) GetStaticDirPath() string
- func (p *PathSpec) GetThemeDataDirPath() (string, error)
- func (p *PathSpec) GetThemeDir() string
- func (p *PathSpec) GetThemeI18nDirPath() (string, error)
- func (p *PathSpec) GetThemeStaticDirPath() (string, error)
- func (p *PathSpec) GetThemesDirPath() string
- func (p *PathSpec) LayoutDir() string
- func (p *PathSpec) MakePath(s string) string
- func (p *PathSpec) MakePathSanitized(s string) string
- func (p *PathSpec) MakeStaticPathRelative(inPath string) (string, error)
- func (p *PathSpec) PaginatePath() string
- func (p *PathSpec) PrependBasePath(rel string) string
- func (p *PathSpec) RelURL(in string, addLanguage bool) string
- func (p PathSpec) String() string
- func (p *PathSpec) Theme() string
- func (p *PathSpec) ThemeSet() bool
- func (p *PathSpec) URLEscape(uri string) string
- func (p *PathSpec) URLPrep(in string) string
- func (p *PathSpec) URLize(uri string) string
- func (p *PathSpec) URLizeAndPrep(in string) string
- func (p *PathSpec) URLizeFilename(filename string) string
- func (p *PathSpec) UnicodeSanitize(s string) string
- func (p *PathSpec) WorkingDir() string
- type RenderingContext
Constants ¶
const ( // Major and minor version. HugoVersionNumber = 0.20 // Increment this for bug releases HugoPatchVersion = 2 )
HugoVersionNumber represents the current build version. This should be the only one
const FilePathSeparator = string(filepath.Separator)
FilePathSeparator as defined by os.Separator.
const HugoVersionSuffix = "" // use this line when doing a release
HugoVersionSuffix is the suffix used in the Hugo version string. It will be blank for release versions. const HugoVersionSuffix = "-DEV" // use this when not doing a release
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") ErrWalkRootTooShort = errors.New("Path too short. Stop walking.") )
var SummaryDivider = []byte("<!--more-->")
SummaryDivider denotes where content summarization should end. The default is "<!--more-->".
var SummaryLength = 70
SummaryLength is the length of the summary that Hugo extracts from a content.
Functions ¶
func AddContextRoot ¶
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 BytesToHTML ¶
BytesToHTML converts bytes to type template.HTML.
func CompareVersion ¶ added in v0.20.1
func CompareVersion(version interface{}) int
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.
func Deprecated ¶
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 DiffStringSlices ¶
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
func DoArithmetic ¶
DoArithmetic performs arithmetic operations (+,-,*,/) using reflection to determine the type of the two terms.
func Emojify ¶
Emojify "emojifies" the input source. Note that the input byte slice will be modified if needed. See http://www.emoji-cheat-sheet.com/
func ExtractRootPaths ¶
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 ¶
ExtractTOC extracts Table of Contents from content.
func FileContains ¶
FileContains checks if a file contains a specified string.
func FileContainsAny ¶
FileContainsAny checks if a file contains any of the specified strings.
func FindAvailablePort ¶
FindAvailablePort returns an available and valid TCP port.
func FirstUpper ¶
FirstUpper returns a string with the first character as upper case.
func GetDottedRelativePath ¶
GetDottedRelativePath expects a relative path starting after the content directory. It returns a relative path with dots ("..") navigating up the path structure.
func GetRealPath ¶
GetRealPath returns the real file path for the given path, whether it is a symlink or not.
func GetRelativePath ¶
GetRelativePath returns the relative path of a given path.
func GetTempDir ¶
GetTempDir returns a temporary directory with the given sub path.
func GuessSection ¶
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.
func HasAsciidoc ¶
func HasAsciidoc() bool
HasAsciidoc returns whether Asciidoctor or Asciidoc is installed on this computer.
func HasPygments ¶
func HasPygments() bool
HasPygments checks to see if Pygments is installed and available on the system.
func HugoReleaseVersion ¶
func HugoReleaseVersion() string
HugoReleaseVersion is same as HugoVersion, but no suffix.
func HugoVersion ¶
func HugoVersion() string
HugoVersion returns the current Hugo version. It will include a suffix, typically '-DEV', if it's development version.
func InStringArray ¶
InStringArray checks if a string is an element of a slice of strings and returns a boolean value.
func IsWhitespace ¶
IsWhitespace determines if the given rune is whitespace.
func MakePermalink ¶
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 ¶
MakeTitle converts the path given to a suitable title, trimming whitespace and replacing hyphens with whitespace.
func NextHugoReleaseVersion ¶
func NextHugoReleaseVersion() string
NextHugoReleaseVersion returns the next Hugo release version.
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 PathPrep ¶
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 ¶
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 ¶
PrettifyURL takes a URL string and returns a semantic, clean URL.
func PrettifyURLPath ¶
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 ReaderContains ¶
ReaderContains reports whether subslice is within r.
func ReaderToBytes ¶
ReaderToBytes takes an io.Reader argument, reads from it and returns bytes.
func ReaderToString ¶
ReaderToString is the same as ReaderToBytes, but returns a string.
func ReplaceExtension ¶
ReplaceExtension takes a path and an extension, strips the old extension and returns the path with the new extension.
func SafeWriteToDisk ¶
SafeWriteToDisk is the same as WriteToDisk but it also checks to see if file/directory already exists.
func SanitizeURLKeepTrailingSlash ¶
SanitizeURLKeepTrailingSlash is the same as SanitizeURL, but will keep any trailing slash.
func Seq ¶
Seq creates a sequence of integers. It's named and used as GNU's seq. Examples: 3 => 1, 2, 3 1 2 4 => 1, 3 -3 => -1, -2, -3 1 4 => 1, 2, 3, 4 1 -2 => 1, 0, -1, -2
func SliceToLower ¶
SliceToLower goes through the source slice and lowers all values.
func SymbolicWalk ¶
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
func ToLowerMap ¶
func ToLowerMap(m map[string]interface{})
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{}.
func TotalWords ¶
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 TruncateWordsByRune ¶
TruncateWordsByRune truncates words by runes.
func TruncateWordsToWholeSentence ¶
TruncateWordsToWholeSentence takes content and truncates to whole sentence limited by max number of words. It also returns whether it is truncated.
func Uglify ¶
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 ¶
UniqueStrings returns a new slice with any duplicates removed.
Types ¶
type BaseURL ¶ added in v0.20.1
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).
type Blackfriday ¶
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 ¶ added in v0.20.1
type ContentSpec struct {
// contains filtered or unexported fields
}
func NewContentSpec ¶ added in v0.20.1
func NewContentSpec(cfg config.Provider) *ContentSpec
func (ContentSpec) NewBlackfriday ¶ added in v0.20.1
func (c ContentSpec) NewBlackfriday() *Blackfriday
NewBlackfriday creates a new Blackfriday filled with site config or some sane defaults.
func (ContentSpec) RenderBytes ¶ added in v0.20.1
func (c ContentSpec) RenderBytes(ctx *RenderingContext) []byte
RenderBytes renders a []byte.
type DistinctLogger ¶
DistinctLogger ignores duplicate log statements.
func NewDistinctErrorLogger ¶
func NewDistinctErrorLogger() *DistinctLogger
NewDistinctErrorLogger creates a new DistinctLogger that logs ERRORs
func NewDistinctFeedbackLogger ¶
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 ¶ added in v0.20.1
func NewDistinctWarnLogger() *DistinctLogger
NewDistinctWarnLogger creates a new DistinctLogger that logs WARNs
func (*DistinctLogger) Printf ¶
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 ¶
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 FileResolverFunc ¶
type HugoHTMLRenderer ¶
type HugoHTMLRenderer struct { *RenderingContext blackfriday.Renderer }
HugoHTMLRenderer wraps a blackfriday.Renderer, typically a blackfriday.Html Enabling Hugo to customise the rendering experience
func (*HugoHTMLRenderer) BlockCode ¶
func (r *HugoHTMLRenderer) BlockCode(out *bytes.Buffer, text []byte, lang string)
type HugoMmarkHTMLRenderer ¶
HugoMmarkHTMLRenderer wraps a mmark.Renderer, typically a mmark.html Enabling Hugo to customise the rendering experience
type Language ¶
type Language struct { Lang string LanguageName string Title string Weight int Cfg config.Provider // contains filtered or unexported fields }
func NewDefaultLanguage ¶
func (*Language) Get ¶
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.
func (*Language) GetStringMap ¶
GetStringMap returns the value associated with the key as a map of interfaces.
func (*Language) GetStringMapString ¶
GetStringMapString returns the value associated with the key as a map of strings.
func (*Language) IsSet ¶ added in v0.20.1
IsSet checks whether the key is set in the language or the related config store.
type LinkResolverFunc ¶
type PathSpec ¶
type PathSpec struct { BaseURL // contains filtered or unexported fields }
PathSpec holds methods that decides how paths in URLs and files in Hugo should look like.
func NewPathSpec ¶ added in v0.20.1
NewPathSpec creats a new PathSpec from the given filesystems and Language.
func (*PathSpec) AbsPathify ¶ added in v0.20.1
AbsPathify creates an absolute path if given a relative path. If already absolute, the path is just cleaned.
func (*PathSpec) AbsURL ¶
AbsURL creates an absolute URL from the relative path given and the BaseURL set in config.
func (*PathSpec) GetLayoutDirPath ¶ added in v0.20.1
GetLayoutDirPath returns the absolute path to the layout file dir for the current Hugo project.
func (*PathSpec) GetRelativeThemeDir ¶ added in v0.20.1
GetRelativeThemeDir gets the relative root directory of the current theme, if there is one. If there is no theme, returns the empty string.
func (*PathSpec) GetStaticDirPath ¶ added in v0.20.1
GetStaticDirPath returns the absolute path to the static file dir for the current Hugo project.
func (*PathSpec) GetThemeDataDirPath ¶ added in v0.20.1
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.
func (*PathSpec) GetThemeDir ¶ added in v0.20.1
GetThemeDir gets the root directory of the current theme, if there is one. If there is no theme, returns the empty string.
func (*PathSpec) GetThemeI18nDirPath ¶ added in v0.20.1
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.
func (*PathSpec) GetThemeStaticDirPath ¶ added in v0.20.1
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.
func (*PathSpec) GetThemesDirPath ¶ added in v0.20.1
GetThemesDirPath gets the static files directory of the current theme, if there is one. Ignores underlying errors. TODO(bep) Candidate for deprecation?
func (*PathSpec) LayoutDir ¶ added in v0.20.1
LayoutDir returns the relative layout dir in the currenct Hugo project.
func (*PathSpec) MakePath ¶
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 ¶
MakePathSanitized creates a Unicode-sanitized string, with the spaces replaced
func (*PathSpec) MakeStaticPathRelative ¶ added in v0.20.1
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.
func (*PathSpec) PaginatePath ¶
PaginatePath returns the configured root path used for paginator pages.
func (*PathSpec) PrependBasePath ¶ added in v0.20.1
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.
func (*PathSpec) RelURL ¶
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) URLize ¶
URLize is similar to MakePath, but with Unicode handling Example:
uri: Vim (text editor) urlize: vim-text-editor
func (*PathSpec) URLizeAndPrep ¶
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
URLizeFilename creates an URL from a filename by esacaping unicode letters and turn any filepath separator into forward slashes.
func (*PathSpec) UnicodeSanitize ¶
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.
func (*PathSpec) WorkingDir ¶ added in v0.20.1
WorkingDir returns the configured workingDir.
type RenderingContext ¶
type RenderingContext struct { Content []byte PageFmt string DocumentID string DocumentName string Config *Blackfriday RenderTOC bool FileResolver FileResolverFunc LinkResolver LinkResolverFunc Cfg config.Provider // contains filtered or unexported fields }
RenderingContext holds contextual information, like content and configuration, for a given content rendering.