Skip to content

Instantly share code, notes, and snippets.

@Coding-Koala222

Coding-Koala222/github-pages-with-tailwind-tutorial.md

Last active April 27, 2026 06:59
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save Coding-Koala222/32c68fe4f7a4fd9276182d2c02bfe1f3 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save Coding-Koala222/32c68fe4f7a4fd9276182d2c02bfe1f3 to your computer and use it in GitHub Desktop.
Download ZIP
GitHub Pages: How to Convert a Temporary CDN-Based Tailwind Site to a Permanent GitHub Actions Workflow-Based Site
Raw
github-pages-with-tailwind-tutorial.md

GitHub Pages: How to Convert a Temporary cdn.tailwindcss.com or cdn.jsdelivr.net-Based Tailwind Site to a Permanent GitHub Actions Workflow-Based Site

This guide will show you how to permanently set up Tailwind CSS for your static HTML site using a GitHub Actions workflow. It includes configuration and troubleshooting.

Prerequisites

This guide assumes that you already have the following line of code in the <head> section of your HTML file, per the official CDN setup instructions.

<script src="https://cdn.jsdelivr.net/npm/@tailwindcss/browser@4"></script>

This setup process automatically implements Classpresso ☕, a post-build Tool that makes Tailwind CSS rendering up to 50% faster! You can learn more about it on their GitHub repository.


Why shouldn't I keep using cdn.tailwindcss.com or cdn.jsdelivr.net? It seems to be working fine.

The reason you would switch to a GitHub actions workflow-based approach isn't because CDN doesn't work. It's because it's not designed for production use:

  • Performance: The CDN version compiles Tailwind CSS in the browser every time the page loads, which is slow. A pre-built CSS file loads instantly.

  • Reliability: You're dependent on Cloudflare's CDN staying up. If it goes down, your styles break.

  • File size: The CDN version includes the entire Tailwind compiler (~70KB). A built CSS file with only the styles you actually use is much smaller (often <20KB after minification).

  • Production best practice: Pre-built assets are the standard for any real website or project you deploy.

1. Remove the CDN from Your HTML

In your index.html, find and remove:

<script src="https://cdn.jsdelivr.net/npm/@tailwindcss/browser@4"></script>

Replace it with:

<link rel="stylesheet" href="./dist/output.css">

This will load your own pre-built Tailwind CSS, which you'll generate in the next steps.

2. Add the GitHub Actions Workflow

Go to repository settings > actions > general and scroll down to Workflow permissions

Choose Read and write permissions

Click Save

3. Add the Necessary Files to Your Repo

Starting at the root of your repository, you need these files/folders:

my-repo/
├──.github
│   └── workflows
│       └── build-css.yml
├── pages/
│   └── index.html
├── src/
│   └── input.css
├── dist/
│   └── output.css   # (will be generated by workflow)
├── tailwind.config.js
└── package.json

.github/workflows/build-css.yml

Create a file called build-css.yml in the folder .github/workflows:

name: Build, Optimize with Classpresso, and Deploy

on:
  push:
    branches:
      - main

jobs:
  Build Tailwind CSS:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v6
        with:
          node-version: 24

      - name: Install dependencies
        run: npm install

      - name: Build Tailwind CSS
        run: npx tailwindcss -i ./src/input.css -o ./dist/output.css

      - name: Commit and push
        run: |
          git config user.email "action@github.com"
          git config user.name "GitHub Action"
          git add dist/output.css
          git commit -m "Build CSS" || echo "No changes to commit"
          git push || echo "Nothing to push"

  Build Webpage and Deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v6
        with:
          node-version: 24

      - run: npm install

      # Build your static site
      - name: Copy pages to public "dist" folder
        uses: canastro/copy-file-action@master
        with:
          source: pages/.
          target: dist/
          flags: '-r'

      - name: Ensure writable dist
        run: sudo chown -R $USER:$USER dist

      # Optimize classes in built HTML and CSS
      - name: Optimize HTML with Classpresso
        run: npx classpresso optimize --dir dist

      # Deploy to GitHub Pages
      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./dist
          user_name: 'GitHub-Actions Deploy [bot]'
          user_email: 'github-actions[bot]@users.noreply.github.com'

src/input.css

Create a file called input.css in the src folder:

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

tailwind.config.js

Create a file called tailwind.config.js at the root of your repository:

module.exports = {
  content: [
    "./**/*.html",
  ],
  theme: {
    extend: {},
  },
  plugins: [],
}

package.json

Create a file called package.json at the root of your repository:

{
  "name": "berkeley-build-guild-website",
  "version": "1.0.0",
  "devDependencies": {
    "autoprefixer": "^10.0.0",
    "classpresso": "^1.7.2",
    "postcss": "^8.0.0",
    "tailwindcss": "^3.0.0"
  }
}

4. Set-Up GitHub Pages Settings

  • Go to Settings > Pages in your repo.
  • Under Build and deployment, set the source to GitHub Actions.
  • Make a commit to trigger the workflow to build the website.

If the live website doesn't update right away, try waiting a minute and then refreshing the webpage. It can take a little while for GitHub to build the website.

5. Commit and Push Your Changes (If using command line)

git add .
git commit -m "Set up Tailwind workflow build"
git push

Otherwise, you can use GitHub's web interface to create/edit files and commit changes.

That’s it!

You now have a permanent, version-controlled Tailwind setup. No more CDN!

Troubleshooting

  • No styles?

    • Make sure dist/output.css exists and is large (not empty).
    • Hard refresh your page (Ctrl+Shift+R).
    • Check the "Build, Optimize with Classpresso, and Deploy" workflow logs for errors.

  • Classes not working?

    • Confirm your tailwind.config.js has the right content globs.
    • Confirm src/input.css is in the correct location and not empty.

  • Workflow errors?

    • Ensure all files are in the repo.
    • Make sure the package.json is valid JSON (use the code provided above).
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment