Netlify Ghost Markdown Build Plugin

This plugin generates posts, pages, tag pages and author pages from a Ghost publication as markdown files, using the Ghost Content API. In addition it will copy images from the Ghost publication into a local assets directory. Pages, posts, tag pages, author pages and images will be generated on the onPreBuild event in the Netlify deployment cycle, this is to ensure the files are present before an actual build occurs.

Prerequisites

Before you can use this package you'll need a Netlify project that can consume markdown files and images. This package was built with Jekyll in mind, however in theory it should work with any static site generator :sparkles:. Additionally you'll need the Netlify CLI tool installed and Build Plugins Beta enabled.

Installation

To install, add the following lines to your netlify.toml file:

[[plugins]]
package = "netlify-plugin-ghost-markdown"

   [plugins.inputs]
   ghostURL = "https://YOURGHOST.URL"
   ghostKey = "YOURGHOSTKEY"

Note: The [[plugins]] line is required for each plugin, even if you have other plugins in your netlify.toml file already.

You'll need to get a Ghost Content API URL and key to authenticate with your Ghost publication. Please see the Ghost documentation for more info.

Psst, test credentials can be "borrowed" from here: https://ghost.org/docs/api/v3/javascript/content/#working-example

Configuration

[[plugins]]
package = "netlify-plugin-ghost-markdown"

  [plugins.inputs]
  # Required: Your Ghost domain, must not end in a trailing slash
  ghostURL = "https://YOURGHOST.URL"

  # Required: Content API key from the Integrations screen in Ghost Admin
  ghostKey = "YOURGHOSTKEY"

  # Optional: Directory containing image assets (assets/images by default)
  assetsDir = "./assets/images/"

  # Optional: Directory containing pages (site root by default)
  pagesDir = "./"

  # Optional: Directory containing posts (_posts/ directory by default)
  postsDir = "./_posts/"

  # Optional: Output tag pages (false by default)
  tagPages = false

  # Optional: Output author pages (false by default)
  authorPages = false

  # Optional: Directory containing tags (tag/ directory by default)
  tagsDir = "tag/"

  # Optional: Directory containing authors (author/ directory by default)
  authorsDir = "author/"

  # Optional: Layout value for pages (page by default)
  pageLayout = "page"

  # Optional: Layout value for posts (post by default)
  postsLayout = "post"

  # Optional: Layout value for pages (page by default)
  tagsLayout = "tag"

  # Optional: Layout value for posts (post by default)
  authorsLayout = "author"

  # Optional: Date prefix on post file names (true by default)
  postDatePrefix = true

  # Optional: File path and name for a timestamp caching file (_data/ghostMarkdownCache.json by default)
  cacheFile = "./_data/ghostMarkdownCache.json"

Currently posts follow the Jekyll markdown file name format. Set the postDatePrefix to false to use the post slug as the file name

Development

Testing inside the project is proving difficult at the minute. Currently requesting support on a practical method here

Currently you need clone this project and copy the plugin into an example site, copy the package.json into the root of the project, and then run it like a custom build plugin. You can download the demo site here if you need it as a quick starting point. Don't forget to install the dependencies and run it using Netlify CLI!

License

Released under the MIT license.