Ghost is written in 100% JavaScript. Where there are shared or common tasks for working with Ghost's API, we aim to publish reusable packages that do as much of the work as possible. This means our SDK is an ever-growing library of tiny tools for working with Ghost.
Helpers
- Package:
@tryghost/helpers
- Builds: CJS, ES, UMD
The shared helpers are designed for performing data formatting tasks, usually when creating custom frontends. These are the underlying tools that power our handlebars and gatsby helpers.
Tags
Filters and outputs tags. By default, the helper will output a comma separated list of tag names, excluding any internal tags.
import {tags} from '@tryghost/helpers'
// Outputs e.g. Posted in: New Things, Releases, Features.
posts.forEach((post) => {
tags(post, {prefix: 'Posted in: ', suffix: '.'});
});
The first argument must be a post object, or any object that has a tags
array.
Options
The tag helper supports multiple options so that you can control exactly what is output, without having to write any logic.
limit
{integer} - limits the number of tags to be returnedfrom
{integer, default:1} - index of the tag to start iterating fromto
{integer} - index of the last tag to iterate overseparator
{string, default:","} - string used between each tagprefix
{string} - string to output before each tagsuffix
{string} - string to output after each tagvisibility
{string, default:"public"} - change to "all" to include internal tagsfallback
{object} - a fallback tag to output if there are nonefn
{function} - function to call on each tag, default returns tag.name
Reading Time
Calculates the estimated reading time based on the HTML for a post & available images.
import {readingTime} from '@tryghost/helpers'
// Outputs e.g. A 5 minute read.
posts.forEach((post) => {
readingTime(post, {minute: 'A 1 minute read.', minutes: 'A % minute read.'});
});
The first argument must be a post object, or any object that has an html
string. If a feature_image
is present, this is taken into account.
Options
The output of the reading time helper can be customised through format strings.
minute
{string, default:"1 min read"} - format for reading times <= 1 minuteminutes
{string, default:"% min read"} - format for reading times > 1 minute
Installation
yarn add @tryghost/helpers
npm install @tryghost/helpers
You can also use the standalone UMD build:
https://unpkg.com/@tryghost/helpers@{version}/umd/helpers.min.js
Usage
ES modules:
import {tags, readingTime} from '@tryghost/helpers'
Node.js:
const {tags, readingTime} = require('@tryghost/helpers');
In the browser:
<script src="https://unpkg.com/@tryghost/helpers@{version}/umd/helpers.min.js"></script>
<script>
const {tags, readingTime} = GhostHelpers;
</script>
Get the latest version from https://unpkg.com.
String
- Package:
@tryghost/string
- Builds: CJS
Utilities for processing strings.
Slugify
The function Ghost uses to turn a post title or tag name into a slug for use in URLs.
const {slugify} = require('@tryghost/string');
const slug = slugify('你好 👋!'); // slug === "ni-hao"
The first argument is the string to transform. The second argument is an optional options object.
Options
The output can be customised by passing options
requiredChangesOnly
{boolean, default:false} - don't perform optional cleanup, e.g. removing extra dashesInstallation
yarn add @tryghost/string
npm install @tryghost/string
Usage
Node.js:
const {slugify} = require('@tryghost/string');
Contributing
Our individual SDK packages are maintained together in the Ghost SDK repository. We welcome contributions both to existing packages and of new packages.