Working With Eleventy

Eleventy and Ghost

Eleventy is a good fit for a lightweight Ghost front-end. Ghost remains the CMS: editors write posts, manage pages, upload images, and handle publishing in Ghost Admin. Eleventy reads that content from the Content API when the site builds. For most Eleventy sites, use the official JavaScript Content API client. It is maintained as part of the TryGhost SDK and works in Node.js during Eleventy builds. Use the Admin API only for private server-side scripts, such as imports or custom publishing tools. Do not put an Admin API key in client-side JavaScript.

Prerequisites

This configuration requires basic knowledge of JavaScript and HTML templates. You will also need:

A running Ghost site, either self-hosted or on Ghost(Pro)
A custom integration in Ghost Admin so you can copy the Content API URL and key
An Eleventy project

Create the Content API key from Settings -> Integrations in Ghost Admin. For more detail, see Content API authentication.

Start from a new Eleventy site

If you already have an Eleventy site, skip to the Content API setup. Otherwise, create a small project and install Eleventy:

mkdir my-eleventy-site
cd my-eleventy-site
npm init -y
npm install @11ty/eleventy @tryghost/content-api dotenv

Eleventy documents the same project setup in the official Eleventy docs.

Install the Ghost Content API client

If you started with an existing Eleventy site, install the Ghost Content API client:

npm install @tryghost/content-api dotenv

Add your Ghost credentials to environment variables. A local .env file is fine if your deployment platform loads it and you keep it out of source control.

GHOST_API_URL=https://demo.ghost.io
GHOST_CONTENT_API_KEY=22444f78447824223cefc48062
GHOST_API_VERSION=v6.0

For Ghost(Pro), the URL is usually your .ghost.io URL. For self-hosted Ghost, use the public URL for your Ghost install.

Fetch Ghost content with a global data file

Eleventy global data files make API data available to every template. Create _data/ghost.js:

// _data/ghost.js
require("dotenv").config();
const GhostContentAPI = require("@tryghost/content-api");

const api = new GhostContentAPI({
  url: process.env.GHOST_API_URL,
  key: process.env.GHOST_CONTENT_API_KEY,
  version: process.env.GHOST_API_VERSION || "v6.0",
});

async function browseAll(resource, options = {}) {
  const items = [];
  let page = 1;

  while (page) {
    const response = await resource.browse({
      ...options,
      limit: 100,
      page,
    });

    items.push(...response);
    page = response.meta.pagination.next || null;
  }

  return items;
}

module.exports = async function() {
  const [posts, pages, tags, authors, settings] = await Promise.all([
    browseAll(api.posts, { include: "tags,authors", order: "published_at DESC" }),
    browseAll(api.pages, { include: "tags,authors" }),
    browseAll(api.tags, { include: "count.posts" }),
    browseAll(api.authors, { include: "count.posts" }),
    api.settings.browse(),
  ]);

  return {
    posts,
    pages,
    tags,
    authors,
    settings,
  };
};

Ghost 6.0 and later limit each browse request to 100 records, so static builds need pagination. The helper above follows the meta.pagination.next value until there are no more pages. See pagination for building static sites and Content API pagination for the underlying API behavior.

List posts on the home page

Create index.njk and read from the ghost data object:

---
title: Latest posts
---

<!doctype html>
<html lang="{{ ghost.settings.lang or 'en' }}">
  <head>
    <meta charset="utf-8">
    <title>{{ ghost.settings.title }}</title>
  </head>
  <body>
    <h1>{{ ghost.settings.title }}</h1>

    <ul>
      {% for post in ghost.posts %}
        <li>
          <a href="/posts/{{ post.slug }}/">{{ post.title }}</a>
          {% if post.primary_author %}
            by {{ post.primary_author.name }}
          {% endif %}
        </li>
      {% endfor %}
    </ul>
  </body>
</html>

Create one page per post

Use Eleventy pagination with a page size of 1 to create a static page for every Ghost post.

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

<!doctype html>
<html lang="{{ ghost.settings.lang or 'en' }}">
  <head>
    <meta charset="utf-8">
    <title>{{ post.title }} - {{ ghost.settings.title }}</title>
  </head>
  <body>
    <article>
      <h1>{{ post.title }}</h1>
      {% if post.primary_author %}
        <p>{{ post.primary_author.name }}</p>
      {% endif %}
      {{ post.html | safe }}
    </article>
  </body>
</html>

Ghost returns post HTML from content written in Ghost Admin. Rendering it with the Nunjucks safe filter is normal for a trusted CMS source, but do not use it for untrusted user-submitted HTML.

Create tag and author pages

The same ghost data object includes tags and authors. For example, this creates one archive page per tag:

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

<!doctype html>
<html lang="{{ ghost.settings.lang or 'en' }}">
  <head>
    <meta charset="utf-8">
    <title>{{ tag.name }} - {{ ghost.settings.title }}</title>
  </head>
  <body>
    <h1>{{ tag.name }}</h1>

    <ul>
      {% for post in ghost.posts %}
        {% if post.primary_tag and post.primary_tag.slug == tag.slug %}
          <li><a href="/posts/{{ post.slug }}/">{{ post.title }}</a></li>
        {% endif %}
      {% endfor %}
    </ul>
  </body>
</html>

For larger sites, pre-group posts by tag in _data/ghost.js so templates do less filtering work.

Run Eleventy locally

Once the data file and templates are in place, start Eleventy’s local development server:

npx @11ty/eleventy --serve

Eleventy serves the site at http://localhost:8080/ by default.

Use the Admin API from private scripts

The Admin API can create, update, and publish content. It is useful for migrations or custom editorial tooling, but it is not needed to render a public Eleventy front-end. Install the Admin API client only where the key stays private:

npm install @tryghost/admin-api

// scripts/create-draft.js
const GhostAdminAPI = require("@tryghost/admin-api");

const admin = new GhostAdminAPI({
  url: process.env.GHOST_API_URL,
  key: process.env.GHOST_ADMIN_API_KEY,
  version: "v6.0",
});

admin.posts.add(
  {
    title: "Draft from a private script",
    html: "<p>This draft was created through the Admin API.</p>",
    status: "draft",
  },
  { source: "html" }
);

Run Admin API scripts on your own machine, in CI, or on a server. Never ship GHOST_ADMIN_API_KEY to the browser.

Next steps

Read the Content API JavaScript client docs for available endpoints and options. Eleventy’s global data files and pagination docs explain how API data becomes static pages.

Getting Started

Core Concepts

Themes

Advanced Tools

Resources

Eleventy and Ghost

Prerequisites

Start from a new Eleventy site

Install the Ghost Content API client

Fetch Ghost content with a global data file

List posts on the home page

Create one page per post

Create tag and author pages

Run Eleventy locally

Use the Admin API from private scripts

Next steps

​Eleventy and Ghost

​Prerequisites

​Start from a new Eleventy site

​Install the Ghost Content API client

​Fetch Ghost content with a global data file

​List posts on the home page

​Create one page per post

​Create tag and author pages

​Run Eleventy locally

​Use the Admin API from private scripts

​Next steps

Eleventy and Ghost

Prerequisites

Start from a new Eleventy site

Install the Ghost Content API client

Fetch Ghost content with a global data file

List posts on the home page

Create one page per post

Create tag and author pages

Run Eleventy locally

Use the Admin API from private scripts

Next steps