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
orbuild
environment - purge unused css classes with PurgeCSS for
build
, but not indev
- 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 javascriptwith 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.
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.
Make sure to install postcss-cli
and autoprefixer
globally in your environment, as Hugo Pipe’s PostCSS requires it. This is mentioned in the Hugo Docs.
npm install -g postcss-cli
npm install -g autoprefixer
Make sure to use a minimum Hugo version of v0.69.0 and above.
- 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 inexampleSite/
to reflect thenew-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
- 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 innew-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
, the development of the site layout is done within new-site/themes/new-theme-name/layout
.
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
.
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
dependencies of this starter theme yet. For this to fix, please add a package.json
file to the root of your repo with the content:
{
"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.
To make the distinction between development
and production
environments work, add an environment variable HUGO_ENV = "production"
to your site settings under Settings
→ Build & deploy
→ Environment
.
Or use a netlify.toml
for a file-based configuration.
With the latest version of Hugo v0.69.0 and Tailwind CSS v1.4. the setup for Tailwind CSS and the PurgeCSS process does not need two separate postcss.config.js
versions any more. The setup is now done within one file.
Within postcss.config.js
a purgecss
function is defined, which is only called based on the environment variable HUGO_ENVIRONMENT === 'production'
.
const themeDir = __dirname + '/../../';
const purgecss = require('@fullhuman/postcss-purgecss')({
... // see Tailwind CSS documentation for the PurgeCSS extractor
})
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
with some additional minification. This snippet is located in /layouts/partials/head.html
.
{{ $styles := resources.Get "css/styles.css" | postCSS (dict "config" "./assets/css/postcss.config.js") }}
{{ if .Site.IsServer }}
<link rel="stylesheet" href="{{ $styles.RelPermalink }}">
{{ else }}
{{ $styles := $styles| minify | fingerprint | resources.PostProcess }}
<link rel="stylesheet" href="{{ $styles.Permalink }}" integrity="{{ $styles.Data.Integrity }}">
{{ end }}
Documentation for Hugo's PostCSS setup.
Documentation for Tailwind CSS setup of calling PurgeCSS manually.