Jekyll Utils

A collection of Jekyll utilility methods to generate eg. Jekyll permalinks and slugs

Requirements

Requires at least Node.js 10.x

Installation

npm install jekyll-utils --save

API Usage

slugify

• See: Mimicked Jekyll Code

Slugify a filename or title.

When mode is "none", return the given string.

When mode is "raw", return the given string, with every sequence of spaces characters replaced with a hyphen.

When mode is "default" or nil, non-alphabetic characters are replaced with a hyphen too.

When mode is "pretty", some non-alphabetic characters (._~!$&'()+,;=@) are not replaced with hyphen.

If cased is true, all uppercase letters in the result string are replaced with their lowercase counterparts.

Parameters

• str string the string to create a slug of
• mode string how string is slugified. Can be set to "default", "pretty" or "raw" (optional, default default)
• cased boolean – whether to keep the character casing or not (optional, default false)

Examples

slugify('The _config.yml file')
// => 'the-config-yml-file'

slugify('The _config.yml file', 'pretty')
// => 'the-_config.yml-file'

slugify('The _config.yml file', 'pretty', true)
// => 'The-_config.yml file'

Returns string the slugified string

generateUrl

Parameters

• template string The String used as template for URL generation, for example "/:path/:basename:output_ext", where a placeholder is prefixed with a colon. Or one of the predefined styles "pretty", "none", "date" or "ordinal". (optional, default date)

• jekyllResource object A representation of a Jekyll resource such as a Post or a Page

  • jekyllResource.basename_without_ext string The file basename without the file extension.
  • jekyllResource.date (Date | number) The published date of the resource
  • jekyllResource.data object? The resource document's data
    • jekyllResource.data.categories Array<string>? The categories specified on the document
    • jekyllResource.data.slug string? The slug specified on the document

• Throws Error if not all needed placeholders are found

Returns string the String URL

JekyllUrl

• See: Mimicked Jekyll Code

Methods that generate a URL for a resource such as a Post or a Page.

Parameters

• options object One of :permalink or :template must be supplied.
  • options.template string The String used as template for URL generation, or example "/:path/:basename:output_ext", where a placeholder is prefixed with a colon.
  • options.null string :placeholders - A hash containing the placeholders which will be replaced when used inside the template. E.g. { year: (new Date()).getFullYear() } would replace the placeholder ":year" with the current year.
  • options.permalink string If supplied, no URL will be generated from the template. Instead, the given permalink will be used as URL.

Examples

new JekyllUrl({
  template: '/:categories/:title.html',
  placeholders: {':categories': 'ruby', ':title' => 'something'}
}).toString();

toString

Generates the relative URL of the resource

• Throws Error if the relative URL contains a colon

Returns string the String URL

generated_permalink

Generates a URL from the permalink

Returns (string | false) the unsanitized String URL

generated_url

Generates a URL from the template

Returns (string | false) the unsanitized String URL

sanitize_url

Parameters

• str string an unsanitized String URL

Returns string a sanitized String URL, stripping "../../" and multiples of "/", as well as the beginning "/" so we can enforce and ensure it.

escape_path

Escapes a path to be a valid URL path segment

Parameters

• path string The path to be escaped.

Examples

JekyllUrl.escape_path('/a b')
// => '/a%20b'

Returns string the escaped path.