Helpers

Helpers let you extend Handlebars with custom functionality. You can use them to manipulate data, generate content, and more. Every helper has a name and can be referenced in your pages using the following syntax. Doxicity ships with some built-in helpers, but you can also add your own.

Syntax

Helpers are accessed using the following syntax.

{{helperName}}

Some helpers accept one or more arguments. For example, the {{slugify}} helper needs to know what string you’re trying to “slugify”. You can pass it an argument like this. 

{{slugify 'this will be slugified'}}

If you want to pass data instead of a hard-coded string, omit the quotes and pass the appropriate property name. 

--- 
text: this will be slugified
---

{{slugify text}}

Some helpers accept hash arguments, which are a lot like HTML attributes. Hash arguments can be provided in any order and can accept strings, numbers, and/or data. 

{{helperName key='value' name='doxicity'}}

Built-in Helpers

All of Handlebars’ built-in helpers are supported. In addition, Doxicity provides the following helpers for convenience. Square brackets denote optional arguments.

Name Description
{{asset [pathname]}} Generates a URL to the assets folder. The pathname argument is optional and will be appended to the URL. You should use this whenever you need to reference an asset to prevent broken links if your config changes.
{{formatDate date [...hash]}} Outputs a localized date in the desired format using the Intl.DateTimeFormat API. Available hash arguments include lang, weekday, era, year, month, day, hour, minute, second, timeZoneName, timeZone, and hourFormat.
{{formatNumber number [...hash]}} Outputs a localized number in the desired format using the Intl.NumberFormat API. Available hash arguments include lang, type, noGrouping, currency, currencyDisplay, minimumIntegerDigits, minimumFractionDigits, maximumFractionDigits, minimumSignificantDigits, maximumSignificantDigits.
{{slugify string}} Converts a string from “Some String” to “some-string”, which is useful for things like permalinks.
{{url [pathname]}} Outputs your website’s baseUrl as defined in your config. The pathname argument is optional and will be appended to the base URL. You should use this whenever you need to reference a path relative to your website’s base URL.

Hash arguments look a lot like HTML attributes. Here is an example that uses three hash arguments, for reference. 

{{formatDate '2022-04-17' year='numeric' month='long' day='numeric'}}

Writing Your Own Helpers

Helpers must adhere to the DoxicityHelper interface described below. The interface is described in TypeScript, but you can write helpers in JavaScript as well. When naming helpers, avoid using the same name as any top-level fields in your config data or page data. 

export interface DoxicityHelper {
  name: string;
  callback: (args: unknown) => string;
}

Here’s an example helper that converts a string to uppercase.

const myHelper = { name: 'uppercase', callback: string => string.toUppercase() };

Helpers can receive any valid argument(s) that Handlebars supports. You can find more details in the Handlebars documentation .