{"id":13929288,"url":"https://github.com/daviddarnes/eleventy-plugin-ghost","last_synced_at":"2025-04-12T09:31:47.586Z","repository":{"id":39751784,"uuid":"342272924","full_name":"daviddarnes/eleventy-plugin-ghost","owner":"daviddarnes","description":"Access the Ghost API in Eleventy 👻🎈","archived":false,"fork":false,"pushed_at":"2022-06-01T08:32:14.000Z","size":43,"stargazers_count":20,"open_issues_count":0,"forks_count":3,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-04-11T14:58:02.355Z","etag":null,"topics":["eleventy","eleventy-plugin","ghost","ghost-api","ghost-cms","headless-cms"],"latest_commit_sha":null,"homepage":"https://eleventy-plugin-ghost.netlify.app","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/daviddarnes.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-02-25T14:34:32.000Z","updated_at":"2024-05-21T09:35:36.000Z","dependencies_parsed_at":"2022-09-07T15:02:30.405Z","dependency_job_id":null,"html_url":"https://github.com/daviddarnes/eleventy-plugin-ghost","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":"5t3ph/eleventy-plugin-template","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daviddarnes%2Feleventy-plugin-ghost","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daviddarnes%2Feleventy-plugin-ghost/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daviddarnes%2Feleventy-plugin-ghost/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daviddarnes%2Feleventy-plugin-ghost/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/daviddarnes","download_url":"https://codeload.github.com/daviddarnes/eleventy-plugin-ghost/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248546105,"owners_count":21122253,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["eleventy","eleventy-plugin","ghost","ghost-api","ghost-cms","headless-cms"],"created_at":"2024-08-07T18:02:14.243Z","updated_at":"2025-04-12T09:31:47.288Z","avatar_url":"https://github.com/daviddarnes.png","language":"JavaScript","readme":"# eleventy-plugin-ghost\n\n[![npm](https://img.shields.io/npm/v/eleventy-plugin-ghost)](https://www.npmjs.com/package/eleventy-plugin-ghost)\n\nImport your [Ghost](https://ghost.org) content directly into [Eleventy](https://github.com/11ty/eleventy) as global data. Compatible with Eleventy v1.0.0 and above.\n\n[Check out the live demo](https://eleventy-plugin-ghost.netlify.app) and the [demo directory in the repo](https://github.com/daviddarnes/eleventy-plugin-ghost/tree/main/demo) to see it all in action.\n\n## Installation\n\n1. Install the plugin using npm:\n\n   ```\n   npm install eleventy-plugin-ghost\n   ```\n\n2. 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](http://www.ghost.org/docs/content-api/) or [Admin API key](https://ghost.org/docs/admin-api/):\n\n   ```js\n   const pluginGhost = require(\"eleventy-plugin-ghost\");\n\n   require(\"dotenv\").config();\n   const {\n     GHOST_URL,\n     // GHOST_ADMIN_KEY,\n     GHOST_KEY,\n   } = process.env;\n\n   module.exports = (eleventyConfig) =\u003e {\n     eleventyConfig.addPlugin(pluginGhost, {\n       url: GHOST_URL,\n       key: GHOST_KEY,\n       // apiKey: GHOST_ADMIN_KEY,\n       version: \"v4\", // \"v4\" is the default\n     });\n   };\n   ```\n\n   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:\n\n   ```text\n   GHOST_URL=https://demo.ghost.io\n   GHOST_KEY=22444f78447824223cefc48062\n   ```\n\n3. Run or build your Eleventy project and use the global `ghost` data variable to access `posts`, `pages`, `tags`, `authors` and `settings`.\n\n## Usage\n\nThe 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.\n\nAfter installing and running you'll be provided with a global `ghost` key as well as a `filtersPosts()` function. See [API](#API) and [filtering posts](#Filtering-posts) sections respectively for more information.\n\n## API\n\n- `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\n- `ghost.pages`: An array of all pages in Ghost. Note that the `pages` array will include draft pages if you use the Admin API\n- `ghost.tags`: An array of all tags in Ghost, including the number of posts within each tag but filtered to only contain public tags\n- `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\n- `ghost.settings`: All settings set in Ghost\n\nAll data is cached using [`@11ty/eleventy-fetch`](https://www.11ty.dev/docs/plugins/fetch/) with a duration of 1 minute. This keeps the local builds fast while still inheriting newly applied content.\n\n## Admin API\n\nPassing 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](https://ghost.org/docs/admin-api/#posts).\n\nIf 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](#development) guide down below and submit a pull request.\n\n## Internal tags\n\nWhen posts are retrieved all tags are applied, including [internal tags](https://ghost.org/docs/publishing/#internal-tag). 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.\n\n## Filtering posts\n\nThe 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\":\n\n```nunjucks\n{% for post in ghost.posts | filterPosts(\"tags\", \"portfolio\") %}\n  \u003cli\u003e\u003ca href=\"/{{ post.slug }}/\"\u003e{{ post.title }}\u003c/a\u003e\u003c/li\u003e\n{% endfor %}\n```\n\nIt's also possible to filter _out_ posts with a certain tag by prefixing the parameter with `!`:\n\n```nunjucks\n{% for post in ghost.posts | filterPosts(\"tags\", \"!blog\") %}\n  \u003cli\u003e\u003ca href=\"/{{ post.slug }}/\"\u003e{{ post.title }}\u003c/a\u003e\u003c/li\u003e\n{% endfor %}\n```\n\nThe filter works for `authors` as well as `internalTags`:\n\n```nunjucks\n{% for post in ghost.posts | filterPosts(\"internalTags\", \"!hash-internal-tag\") %}\n  \u003cli\u003e\u003ca href=\"/{{ post.slug }}/\"\u003e{{ post.title }}\u003c/a\u003e\u003c/li\u003e\n{% endfor %}\n```\n\n```nunjucks\n{% for post in ghost.posts | filterPosts(\"authors\", \"david\") %}\n  \u003cli\u003e\u003ca href=\"/{{ post.slug }}/\"\u003e{{ post.title }}\u003c/a\u003e\u003c/li\u003e\n{% endfor %}\n```\n\n## Creating pages\n\nRendering pages for posts, pages, authors and tags can be done by making use of the [eleventy pagination](https://www.11ty.dev/docs/pagination/) feature. In the following example post pages are being created in a `post.njk` file:\n\n```nunjucks\n---\npagination:\n  data: ghost.posts\n  size: 1\n  alias: post\npermalink: \"/{{ post.slug }}/\"\n---\n\n\u003ch1\u003e{{ post.title }}\u003c/h1\u003e\n{{ post.html | safe }}\n```\n\nThe 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:\n\n```nunjucks\n---\npagination:\n  data: ghost.tags\n  size: 1\n  alias: tag\npermalink: \"/{{ tag.slug }}/\"\n---\n\n\u003ch1\u003e{{ tag.name }}\u003c/h1\u003e\n\u003cul\u003e\n  {% for post in ghost.posts | filterPosts(\"tags\", tag.slug) %}\n    \u003cli\u003e\u003ca href=\"/{{ post.slug }}/\"\u003e{{ post.title }}\u003c/a\u003e\u003c/li\u003e\n  {% endfor %}\n\u003c/ul\u003e\n```\n\nA 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](https://www.11ty.dev/docs/data-frontmatter/#alternative-front-matter-formats) and checks if a post has an internal tag with the slug `hash-internal-tag` and prevents the post from rendering:\n\n```nunjucks\n---js\n{\n  pagination: {\n    data: \"ghost.posts\",\n    size: 1,\n    alias: \"post\",\n    before: function(data) {\n      return data.filter(post =\u003e post.internalTags.every(tag =\u003e tag.slug !== \"hash-internal-tag\"));\n    }\n  },\n  permalink: \"/{{ post.slug }}/\"\n}\n---\n\n\u003ch1\u003e{{ post.title }}\u003c/h1\u003e\n{{ post.html | safe }}\n```\n\nCheck out the demo directory of this project for more extensive examples.\n\n## Development\n\n1. Create a `.env` file inside of `demo` with the following credentials:\n\n   ```text\n   GHOST_URL=https://demo.ghost.io\n   GHOST_KEY=22444f78447824223cefc48062\n   ```\n\n2. Amend the `.eleventy.js` file within `demo` so it points to the source code in the parent directory:\n\n   ```js\n   // const pluginGhost = require(\"../\");\n   const pluginGhost = require(\"eleventy-plugin-ghost\");\n   ```\n\n3. Install the demo dependencies:\n\n   ```text\n   cd demo\n   npm install\n   ```\n\n4. Run the demo locally:\n   ```text\n   npm run dev\n   ```\n","funding_links":[],"categories":["others"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdaviddarnes%2Feleventy-plugin-ghost","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdaviddarnes%2Feleventy-plugin-ghost","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdaviddarnes%2Feleventy-plugin-ghost/lists"}