How to Setup TailwindCSS for a Custom Ghost Theme

Matt Lehrer — Sun, 30 Aug 2020 21:30:20 +0000

Ghost has a ton going for it. But existing themes are never exactly right and I wanted to be able to make changes with TailwindCSS and couldn't find a fresh start -- despite finding others looking for this, too. If you're in the same position, this post is for you.

I use the official Ghost Starter Theme as a jumping off point, though you should be able to do this with any existing theme.

You'll need the Ghost CLI installed.



npm install ghost-cli@latest -g

Start by creating a fresh directory.



mkdir ghost-project && cd "$_"

Then install Ghost locally.



ghost install local

After the installation is done, you'll have a running ghost instance at http://localhost:2368

Next create a new repository based on the Ghost Starter Theme using the "Use this template" green button on Github.

cd into the themes directory and clone the new repo, with your username and the name of the repo:



cd content/themes
git clone git@github.com:<your-github-username/<your-new-repo-name>.git ghost-starter-with-tailwind

The default Casper theme will be in that directory as a sibling, if you want to see how that theme handles anything.

The Ghost Starter Theme uses yarn, so use that to install dependencies. cd into your new theme directory and then run yarn:



cd ghost-starter-with-tailwind
yarn

This is a good time to change the name of the theme to whatever you'd like. The name field at the top of the package.json ('ghost-starter-theme' when you open the file) is what shows up in Ghost's admin interface.

You can now install and setup Tailwind.



yarn add tailwindcss
npx tailwindcss init

Add the Tailwind base styles to ./assets/css/screen.css:



/* assets/css/screen.css */

/* ... */

/* Base components */
@import "vars.css";
@import "components/global.css";
@import "components/forms.css";
@import "components/buttons.css";

/* Ghost components */
@import "ghost/header.css";
@import "ghost/content.css";
@import "ghost/readmore.css";
@import "ghost/members.css";
@import "ghost/errors.css";
@import "ghost/footer.css";
@import "ghost/badge.css";

/* Tailwind - add this part */
@import "tailwindcss/base";
@import "tailwindcss/components";
@import "tailwindcss/utilities";

/* ... */

As you replace styles with Tailwind classes, you can remove the other imports but leave them there for now.

The Starter uses Gulp and gulp-postcss, so we'll roughly follow that part of the Tailwind installation instructions:



// gulpfile.js

// import tailwind at the top of the file
const tailwind = require('tailwindcss')

// ...

// add tailwind to the css processors list, around line 43:
function css(done) {
    var processors = [
        easyimport,
        colorFunction(),
        tailwind(), // add this
        autoprefixer(),
        cssnano()
    ];

    // ...
}

Next, restart ghost to make sure we're catching all the new files and the name change on the theme, if you made one. It shouldn't matter what your working directory is. You can run this from the theme directory.



ghost restart

Then start all the theme file watchers, so that changes to css and the handlebars files are picked up by Ghost. This you have to run from the theme directory (/content/themes/ghost-starter-with-tailwind or whatever you named it).



yarn dev

Setup Ghost admin with a name for the admin and the blog, an email and a password at http://localhost:2368/ghost and then hit skip at the bottom of the next page when it asks to invite teammates.

Almost done now. Go into Ghost's settings and activate the new theme. Click into Settings > Design.

And then all the way at the bottom of the Design Settings page, click activate on the new theme.

Finally, you can start adding Tailwind classes to your handlebars templates. If something doesn't work quite right, try removing CSS and imports from screen.css. Your changes should be picked up by the watchers, but there's no autoreload in the browser. So refresh after saving any changes.

This should get you started. I have the code to this point on Github.

I'll follow up with another post on how I converted the existing CSS to Tailwind, adding Tailwind's typography plugin for a good starting point for post pages, and purging unused CSS on Ghost Pro, which required manual purging when I used it.

DEV Community: Matt Lehrer

How to Setup TailwindCSS for a Custom Ghost Theme