Spirit

Ghost's style guide, CSS framework, and component library.

Usage

Node/Express apps

First, install the package 🙂

yarn add -D --exact ghost-spirit

From here there are multiple entry points depending on the use case but typically you'll want a setup something like this:

bootstrap/index.js:

const spirit = require('ghost-spirit');
const hbs = require('express-hbs');

spirit.registerHelpers('brand', {hbs});

gulpfile.js

const spirit = require('ghost-spirit');

gulp.task('css', function () {
    gulp.src(['assets/css/app.css'])
        .pipe(spirit.gulpPostcss())
        .pipe(gulp.dest('public/'));
})

resources/assets/css/app.css

@import "spirit-brand.css";

NB: If you want the product styles rather than brand styles swap instances of brand for product, eg:

spirit.registerHelpers('product', {hbs});

@import "spirit-product.css";

Advanced config

If you need to modify the default Spirit postcss config you can do so like this:

let spirit = require('spirit');

gulp.task('css', function () {
    let config = spirit.postcssPluginConfig();

    // modify options for a default plugin
    config.options['autoprefixer'].browsers = ['last 1 versions'];

    // add a new plugin in a specific order, eg, before minification
    config.plugins.splice(config.plugins.indexOf('cssnano'), 0, 'css-awesome');
    config.options['css-awesome'] = {
        emojify: true
    };

    // remove a plugin
    config.plugins.splice(config.plugins.indexOf('cssnano'), 1);

    // finally pass the config as a param to spirit.gulpPostcss
    gulp.src(['assets/css/app.css'])
        .pipe(spirit.gulpPostcss(config))
        .pipe(gulp.dest('public/'));
});

Ember.js apps

See https://github.com/TryGhost/ember-cli-ghost-spirit

Development

yarn && cd components/SearchInput && yarn && cd ../../

Run

• Either dev mode: yarn dev
• Or standard server: yarn start
• View: http://localhost:9999

Publish

• yarn ship

Search-Input component

The search box is a Glimmer.js component that can be found in /components/SearchInput. It's implementation is entirely client-side using a generated JSON file as the search index that is built as part of the standard gulp tasks.

The component is built as part of the default gulp tasks using the correct environment based on the NODE_ENV env var so there's no extra steps needed unless you want to modify the search component.

Updating the search data

The search index is generated from YAML front-matter located in the product view files. Each view file that you want to appear in the search results should have three pieces of data in the front-matter:

• url (optional) - a relative URL where this entry can be located, if it's omitted then it will be calculated based on the file path
• title - the text that should appear in the search results and is used for matching
• keywords - any additional words that should be used for matching (can also be useful for providing alternatives, eg English/American spelling)

An example of the front-matter format from /resources/views/product/classes/font-weight.hbs:

---
title: Font Weight
keywords:
    - font-weight
    - typography
---

... view content ...

For this example the url will be generated as /product/classes/font-weight/. Note that the keywords includes a form that matches the CSS naming (font-weight), this is so that including the - in the search query will still match.

Developing the component

To start the Glimmer.js development server run the following:

• cd components/SearchInput
• ember serve

You can then access http://localhost:4200 where you can see a dummy sidebar containing the search component. Any changes you make to the component code will live-reload this screen.

It's also possible to run both the Spirit server and Glimmer.js dev server at the same time in two terminal tabs. If you do this then the Spirit pages will also livereload when the search component is rebuilt.

There are two primary files where 95% of the component development will occur:

• components/SearchInput/src/ui/components/SearchInput/component.ts
• components/SearchInput/src/ui/components/SearchInput/template.hbs

Differing class lists for the product/brand search inputs are defined in:

• components/SearchInput/src/ui/components/SearchInputProduct/template.hbs
• components/SearchInput/src/ui/components/SearchInputBrand/template.hbs

Glimmer.js doesn't yet allow passing through attributes via web component attributes so the above is a little hack so that we can have different input styles without unnecessary duplication.