eleventy-plugin-ghost

Import your Ghost content directly into Eleventy as global data. Compatible with Eleventy v1.0.0 and above.

Check out the live demo and the demo directory in the repo to see it all in action.

Installation

1. Install the plugin using npm:

   npm install eleventy-plugin-ghost

2. Add the plugin to your .eleventy.js config, ensuring to add your Ghost URL, Content API key and optionally your Admin API key. Check out the Ghost docs for how to create a Content or Admin API key:

   const pluginGhost = require("eleventy-plugin-ghost");
   
   require("dotenv").config();
   const {
     GHOST_URL,
     // GHOST_ADMIN_KEY,
     GHOST_KEY,
   } = process.env;
   
   module.exports = (eleventyConfig) => {
     eleventyConfig.addPlugin(pluginGhost, {
       url: GHOST_URL,
       key: GHOST_KEY,
       // apiKey: GHOST_ADMIN_KEY,
       version: "v4", // "v4" is the default
     });
   };

   The example above is using dotenv with a .env file to ensure credentials are not stored in the source code. Here's an example of the .env file:

   GHOST_URL=https://demo.ghost.io
   GHOST_KEY=22444f78447824223cefc48062

3. Run or build your Eleventy project and use the global ghost data variable to access posts, pages, tags, authors and settings.

Usage

The API will default to the latest stable version, which is v4. However passing version into the plugin options will set the version returned, as shown in the above code sample.

After installing and running you'll be provided with a global ghost key as well as a filtersPosts() function. See API and filtering posts sections respectively for more information.

API

• ghost.posts: An array of all posts in Ghost, including their tags and authors. Note that the posts array will include draft posts if you use the Admin API
• ghost.pages: An array of all pages in Ghost. Note that the pages array will include draft pages if you use the Admin API
• ghost.tags: An array of all tags in Ghost, including the number of posts within each tag but filtered to only contain public tags
• ghost.authors: An array of all authors in Ghost, including the number of posts within each author. Note that using the Admin API will cause authors to actually return users which comes with additional data
• ghost.settings: All settings set in Ghost

All data is cached using @11ty/eleventy-fetch with a duration of 1 minute. This keeps the local builds fast while still inheriting newly applied content.

Admin API

Passing in an Admin API key will cause the plugin to use the Ghost Admin API. This means all global data objects except for settings will return additional data. For example posts and pages will include draft posts and pages. For more information on what additional data is exposed check out the official Ghost docs.

If you're looking to get additional data from the Admin API, such as tiers, offers and members then feel free to follow the development guide guide down below and submit a pull request.

Internal tags

When posts are retrieved all tags are applied, including internal tags. Internal tags are very useful for grouping posts without exposing the tag in the front-end. To assist with this the plugin filters out internal tags from the tags key on posts and applies them to a new internalTags key. Internal tag slugs are prefixed with hash- to mirror the # applied in the UI to define them.

Filtering posts

The plugin comes with a custom filter called filterPosts, this can be used to filter posts by attributes such as authors, tags and internalTags using the attributes slug. The following example will list posts that are tagged with "portfolio":

{% for post in ghost.posts | filterPosts("tags", "portfolio") %}
  <li><a href="/{{ post.slug }}/">{{ post.title }}</a></li>
{% endfor %}

It's also possible to filter out posts with a certain tag by prefixing the parameter with !:

{% for post in ghost.posts | filterPosts("tags", "!blog") %}
  <li><a href="/{{ post.slug }}/">{{ post.title }}</a></li>
{% endfor %}

The filter works for authors as well as internalTags:

{% for post in ghost.posts | filterPosts("internalTags", "!hash-internal-tag") %}
  <li><a href="/{{ post.slug }}/">{{ post.title }}</a></li>
{% endfor %}

{% for post in ghost.posts | filterPosts("authors", "david") %}
  <li><a href="/{{ post.slug }}/">{{ post.title }}</a></li>
{% endfor %}

Creating pages

Rendering pages for posts, pages, authors and tags can be done by making use of the eleventy pagination feature. In the following example post pages are being created in a post.njk file:

---
pagination:
  data: ghost.posts
  size: 1
  alias: post
permalink: "/{{ post.slug }}/"
---

<h1>{{ post.title }}</h1>
{{ post.html | safe }}

The same can be done for authors and tags in combination with the filterPosts function to list out posts by that author or tagged with that tag:

---
pagination:
  data: ghost.tags
  size: 1
  alias: tag
permalink: "/{{ tag.slug }}/"
---

<h1>{{ tag.name }}</h1>
<ul>
  {% for post in ghost.posts | filterPosts("tags", tag.slug) %}
    <li><a href="/{{ post.slug }}/">{{ post.title }}</a></li>
  {% endfor %}
</ul>

A more advanced use case is if you want to render post pages but filter out posts with a certain attribute. The below example makes use of gray-matter in eleventy and checks if a post has an internal tag with the slug hash-internal-tag and prevents the post from rendering:

---js
{
  pagination: {
    data: "ghost.posts",
    size: 1,
    alias: "post",
    before: function(data) {
      return data.filter(post => post.internalTags.every(tag => tag.slug !== "hash-internal-tag"));
    }
  },
  permalink: "/{{ post.slug }}/"
}
---

<h1>{{ post.title }}</h1>
{{ post.html | safe }}

Check out the demo directory of this project for more extensive examples.

Development

1. Create a .env file inside of demo with the following credentials:

   GHOST_URL=https://demo.ghost.io
   GHOST_KEY=22444f78447824223cefc48062

2. Amend the .eleventy.js file within demo so it points to the source code in the parent directory:

   // const pluginGhost = require("../");
   const pluginGhost = require("eleventy-plugin-ghost");

3. Install the demo dependencies:

   cd demo
   npm install

4. Run the demo locally:

   npm run dev