Using Jekyll with Tailwindcss on GitHub Pages

In this article, I explain how to run a Jekyll blog that is using Tailwindcss on GitHub Pages.

Prerequisites

• Having Jekyll installed (Installation | Jekyll • Simple, blog-aware, static sites (jekyllrb.com))
• Have a GitHub account

Step 1: Run it locally

First, generate a new Jekyll blog, you can use this command:

jekyll new myBlogWithTailwind --blank

Go to the generated project directory and generate a Gemfile:

bundle init

Edit the Gemfile by adding this line: gem “jekyll”.

After that, you can create a package.json file and install the required dependencies (tailwindcss, postcss, postcss-import, autoprefixer):

npm init
npm install tailwindcss@latest postcss@latest autoprefixer@latest postcss-import@latest --save-dev

Now that you have tailwind installed, you can generate its configuration file tailwind.conf.js by running:

npx tailwindcss init

Now edit the Gemfile and add this: gem “jekyll-postcss”, then run:

bundle install

After that, you have to add jekyll-postcss in the plugins list in Jekyll’s configuration file _config.yml:

plugins:
  - jekyll-postcss

At the root of the project directory, create a file named postcss.config.js and add the following lines:

Last step is to import Tailwindcss stylesheets in the main.scss file (assets/css/main.scss).

Now that everything is configured, let’s try to add some tailwind classes (text-center, text-red-500, text-2xl) in the default.html files:

<div class="text-center text-red-500 text-2xl">Hello World</div>

Serve the website with this command:

bundle exec jekyll serve

You should now have your blog running on http://localhost:4000.

Congratulations 🎉 You now have your Jekyll blog using Tailwindcss !

Step 2: Run it on GitHub Pages

First of all, create a new public repository in GitHub and push your project. Here is an example of a .gitignore file:

If you activate now GitHub Pages on your repository, you may have an error: File to import not found or unreadable: tailwindcss/base

Indeed, Tailwindcss stylesheets are located in the nodes_modules folder that is not present on the repo (best practice is to add nodes_modules in the .gitignore). We can bypass this error by using GitHub Actions and modify some Jekyll configuration.

First, edit the _config.yml file and add this(don’t forget to push your modifications):

Next, you have to create a GitHub Action with these three steps:

• Installation of dependencies: we will run a simple script npm install.
• Build the Jekyll website: we will use the Jekyll GitHub Action proposed by default.
• Deploy the blog on GitHub Pages: we are going to use an action developed by CrazyMax → GitHub Pages

This is the action:

The last step of the action will publish your builded website on a new git branch. By default it’s called gh-pages. So you have to change the target branch in the repository settings > Pages.

Now, everything should be OK! You can access your blog on this url: https://<username>.github.io/<your-repo>.

Example: https://mehdiha.github.io/jekyll-tailwind-ghpages/

If you have a 404 error loading the css file, make sure that you have the right baseurl in the _.config.yml file. Usually you have to set the name of your repo. In my case, it’s: “/jekyll-tailwind-ghpages”. And in the main html file, verify that you load the css file like this:

<link rel="stylesheet" href="{{site.baseurl}}/assets/css/main.css">

You can check the complete project in my repo: mehdiha/jekyll-tailwind-ghpages (github.com)