Hugo Starter Theme with Tailwind CSS

Starter files for a Hugo theme with Tailwind CSS.

• set up to use Tailwind CSS - v2.0+
• includes the @tailwindcss/typography plugin for styling of markdown content
• use Hugo Pipes to build and load css based on

  dev

  or

  build

  environment
• purge unused css classes with PurgeCSS for

  build

  , but not in

  dev

• works as separate theme repo or as a local theme folder within a Hugo site
• basic template setup with an index page, an about page and a posts category
• responsive navigation header ~~with minimal javascript~~ with pure css to hide the nav on small screens
• to keep that s***er down, the theme features a sticky footer
• included helper partials to show Hugo parameters and Tailwind CSS breakpoints during development

Live long and code.

What this theme is NOT

This theme is a starter setup theme to aid in developing Hugo themes using the Tailwind CSS framework. It is not a standalone theme ready to use.

Prerequisites

Make sure to install

postcss-cli

autoprefixer

npm install -g postcss-cli
npm install -g autoprefixer

Make sure to use a minimum Hugo version of v0.69.0 and above.

Set the

writeStats

config

/exampleSite/config.toml

[build]
  writeStats = true

Basic usage to develop a separate Theme repo

• clone and rename the repo

git clone https://github.com/dirkolbrich/hugo-theme-tailwindcss-starter new-theme-name

• to make that theme your own, switch into the newly created folder, remove the git history from this starter repo and initiate a new git repo

cd new-theme-name
rm -rf .git
git init

• now install the necessary node packages

npm install

• edit the

  config.toml

  file in

  exampleSite/

  to reflect the

  new-theme-name

# in config.toml
theme = "new-theme-name" # your new theme name here

• start a server to develop with

  exampleSite

hugo server -s exampleSite --themesDir=../.. --disableFastRender

Usage directly within a Hugo repo as a theme package

• start a new Hugo site

hugo new site new-site

• switch into the theme folder an clone the starter repo

cd new-site/themes
git clone https://github.com/dirkolbrich/hugo-theme-tailwindcss-starter new-theme-name

• switch into the newly created theme folder, remove the git history from this starter repo and install the node packages

cd new-theme-name
rm -rf .git
npm install

• edit the

  config.toml

  file in

  new-site/

  to reflect the new-theme-name

# in config.toml
theme = "new-theme-name" # your new theme name here

• switch to the root of the new-site repo and start a server to view the index site

cd new-site
hugo server --disableFastRender

Your content should go into

new-site/content

new-site/themes/new-theme-name/layout

Helpers

Included are the following helpers for the development phase (not visible in production):

• /partials/dev-parameters.html

  , which shows basic Hugo page parameters

• /partials/dev-size-indicator.html

  , which displays a floating circle in the upper right corner to indicate the Tailwind CSS responsive breakpoints

If you don't need any of these helpers anymore, just delete the corresponding line from

/layouts/_default/baseof.html

Deploy to Netlify

If you use this starter theme and want to deploy your site to Netlify, you MAY encounter a build error which contains the following line:

ERROR {your deploy time here} error: failed to transform resource: POSTCSS: failed to transform "css/styles.css" (text/css): PostCSS not found; install with "npm install postcss-cli". See https://gohugo.io/hugo-pipes/postcss/

That is, Netlify doesn't know the

npm

package.json

{
    "name": "my-site",
    "version": "0.0.1",
    "description": "that is my-site",
    "repository": "https://github.com/you/my-site",
    "license": "MIT",
    "devDependencies": {
        "@fullhuman/postcss-purgecss": "^3.1.3",
        "@tailwindcss/typography": "^0.3.1",
        "autoprefixer": "^10.2.0",
        "postcss": "^8.2.3",
        "postcss-cli": "^8.3.1",
        "postcss-import": "^14.0.0",
        "tailwindcss": "^2.0.2"
    },
    "browserslist": [
        "last 1 version",
        "> 1%",
        "maintained node versions",
        "not dead"
    ]
}

This introduces the dependencies Tailwind CSS and PostCSS need, Netlify will run the installation automatically on deploy.

Environment variables

To make the distinction between

development

production

HUGO_ENV = "production"

Settings

Build & deploy

Environment

Or use a

netlify.toml

How does that work anyway?

Within

postcss.config.js

purgecss

HUGO_ENVIRONMENT === 'production'

const themeDir = __dirname + '/../../';

const purgecss = require('@fullhuman/postcss-purgecss')({
    // see https://gohugo.io/hugo-pipes/postprocess/#css-purging-with-postcss
    content: ['./hugo_stats.json'],
    defaultExtractor: (content) => {
        let els = JSON.parse(content).htmlElements;
        return els.tags.concat(els.classes, els.ids);
    }
})
module.exports = {
    plugins: [
        require('postcss-import')({
            path: [themeDir]
            }), 
        require('tailwindcss')(themeDir + 'assets/css/tailwind.config.js'),
        require('autoprefixer')({
            path: [themeDir],
            grid: true
        }),
        ...(process.env.HUGO_ENVIRONMENT === 'production' ? [purgecss] : [])
    ]
}

During the build process Hugo Pipes checks this variable too and build the

styles.css

/layouts/partials/head.html

{{ $styles := resources.Get "css/styles.css" | postCSS (dict "config" "./assets/css/postcss.config.js") }}
{{ if .Site.IsServer }}
    
{{ else }}
    {{ $styles := $styles| minify | fingerprint | resources.PostProcess }}
    
{{ end }}

Reference

Documentation for Hugo's PostCSS setup.