search

mixu / ghost-render

Render static blog sites from Markdown using Ghost themes
224 stars 21 forks source link

readme

ghost-render

Renders static blog sites from Markdown using Ghost themes.

Features

Changelog

v.1.1.0: added a missing dependency to package.json

Getting started

Install ghost-render: 

npm install -g ghost-render

Initialize a basic settings JSON file (mostly for Ghost-specific settings):

ghost-render --init > settings.json

Download a Ghost theme. There are a number of free and paid Ghost themes - I'll use the default Casper theme from Ghost here:

git clone https://github.com/TryGhost/Casper.git

Create some content:

mkdir -p ./blog/2014/01/30/
echo "# Hello world\n YOLO" > ./blog/2014/01/30/hello-world.md

Run ghost-render:

ghost-render --input ./blog/ --settings ./settings.json --theme ./Casper --output ./tmp

Open up the result in a browser (mostly because of file:// URL security issues). Any HTTP server will work, I'll use the one built into Python:

cd ./tmp
python -m SimpleHTTPServer 5000

All done; here's a screenshot of the result:

screenshot

The resulting output

The output HTML is fully static. This means that you could, for example, point a HTTP server at the output folder and be done with it or push the output folder to Amazon S3.

For example, here is how I deploy my own blog: aws s3 sync ./output/ s3://some-s3-bucket/some-folder/ --delete --exclude "node_modules/*" --exclude ".git" (assuming credentials are in the necessary environment variables and that the AWS CLI is installed).

Adding metadata to each post

Each blog post can have metadata associated with it. To set the metadata, start your markdown file with a metadata block that looks like this:

---
title: Page title
published_at: 2014-01-30 11:26:04
author: foo
tags: foo bar
---

All of the post metadata is optional - see below for the fallback values.

You can also write HTML inside the posts and it will be included in the rendered page as-is. This can be handy for those moments where you need to produce very specific markup.

title

title is used as the page title in the templates and the <title> tag.

The first heading in the markdown file is used if title is not set. If there is no first heading, the file name is used (without the file extension).

published_at

published_at determines the sorting order for posts, and it is used in the index templates to show when a post was made.

If published_at is not set, it is detected from the file path. If your file paths contain numbers that look like yyyy-mm-dd, then you don't need to explicitly set the published_at metadata value.

Some examples of acceptable paths which are automatically parsed if the published_at value is missing:

If this detection fails to produce a result, the creation time of the file is used.

author

author refers to an author by their short name (slug). It is used to fetch the author's metadata from the settings.json file, which will then be rendered by most templates as an author blurb somewhere in the page.

A per-author index of posts is generated for each author at /author/:slug/ (e.g. /author/mixu/). An associated RSS feed is also generated at /author/:slug/rss/. You can set the slug in settings.json.

If you leave the field blank, the author with the name default will be used (e.g. authors.default in settings.json).

tags

tags contains a space-separated (foo bar) or comma-separated (foo, bar) list of tags. Each tag becomes a paginated collection of posts grouped by tag and sorted by published_at. The tag URL slug is generated by lowercasing the tag name and then replacing all non-alphanumeric characters with -.

A per-tag index of posts is generated for each tag at /tag/:slug/ (e.g. /tag/linux/).

If you leave the field blank, there are no tags and no tag index pages.

How post and page URLs are determined

One of the things I dislike about most static site generators is how fiddly it is to get the exact URL structure you want. ghost-render is WYSIWYG in that what you have in your input directory structure is what you get in the output directory structure.

The only change is that .md files will have their extension changed to .html. Other than that, you can implement any directory structure you want, and the generated index pages will adjust to contain the correct URLs to your posts.

You can include non-markdown files. They are automatically copied into the output directory, maintaining the same relative paths.

BTW, if you want /2014/01/30/post-name to work as a link, name your markdown file /2014/01/30/post-name/index.md. This will become /2014/01/30/post-name/index.html, which makes pretty links work as expected.

Indexes are ordered by published_at. See the section on metadata about how this value is automatically detected.

Publishing pages

Everything is a post by default, but you can set page: true in the metadata to render a file as a page. Pages are rendered using the Ghost page template, and they are not included in the post indices.

Publishing drafts

Drafts are posts you’re still working on and don’t want to publish yet.

To mark a page or post as a draft, set draft: true in the metadata section. Drafts are excluded from the rendering pipeline.

Configuring the blog

The blog is configured using the shared settings.json file. The settings.json file should contain the following shared fields:

{
  "blog": {
    "url": "http://blog.example.com",
    "title": "Blog title",
    "description": "Blog description",
    "logo": ""
  },
  "authors": {
    "default": {
      "name": "Author name",
      "bio": "Author bio",
      "website": "http://blog.example.com",
      "image": "http://lorempixel.com/90/90/people/",
      "cover": "http://lorempixel.com/800/600/people/",
      "slug": "nick"    
    }
  }
}

The blog key contains information about the blog's URL, title and location:

The authors key is a hash, indexed by author short name. The authors.default key must be set. The default author is used on all posts that do not have a author: authorname metadata information. To support multiple authors, add more entries to the authors hash and then add the author: somename metadata entry for the posts written by that author.

Customizing the theme

Take a look at the Ghost themes documentation on how to write a theme and the helpers that are available in themes.

ghost-render uses code extracted from Ghost (0.5.x), so it should produce the same result in most cases. I've tested it casually, but not super extensively - if it works on Casper and a couple of other themes I tried so it's good enough for me. File pull requests or issues if you notice themes that don't work as expected.

Ideally, the Ghost core team would package the core rendering functions separately so that simple static sites can take advantage of the same standard for writing themes. Not sure if they are interested, but I'd love to see something cleaner than what I've done here.

Converting a Wordpress blog

I used wp2md to do the initial conversion. The markup requires a bit of touchup:

but other than those manual changes everything was smooth.

What would make this module easier to maintain?

Here are the main things that, if changed in Ghost core, would make this module easier to maintain: