Displays posts in a series for the Ghost publishing platform.
You must have a Content API key for your site first. You will likely need to generate a new Content API key. TODO: Link to that process. Once your key is ready, there are a couple options to integrate Series Display with your Ghost site.
The easiest way to integrate with your site is to inject code via the Admin site.
Copy the ghost-series-display.min.js
file to your site's server.
We recommend finding the assets
directory likely already included with your theme and copying the
file to a sensible location there (e.g., assets/js/
).
Next, you will need to add some code via your Admin site.
- Login to your Admin site.
- Navigate to the Settings area.
- Choose Code Injection.
- Add the JS code (example below) to the Site Footer.
If you are comfortable editing your site's theme, you can integrate directly. However, doing so will only affect that specific theme, whereas the Code Injection method works for any theme (barring some possible needed tweaks to the embed script for insertions).
- Install the
ghost-series-display
package via NPM to your theme project:
npm i ghost-series-display --save-dev
- Update your theme's build script to include one of the scripts from the
ghost-series-display
package. Below is an example for adding its UMD script to theCasper
theme.
function js(done) {
pump([
src([
'assets/js/lib/*.js',
'assets/js/*.js'
], {sourcemaps: true}),
uglify(),
concat('casper.js'),
dest('assets/built/', {sourcemaps: '.'}),
src('node_modules/ghost-series-display/dist/umd/ghost-series-display.min.js'),
dest('assets/built/', {sourcemaps: '.'}),
livereload()
], handleError(done));
}
- Open your theme's main template (usually
default.hbs
). - Add a block for page scripts just before the
ghost_foot
helper.
{{{block "pageScripts"}}}
{{ghost_foot}}
</body>
- Open your theme's post template (e.g.,
post.hbs
). - Add the integration script code inside a content block matching the name used in your main template.
{{#contentFor "pageScripts"}}
<script src="https://unpkg.com/@tryghost/content-api@1.6.0/umd/content-api.min.js"></script>
<script>
// Series Display
(function(opts) {
...
})({
document: window.document,
src: '{{asset "built/ghost-series-display.min.js"}}',
apiKey: '0123456789abcdef0123456789',
apiUrl: `${window.location.protocol}//${window.location.host}`
});
</script>
{{/contentFor}}
These examples require you to verify (or change) the location of the Series Display script file
and your generated Ghost Content API key. Additionally, if your Admin site is separate from your
content site, you will need to change that argument with the apporporiate URL
(e.g., https://admin.mysite.com
). All 3 values are near the end of the script.
If you would rather copy the Series Display script file to your server, you must change the
src
property near the end of the integration script. An example of such a change could be:
{
document: window.document,
src: '/assets/built/ghost-series-display.min.js',
apiKey: '0123456789abcdef0123456789',
apiUrl: `${window.location.protocol}//${window.location.host}`
}
Note: If you already included a reference to the Ghost Content API script file before, or it is included in your theme, you do not need to include the first line of the inclusion script code.
Our first example is the most basic to get things running. It uses default options and works
well for the Casper theme (or any theme that has an element with class .gh-content
for the
post content).
<script src="https://unpkg.com/@tryghost/content-api@1.6.0/umd/content-api.min.js"></script>
<script>
// Series Display
(function(opts) {
var api = new GhostContentAPI({ url: opts.apiUrl, key: opts.apiKey, version: 'v4' });
function loadSeriesDisplay(document, src, api) {
return new Promise((resolve, reject) => {
var script = document.createElement('script');
script.onload = () => resolve(new GhostSeriesDisplay.SeriesDisplay(api));
script.onerror = reject;
script.async = true;
script.src = src;
document.head.append(script);
});
}
loadSeriesDisplay(opts.document, opts.src, api)
.then((seriesDisplay) => {
// Minimum needed to display series info.
seriesDisplay.displaySeriesInfo(document);
});
})({
document: window.document,
src: 'https://unpkg.com/ghost-series-display/dist/umd/ghost-series-display.min.js',
apiKey: '0123456789abcdef0123456789',
apiUrl: `${window.location.protocol}//${window.location.host}`
});
</script>
Another example uses custom options for the display of our series info.
<script src="https://unpkg.com/@tryghost/content-api@1.6.0/umd/content-api.min.js"></script>
<script>
// Series Display
(function(opts) {
var api = new GhostContentAPI({ url: opts.apiUrl, key: opts.apiKey, version: 'v4' });
function loadSeriesDisplay(document, src, api) {
return new Promise((resolve, reject) => {
var script = document.createElement('script');
script.onload = () => resolve(new GhostSeriesDisplay.SeriesDisplay(api));
script.onerror = reject;
script.async = true;
script.src = src;
document.head.append(script);
});
}
loadSeriesDisplay(opts.document, opts.src, api)
.then((seriesDisplay) => {
// Do not show info for a single post series (need at least 2 posts in the series).
// Show series info at the top of the post AND after the post's read more nav.
// * Our theme uses the .post class for its post element.
var options = {
hideSinglePostSeries: true,
insertions: [
{
selector: '.post',
position: GhostSeriesDisplay.ElementInsertionPosition.BEGIN
},
{
selector: '.post ~ nav.read-more',
position: GhostSeriesDisplay.ElementInsertionPosition.AFTER
}
]
}
seriesDisplay.displaySeriesInfo(document);
});
})({
document: window.document,
src: 'https://unpkg.com/ghost-series-display/dist/umd/ghost-series-display.min.js',
apiKey: '0123456789abcdef0123456789',
apiUrl: `${window.location.protocol}//${window.location.host}`
});
</script>
Not too much to say here. We are using np
for easier publishing to NPM.
Be sure to prepare the build first.
npm run prepare
After the build is complete, run np
with an appropriate version.
np patch
np minor
np major
np 1.0.0