In this guide, we’ll take an in-depth look at TailwindCSS, a powerful utility-first CSS framework that allows developers to quickly create custom, extensible, and beautiful Ghost themes without writing a line of CSS.

TailwindCSS is a highly customizable CSS framework, making it easy to tailor designs to any project. It offers a wide range of features, such as responsive breakpoints, custom color palettes, and more. Additionally, TailwindCSS provides a ton of resources to help developers get up and running quickly.

Installing Ghost

Installing Ghost locally is quick and easy using the command line. To view the full list of prerequisites for installing Ghost, refer to this article.

Once you’ve met those prerequisites, open up your terminal and run the following command:

npm install ghost-cli@latest -g

This will install the Ghost-CLI command line tool to help you get Ghost installed and configured. Next, cd into an empty directory and run the install command:

ghost install local

This will download and install the latest version of Ghost in your local environment. Once the installation is complete, you’ll be able to access your new site at http://localhost:2368.

Creating up a New Theme

Once your local Ghost site is up and running, let’s continue in the command line and install the official Starter Theme by Ghost. This will provide the necessary structure as a starting point for our development.

cd content/themes
git clone https://github.com/TryGhost/Starter.git ghost-starter-with-tailwind

With this command, Git will create a directory named ghost-starter-with-tailwind in your themes directory and clone all contents from the remote repository into that directory.

The Ghost Starter Theme uses yarn to manage its dependencies. To install these dependancies, cd into your new theme directory and then run the following command:

cd ghost-starter-with-tailwind
yarn install

This will download and install the necessary packages for the theme.

Installing Tailwind

After your theme is created, you’ll be ready to install TailwindCSS and the typography plugin (needed for styling post content output) with the following commands:

yarn add tailwindcss
npm install -D -s @tailwindcss/typography
npx tailwindcss init

The first two commands install the packages we need and the last command, npx tailwindcss init will create an initial tailwind.config.js file. This config file is used to add extensions or customize Tailwind by adding new font sizes, colors, etc…

Now that Tailwind is installed, we need need to import the Tailwind CSS files. We can do this by adding the following three @tailwind lines at the very top of the assets/css/screen.css file.

@tailwind base;
@tailwind components;
@tailwind utilities;

/*
This is a development CSS file which is compiled to a minified
production stylesheet in assets/built/screen.css using: gulp dev
*/

...

The last step to config Tailwind is to modify the default tailwind.config.js file to ensure it’s compatibility with handlebar templates used by Ghost themes as well as enable the typography plugin we instead earlier. Open the tailwind.config.js file and replace it’s contents with the following:

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: ["./*.hbs", "./**/*.hbs"],
  theme: {
    extend: {}
  },
  plugins: [
    require('@tailwindcss/typography')
  ],
}

Adding Tailwind to Gulp

The Ghost Starter Theme uses gulp.js for build tasks. To add Tailwind to the gulp.js build chain, we need to adjust the gulp configuration file. Below the comment // postcss plugins in gulpfile.js, add:

// postcss plugins
var autoprefixer = require('autoprefixer');
var colorFunction = require('postcss-color-mod-function');
var cssnano = require('cssnano');
var easyimport = require('postcss-easy-import');
var tailwindcss = require('tailwindcss'); // add this line for Tailwind

We’ll also need to update the function css() starting at line 38 and include tailwind() as part of the processors array:

function css(done) {
  var processors = [
    easyimport,
    colorFunction(),
    tailwindcss(), // add this line for Tailwind
    autoprefixer(),
    cssnano()
  ];

...

Finally, we need to ensure the css() function is executed after changes to our Handlebar template files so that any added Tailwind styles are compiled. To do this, modify the hbs() function on line 32 and add the commented line:

function hbs(done) {
  pump([
    src(['*.hbs', '**/**/*.hbs', '!node_modules/**/*.hbs']),
    livereload()
  ], handleError(done));
  css(done); // add this line for Tailwind
}

Let’s also tell gulp to watch for changes in our Handlebar templates on around line 83 change this line:

const watcher = parallel(cssWatcher);

To this:

const watcher = parallel(cssWatcher, hbsWatcher);

Now we can restart Ghost and start the gulp tasks that will watch for future changes and recompile your theme automatically:

ghost restart
yarn dev

Tailwind and Ghost Content

One caveat to using Tailwind and Ghost is the challenge with styling post {{content}}. Since this content is being generated by Ghost and we don’t have direct access to the output to apply Tailwind classes, the Tailwind typography plugin comes in handy. This allows us to apply a set of default Tailwind styles to HTML output that we don’t have control over.

Since we’ve already installed and enabled this plugin in earlier steps, to use it, open up the post.hbs template file and around line 34 add the prose class to the div surrounding the {{content}} output:

<div class="gh-content gh-canvas prose">
  {{content}}
</div>

There are a number of modifiers available for you to customize the style of every outputted tag, so be sure to explore the documentation for the typography plugin for all the available options.

Tailwind and Ghost Cards

One of the highlights of Ghost is it’s extensive selection of editor cards you can use to pull in dynamic content. The Ghost Starter Theme includes default styling for these various cards, however, there may be cases where you’d like to override these styles in favor of your own.

For example, the default Button card features slightly rounded corners that I want to make fully rounded.

This can easily be done by first identifying the class name of the button card, which you can do by locating it on this page. Here we can see the button card is a container with the class kg-card.kg-button-card with the actual button being a link with the class of kg-btn.

<div class="kg-card kg-button-card kg-align-center">
  <a href="#" class="kg-btn kg-btn-accent">Checkout This Button</a>
</div>

Let’s open up our assets/css/screen.css file and at the bottom of the file add the following block of code:

.kg-card.kg-button-card a.kg-btn {
  @apply rounded-full;
}

By using the @apply function included with Tailwind, we can apply any Tailwind style to any CSS selector.

And voila! We have a rounded button that overrides the default Ghost style with Tailwind classes. Now you can free apply this same technique to any other Ghost card.

Are you using TailwindCSS for your Ghost blog? We’d love to know! Tweet us @layeredcraft!

Eric Alli @ericalli

Eric is the founder of LayeredCraft. He has worked as a designer and engineer for 15+ years and loves creating innovative and effective themes for all industries.