Theme & Codebase Structure

[sarmstead]

The Ruby Central theme is built for Ghost CMS deployment. Before staring development, I recommend reviewing their documentation. They have great information on architecture, view patterns, and routing.

(dramatic pause...)

Okay, lovely! So you've read through the Ghost documentation. Below are several things to keep in mind when developing the Ruby Central theme in particular.

CSS Structure

All CSS lives in ./src/css and is organized by function:

• ./src/css/base houses the lowest-level styles needed for theming the site (things like CSS variables and typographical styles).
• ./src/css/components houses all the styles for reusable parts of the website. You'll see things like shared button, call to action, and divider styles, to name a few.
• ./src/css/layout houses all the styles needed for the skeleton of the site. Here you'll find things like the footer and top navigation styles.
• ./src/css/pages houses styles for individual pages, such as the home and about pages.
• ./src/css/vendors houses all vendored asset styles.
• ./src/css/app.css is where all of the styles ultimately get imported. Keep in mind CSS cascading hierarchy when arranging which imports come before others.

What about JavaScript?

In older versions of Ghost, jQuery came pre-packaged. In newer versions, jQuery has been removed and must be imported manually. For that reason, I recommend that any new JavaScript you create be done with vanilla JavaScript. An example of this is src/js/app/navigation-top.js.

Pages, Pages, Pages

You'll notice a few discrepancies between how the Ruby Central theme creates pages and the way Ghost recommends it. To understand these differences, it is first important to understand the different types of pages that can be created:

• Pages defined under the routes key in the routes file are static handlebar pages.
  • That means that these pages are the closest thing you can get to barebones HTML as possible. You can certainly consume Ghost data with handlebars helpers, but these are the least dynamic page types.
  • Example of these from our theme are home.hbs and about.hbs. More on the routes file can be found in the docs.
• Pages in the Ghost admin dashboard can also use custom templates. Templates are unique in that you can define the "slots" for data to go in and have Ghost fill in those slots for each page created in the dashboard.
  • Examples of custom templates from our theme are any of the files prepended with custom-, which is the Ghost standard.
  • See the Ghost docs for information on themes and custom templates. This article on custom templates is also handy.
• Posts and taxonomical data (tags, authors, etc.) are also served as pages by Ghost. This is very similar to how WordPress has author and tag pages.

For the Ruby Central theme, we use a mix of custom templates and pages defined in the route file. It is up to you as the developer which path you choose to create custom themes. I (@sarmstead) find it easiest to create a static page via the routes file and fill it with dynamic data via pages from the dashboard. An example of this is the about page.

First I define a new route in import/routes.yaml and upload that file to my local Ghost site.

routes:
  ...
  /about/:
    data: page.about
    template: about

Then I can create a new file called about.hbs in the root directory. In that file, I create small editable sections for the maintainers of the site. For example:

<header class='page-about__hero'>
    <div class='page-about__hero__inner'>
        {{#get 'pages' filter="title:'About::Hero - Body'" limit='1'}}
            {{#foreach pages}}
                {{content}}
            {{/foreach}}
        {{/get}}
        ...
    </div>
</header>

Here I query Ghost for a page with the title About::Hero - Body. That has some very basic HTML that get rendered in the {{content}} tag.

Uploading a New Theme

Once your changes to the Ruby Central theme are finished, run npm run zip in the root directory. You can then grab the theme.zip file from ./dist and upload it to Ghost in the admin interface.

A Few Gotchas

• All pages created in the admin dashboard are publicly available on the web. For example, the sponsor page titled Flagrant in the dashboard has a url that maps to https://rubycentral.org/flagrant/. There is no way around this, that I am aware.
• If you add a custom route via routes.yaml and upload it to your Ghost instance locally, you will also need to navigate to the directory where Ghost is installed and run ghost restart.
• A good command to keep handy is npm run check. That command uses Ghosts gscan tool which parses through the theme and detects potential problems.