JSDoc: Module: utils

Source:

utils.js, line 1

Members

(inner, constant) default404 :String

Hikaru's default 404 page content for server.

Type:

String

Source:

utils.js, line 1287

(inner, constant) hikaruDir

Hikaru's package dir.

Source:

utils.js, line 19

(inner, constant) isBinaryFileSync

You should use isBinaryPath(p) mostly. This is only for compatibility because isbinaryfile dependency is dropped.

Deprecated:

Source:

utils.js, line 194

(inner, constant) resolveHeaderIDs

Use resolveHeadingIDs(node) instead.

Deprecated:

Source:

utils.js, line 1095

Methods

(inner) checkType(var, name, …types)

Check whether a variable is one of give types.

Parameters:

Name	Type	Attributes	Description
`var`	*
`name`	String		Variable name.
`types`	String	<repeatable>

Source:

utils.js, line 130

(inner) delSite(site, key, file)

Delete file from an array in site which have the same source.

Parameters:

Name	Type	Description
`site`	Site
`key`	String
`file`	File

Source:

utils.js, line 843

(inner) escapeHTML(str) → {String}

Escape HTML chars.

Parameters:

Name	Type	Description
`str`	String

Source:

utils.js, line 218

Returns:

Escaped HTML string.

Type: String

(inner) fallbackSort(arr, …fns)

Sort an array with a fallback list, call comparing function from first to last until there is a difference.

Parameters:

Name	Type	Attributes	Description
`arr`	Array
`fns`	compareCallback	<repeatable>

Source:

utils.js, line 248

(inner) formatDateTimeFn(locales) → {formatDateTime}

Get a function to format date and time, with locale support if Intl is available.

Parameters:

Name	Type	Description
`locales`	String

Source:

utils.js, line 709

See:

Returns:

Type: formatDateTime

(inner) formatDateTimeSimple(dtopt) → {String}

Format date and time to YYYY-MM-DD HH:mm:ss.

Parameters:

Name	Type	Attributes	Default	Description
`dt`	*	<optional>	new Date()

Source:

utils.js, line 681

Returns:

Type: String

(inner) genCategories(posts) → {CategoriesData}

Generate categories from posts.

Parameters:

Name	Type	Description
`posts`	Array.<File>

Source:

utils.js, line 747

Returns:

Type: CategoriesData

(inner) genTOC(node, optsopt)

Generate TOC from HTML headings.

Parameters:

Name	Type	Attributes	Description
`node`	Object		parse5 Node.
`opts`	Object	<optional>

Source:

utils.js, line 1102

(inner) genTags(posts) → {TagsData}

Generate tags from posts.

Parameters:

Name	Type	Description
`posts`	Array.<File>

Source:

utils.js, line 786

Returns:

Type: TagsData

(inner) getContentType(docPath) → {String}

Detect Content-Type via filename.

Parameters:

Name	Type	Description
`docPath`	String

Source:

utils.js, line 414

Returns:

Content-Type value.

Type: String

(inner) getFrontMatter(str) → {FrontMatter}

Get front-matter from string, front-matter here should be at the beginning of string (so UTF-8 BOM is not supported), and should begin with --- in the first line, and should have valid YAML in lines after that, and should end with --- in the next line.

Parameters:

Name	Type	Description
`str`	String

Source:

utils.js, line 336

Returns:

Type: FrontMatter

(inner) getFullDocPath(file) → {String}

Get File's full document path.

Parameters:

Name	Type	Description
`file`	File

Source:

utils.js, line 878

Returns:

Type: String

(inner) getFullSrcPath(file) → {String}

Get File's full src path.

Parameters:

Name	Type	Description
`file`	File

Source:

utils.js, line 866

Returns:

Type: String

(inner) getNodeAttr(node, attrName) → {String}

Get an attribute value from parse5 Node.

Parameters:

Name	Type	Description
`node`	Object	parse5 Node.
`attrName`	String

Source:

utils.js, line 1024

See:

Returns:

Value of the attribute, null if not available.

Type: String

(inner) getNodeText(node) → {String}

Get text content of a parse5 Node.

Parameters:

Name	Type	Description
`node`	Object	parse5 Node.

Source:

utils.js, line 986

See:

Returns:

Type: String

(inner) getPathFn(rootDiropt) → {getPath}

Get a function to handle full website path.

Parameters:

Name	Type	Attributes	Description
`rootDir`	String	<optional>	Site rootDir.

Source:

utils.js, line 507

Returns:

Type: getPath

(inner) getURLFn(baseURLopt, rootDiropt) → {getURL}

Get a function to handle full website URL.

Parameters:

Name	Type	Attributes	Description
`baseURL`	String	<optional>	Site baseURL.
`rootDir`	String	<optional>	Site rootDir.

Source:

utils.js, line 550

Returns:

Type: getURL

(inner) getURLProtocol(url) → {String}

Get protocol of a URL.

Parameters:

Name	Type	Description
`url`	String

Source:

utils.js, line 1134

Returns:

If no protocol return null.

Type: String

(inner) getVersion() → {String}

Get Hikaru version.

Source:

utils.js, line 1279

Returns:

Type: String

(inner) isArray(o) → {Boolean}

Parameters:

Name	Type	Description
`o`	*

Source:

utils.js, line 82

Returns:

Type: Boolean

(inner) isBinary(b) → {Boolean}

Check whether a buffer is a binary. You should use isBinaryPath(p) because this is costly and mostly a false positive is harmless so we don't need an exact check. For non-costly exact check, add isbinaryfile dependency for your project.

Parameters:

Name	Type	Description
`b`	Buffer

Source:

utils.js, line 158

Returns:

Type: Boolean

(inner) isBinaryFile(o) → {Boolean}

You should use isBinaryPath(p) mostly. This is only for compatibility because isbinaryfile dependency is dropped.

Parameters:

Name	Type	Description
`o`	String \| Buffer

Deprecated:

Source:

utils.js, line 183

Returns:

Type: Boolean

(inner) isBinaryPath(p) → {Boolean}

Check whether a path is a binary via ext name. For non-costly exact check, add isbinaryfile dependency for your project.

Parameters:

Name	Type	Description
`p`	String

Source:

utils.js, line 172

Returns:

Type: Boolean

(inner) isBuffer(o) → {Boolean}

Parameters:

Name	Type	Description
`o`	*

Source:

utils.js, line 106

Returns:

Type: Boolean

(inner) isCurrentHostFn(baseURL, rootDiropt) → {isCurrentHost}

Get a function to handle if parameter is on current host.

Parameters:

Name	Type	Attributes	Description
`baseURL`	String		Site baseURL.
`rootDir`	String	<optional>	Site rootDir.

Source:

utils.js, line 570

Returns:

Type: isCurrentHost

(inner) isCurrentPathFn(rootDiropt, currentPathopt) → {isCurrentPath}

Get a function to handle if parameter is current path.

Parameters:

Name	Type	Attributes	Description
`rootDir`	String	<optional>	Site rootDir.
`currentPath`	String	<optional>	current page's path.

Source:

utils.js, line 598

Returns:

Type: isCurrentPath

(inner) isFunction(o) → {Boolean}

Parameters:

Name	Type	Description
`o`	*

Source:

utils.js, line 90

Returns:

Type: Boolean

(inner) isNumber(o) → {Boolean}

Parameters:

Name	Type	Description
`o`	*

Source:

utils.js, line 66

Returns:

Type: Boolean

(inner) isObject(o) → {Boolean}

Parameters:

Name	Type	Description
`o`	*

Source:

utils.js, line 98

Returns:

Return false when o == null.

Type: Boolean

(inner) isReadableSync(p) → {Boolean}

Node.js marks fs.exists() deprecated and suggest to use fs.access(), but it throws error instead of return a boolean, this is a wrapper for it.

Parameters:

Name	Type	Description
`p`	String

Source:

utils.js, line 204

See:

https://nodejs.org/api/fs.html#fsaccesssyncpath-mode

Returns:

Type: Boolean

(inner) isString(o) → {Boolean}

Parameters:

Name	Type	Description
`o`	*

Source:

utils.js, line 74

Returns:

Type: Boolean

(async, inner) loadJSON(path) → {Promise.<Object>}

Parameters:

Name	Type	Description
`path`	String

Source:

utils.js, line 28

Returns:

Type: Promise.<Object>

(inner) loadJSONSync(path) → {Object}

Parameters:

Name	Type	Description
`path`	String

Source:

utils.js, line 36

Returns:

Type: Object

(async, inner) loadYAML(path) → {Promise.<Object>}

Parameters:

Name	Type	Description
`path`	String

Source:

utils.js, line 50

Returns:

Type: Promise.<Object>

(inner) loadYAMLSync(path) → {Object}

Parameters:

Name	Type	Description
`path`	String

Source:

utils.js, line 58

Returns:

Type: Object

(inner) localeCompareFn(locales) → {localCompare}

Get a function to compare strings, with locale support if Intl is available.

Parameters:

Name	Type	Description
`locales`	String

Source:

utils.js, line 660

See:

https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Collator

Returns:

Type: localCompare

(inner) localeCompareSimple(a, b) → {Number}

Compare strings.

Parameters:

Name	Type	Description
`a`	String
`b`	String

Source:

utils.js, line 639

Returns:

Type: Number

(inner) matchFiles(pattern, optsopt) → {Promise.<Array.<String>>}

A Promised glob.

Parameters:

Name Type Attributes Description

pattern String

opts

Objects

Optional match opts.

Properties

Name	Type	Attributes	Default	Description
`workDir`	String	<optional>	.	Working dir for this match.
`ignoreDir`	Boolean	<optional>	true	Ignore directories or not.
`ignoreHidden`	Boolean	<optional>	true	Ignore hidden files or not.
`recursive`	Boolean	<optional>	true	Set to false if you don't care about subdirs to get better performance.

Source:

utils.js, line 277

Returns:

Type: Promise.<Array.<String>>

(inner) nodesEach(node, callback)

Recursively Pre-Order Traversal of parse5 Node.

Parameters:

Name	Type	Description
`node`	Object	Root parse5 Node of a tree.
`callback`	traversalCallback

Source:

utils.js, line 944

See:

https://github.com/inikulin/parse5/blob/master/packages/parse5/docs/tree-adapter/default/element.md

(inner) nodesFilter(node, callback) → {Array.<Object>}

Recursively Pre-Order Traversal of parse5 Node.

Parameters:

Name	Type	Description
`node`	Object	Root parse5 Node of a tree.
`callback`	filterCallback

Source:

utils.js, line 967

See:

https://github.com/inikulin/parse5/blob/master/packages/parse5/docs/tree-adapter/default/element.md

Returns:

An Array of filtered parse5 Nodes.

Type: Array.<Object>

(inner) paginate(p, posts, perPageopt) → {Array.<File>}

Paginate page's posts.

Parameters:

Name	Type	Attributes	Default	Description
`p`	File			Original page.
`posts`	Array.<File>			Page related posts.
`perPage`	Number	<optional>	10	How many posts per page.

Source:

utils.js, line 429

Returns:

Paginated pages, original page's index is 0.

Type: Array.<File>

(inner) paginateCategoriesPosts(categories, parentPath, docDir, perPageopt) → {Array.<File>}

Generate pages and paginate posts of categories.

Parameters:

Name	Type	Attributes	Default	Description
`categories`	Array.<Category>
`parentPath`	String			Parent category's dir.
`docDir`	docDir
`perPage`	Number	<optional>	10	How many posts per page.

Source:

utils.js, line 470

Returns:

All category and it's subs pages.

Type: Array.<File>

(inner) parseFrontMatter(file) → {File}

Parse front-matter and set properties to file.

Parameters:

Name	Type	Description
`file`	File

Source:

utils.js, line 378

Returns:

Type: File

(inner) parseNode(nodeopt, html, optionsopt) → {Object}

Parse HTML string into parse5 Node.

Parameters:

Name	Type	Attributes	Description
`node`	Object	<optional>	If specified, given fragment will be parsed as it was set to the context element's `innerHTML` property.
`html`	String		HTML string to parse.
`options`	Object	<optional>	parse5 options.

Source:

utils.js, line 895

See:

Returns:

Type: Object

(inner) putSite(site, key, file)

Put file into an array in site, will replace file with the same destination.

Parameters:

Name	Type	Description
`site`	Site
`key`	String
`file`	File

Source:

utils.js, line 820

(inner) removeControlChars(str) → {String}

Remove XML control chars.

Parameters:

Name	Type	Description
`str`	String

Source:

utils.js, line 317

Returns:

XML string.

Type: String

(inner) removeHTMLTags(str) → {String}

Remove all HTML tags.

Parameters:

Name	Type	Description
`str`	String

Source:

utils.js, line 231

Returns:

String without HTML tags.

Type: String

(inner) replaceNode(node, html)

Quick and not so dirty way to replace a Node with given HTML string.

Parameters:

Name	Type	Description
`node`	Object	parse5 Node to replace.
`html`	String

Source:

utils.js, line 916

(inner) resolveAnchors(node, baseURL, rootDir, docPath, optsopt)

Update site's internal link to absolute path, and add attributes for external link.

Parameters:

Name	Type	Attributes	Description
`node`	Object		parse5 Node.
`baseURL`	String		Site baseURL.
`rootDir`	String		Site rootDir.
`docPath`	String
`opts`	Object	<optional>

Source:

utils.js, line 1152

(inner) resolveCodeBlocks(node, optsopt)

Update code blocks.

Parameters:

Name Type Attributes Description

node

Object

parse5 Node.

opts

Object

Properties

Name	Type	Attributes	Default	Description
`lineNumbers`	Boolean	<optional>	false	Generate line numbers.

Source:

utils.js, line 1213

(inner) resolveHeadingIDs(node, optsopt)

Update headings' IDs for bootstrap scrollspy.

Parameters:

Name Type Attributes Description

node

Object

parse5 Node.

opts

Object

Properties

Name	Type	Attributes	Default	Description
`safeChar`	String	<optional>	"-"	Char used to replace unsupported chars.

Source:

utils.js, line 1063

(inner) resolveImages(node, rootDir, docPath, optsopt)

Update site's internal image src to absolute path.

Parameters:

Name	Type	Attributes	Description
`node`	Object		parse5 Node.
`rootDir`	String		Site rootDir.
`docPath`	String
`opts`	Object	<optional>

Source:

utils.js, line 1188

(inner) serializeNode(node, optionsopt) → {String}

Serialize parse5 Node into HTML string.

Parameters:

Name	Type	Attributes	Description
`node`	Object		parse5 Node to serialize.
`options`	Object	<optional>	parse5 options.

Source:

utils.js, line 906

See:

https://github.com/inikulin/parse5/blob/master/packages/parse5/docs/index.md#serialize

Returns:

Type: String

(inner) setNodeAttr(node, attrName, attrValue)

Set an attribute value to parse5 Node.

Parameters:

Name	Type	Description
`node`	Object	parse5 Node.
`attrName`	String
`attrValue`	String

Source:

utils.js, line 1041

(inner) setNodeText(node, html)

Set text content (or innerHTML) of a parse5 Node.

Parameters:

Name	Type	Description
`node`	Object	parse5 Node.
`html`	String

Source:

utils.js, line 1002

Type Definitions

CategoriesData

Type:

Object

Properties:

Name	Type	Description
`categories`	Array.<Category>
`categoriesLength`	Number

Source:

utils.js, line 737

FrontMatter

Type:

Object

Properties:

Name	Type	Description
`attributes`	Object	Parsed front-matter properties.
`body`	String	String after front-matter.
`frontMatter`	String	Front-matter string.

Source:

utils.js, line 322

TagsData

Type:

Object

Properties:

Name	Type	Description
`tags`	Array.<Tag>
`tagsLength`	Number

Source:

utils.js, line 776

compareCallback(a, b) → {Number}

Comparing function accepted by Array.sort().

Parameters:

Name	Type	Description
`a`	*
`b`	*

Source:

utils.js, line 235

Returns:

Type: Number

filterCallback(node) → {Boolean}

Parameters:

Name	Type	Description
`node`	Object	parse5 Node.

Source:

utils.js, line 955

Returns:

True to collect a node into an Array.

Type: Boolean

formatDateTime(dtopt) → {String}

Format date and time, with locale support if Intl is available.

Parameters:

Name	Type	Attributes	Default	Description
`dt`	*	<optional>	new Date()

Source:

utils.js, line 694

Returns:

Type: String

getPath(docPathopt, skipEncodeopt) → {String}

Get full website path starts from / after domain. This function can only handle site internal path.

Parameters:

Name	Type	Attributes	Default	Description
`docPath`	String	<optional>
`skipEncode`	Boolean	<optional>	false	If true, skip `encodeURI()`.

Source:

utils.js, line 494

Returns:

Full path that starts with site rootDir.

Type: String

getURL(docPathopt) → {URL}

Get full website URL including the domain. This function can only handle site internal path.

Parameters:

Name	Type	Attributes	Description
`docPath`	String	<optional>

Source:

utils.js, line 537

Returns:

Full website URL.

Type: URL

isCurrentHost(testURLopt) → {Boolean}

Test if given URL is on current host. This function does not care about query string and hash.

Parameters:

Name	Type	Attributes	Description
`testURL`	String	<optional>	URL needed to test.

Source:

utils.js, line 557

Returns:

Type: Boolean

isCurrentPath(testPathopt, strictopt) → {Boolean}

Test if given path is current path. This function does not care about query string and hash. This function can only handle site internal path.

Parameters:

Name	Type	Attributes	Default	Description
`testPath`	String	<optional>		Path needed to test.
`strict`	Boolean	<optional>	false	If not strict, true is also returned if given path is parent path of current path.

Source:

utils.js, line 582

Returns:

Type: Boolean

localeCompare(a, b) → {Number}

Compare strings, with locale support if Intl is available.

Parameters:

Name	Type	Description
`a`	String
`b`	String

Source:

utils.js, line 646

Returns:

Type: Number

traversalCallback(node)

Parameters:

Name	Type	Description
`node`	Object	parse5 Node.

Source:

utils.js, line 934