Giant Robots Smashing Into Other Giant Robots | Will H McMahan

Ghost is a publishing platform, great for personal and professional projects.
Since 2013, the Ghost team has been building a robust tool for crafting content
and sharing it with the digital world.

I first begun using Ghost as soon as it was publicly available and have seen it
grow in to a fantastic solution for the needs of many clients and friends. In
the second half of July 2017, Ghost v1.0.0 was released, and with it came
numerous updates to the editing experience, a refreshed UI, and ever increasing
control of how your work appears on social channels like Facebook and Twitter.

During the past year, we’ve had the opportunity to work with a number of clients
looking to make their blogs better
for their visitors, as well as their authors
and staff. For many of them Ghost was a great fit, and you can check out their
features page to see if what it has to offer meets
your needs. Here’s a quick rundown of some key features that often fall in to
the “must haves” when selecting a platform for a blog or site:

• Ghost is open source, but also has hosted
  options available if you don’t want to run your own server.
• It supports multiples roles for authors, editors, and admins for your whole team.
• You get strong out-of-the-box SEO including support for Facebook Open Graph,
  Twitter Cards, Schema.org, and AMP pages.
• Visitors and your team can subscribe to your site/blog by RSS, Email and Slack.
• Ghost has desktop apps for Mac, PC, and Linux.
• There’s more stuff including a post tags, scheduled publishing, JSON API, XML sitemaps.
• Lest we forget, Ghost theme architecture is flexible and easy to work with
  while allowing you to design your own creative and innovative designs.

Ghost isn’t a blunt instrument that works for every project, but can be the
perfect tool for the right job. To that end, we created our own
Ghost theme template to
help creating your ghost theme a little easier.

Understanding the structure of Ghost themes

Ghost’s default theme is called Casper.
It’s a great theme for getting started using ghost and making your own blog.
However it’s got a substantial amount of code and structure making it less than
ideal for as a starting place for creating new themes.

For this walk-through we’re going to be using thoughtbot’s
ghost-theme-template,
who’s structure is based on that of Casper, with all CSS, and non-essential
html removed.

Core elements

Ghost (and subsequently Ghost themes) have a few core concepts from her which
they build their structure. Most of these are standard elements of any blogging
engine or platform.

• Posts: Referred to as “Stories” within user admin, posts are the base unit
  of Ghost. They’re blog posts… like the one you’re reading… right now.
• Pages: Pages are actually a sub-variant of posts. They have all the same
  properties as posts, but are excluded from the list/index of posts and won’t
  appear on the homepage.
• Authors: Authors are discrete objects that are associated posts and pages.
  The authors in a blog will also have their own pages including their avatar,
  description, and the post they’ve written.
• Navigation: Navigation is user customizable via the Ghost admin. You’re
  able to design a template within your theme for how the navigation manifests
  on each page.
• Tags: Tags can be associated with either posts or pages. Like authors,
  tags get their own page with all the posts that have the relevant tag, as well
  as an optional image and description. When tagging a post, the first tag in
  the series considered the “primary tag,” and can be given special features or
  privileges within the theme.
• Blog Attributes: The blog themselves can also have various attributes that
  are customized via the admin. This includes blog title, blog description,
  logos, and social icons.
• Email Signup: The enabling of email sign-up within the admin is currently
  optional and is by default deactivated. However, you can definitely add
  support for it within your theme. There’re two items associated with email
  subscription. First is a partial, that can be included anywhere throughout
  your site, which will generate a standard e-mail signup form. The second is a
  discrete email subscription page which is also customizable, comes pre-baked
  with a standard look and feel similar to that of the login page.

You also have the ability to customize the login pages for Ghost, but doing so
is typically unneeded for the majority of projects.

Basic structure

The basic document and directory structure of Ghost themes is very similar to
that of most simple web applications. Here’s an outline of the primary files
that make up a Ghost theme.

• /assets: Your theme’s asset directory.
• /partials: Your theme’s partials directory.
  • loop.hbs: The “loop” is the primary post loop. This loop will be used any
    time you’re showing a list of post including the tags page, author page, and
    home page.
  • You can create any partials you want to use in multiple locations throughout
    the site. The ghost-theme-template uses this by having a site-header.hbs
    file to keep the top of the site consistent across the template.
• author.hbs: This is the author page. It contains the author’s name, avatar,
  bio, and a list of post the author has written.
• default.hbs: This is the main layout template file for all pages like the
  home, author, tag, and post pages.
• index.hbs: This is the index/home page. It contains the primary loop that
  will include all non-page posts.
• page.hbs: This is the template for pages (not posts). The overall structure
  of this is often very similar to the post template, but can be customized
  to be quite different.
• post.hbs: This is the template for your posts. Not much to say here; make it great!
• tag.hbs: The final template is for your blog’s tag pages. This page contains
  all of the post associated with a given tag.

Using Gulp with to build your Ghost theme

ghost-theme-template
uses Gulp to add some basic quality of life additions to
your ghost theme development workflow. It comes preconfigured with a few tasks
to get you started. To get the theme up and running you’ll want to cd in to
the theme directory and run npm install to install the theme’s dev
dependencies. If this is your first time using Gulp, be sure to checkout the
getting started docs.

gulp / gulp default

Once the project dependencies have been installed, you have a few tasks
available to you. Running gulp will compile all SCSS files within the /scss
directory. The theme also has Bourbon and
Neat preconfigured, as well as
Autoprefixer. No assembly required. Gulp will
also run JSHint on any of your javascript within the
theme’s /js directory. Once both the asset tasks have been run, Gulp will
continue to watch for changes until terminated.

gulp deploy

So this is the cool part. Running gulp deploy will compile all of your assets,
zip up your theme so you can upload it to ghost (themes can be added to ghost by
way of the admin by uploading a zip file in settings), and will run Ghost’s
official validator, GScan, which will scan
your theme for common issues. If GScan detects any incompatibilities between
your theme and Ghost, it will print the results to the console after the deploy
has completed.

Publishing your Ghost blog

As you build your theme, you’ll want to be running Ghost locally so you are able
to quickly iterate and review changes. Check out the Ghost documentation’s
Set-up Guide
for more info on running ghost locally, but you will first need to install the
ghost-cli.
Once your system is set up, it’s easy to dive in to your projects and generate
new local blogs on the fly.

After you’ve finished your awesome new theme, you can either host your own ghost
instance or use Ghost’s official hosted service
(I do). Once your production app is set up, just upload your theme and your new
blog is ready to go.

If you hit a snag, the Ghost Slack channel is a
lively and helpful community full of people willing to help you get started.

GLHF 👻

Sincerely yours,
Will H McMahan