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
devorbuildenvironment - 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.
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 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.
Set the writeStats option in your Hugo config file, so that purging of CSS classes works in production. See /exampleSite/config.toml as a guideline.
[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.tomlfile 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
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.tomlfile 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.
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 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.
Environment variables
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.
How does that work anyway?
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 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 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 }}
Reference
Documentation for Hugo's PostCSS setup.
Succeeding Netlify Production Build Causes Error...
Hi, Im facing a problem where The First Build Works like charm...
But any succeeding build would cause error
The error is cause by css/css/style.css_STRING file not found in file cache
I need to Manually Deploy the Site by clicking "Clear Cache and Deploy Site" inside netlify...
Any solution to this?
my netlify.toml file looks like this...
error is like this
Error: Cannot find module 'postcss'
Hi dirkolbrich,
Hope you are having a good day
I noticed when using the theme you developed works well in windows env but when I tried this with WSL it fails with below error, would you be able to assist? Error is the same on my project and also the same when I build a new project using your latest repo contents.
error with postCSS
hi,
first, thank you for your theme. in develoment mode my web site work but in production i have a problem.
I have a probleme with postcss :
if i install
my hugo web site don't work in development and in production in netlify
if i run my web site in production i have this error :
i have this error in netlify
could you help me please ? Thank you very munch
Page specific CSS styles file based on front matter
My website requires a particular font stack and colour palette for each project and I've found a way to work with colors by defining them in the frontmatter like so:
These are then propagated to the document by calling them in the
single.htmllike so:This has worked pretty well but I would like to be able to do something similar with fonts. My primary font family in this example is
cocogooseand secondary isrougant. Right now, whenever I want to define new CSS, I'm adding it to thesite.cssfile in assets folder and this is not manageable for a large set of projects.I was thinking it would be better to make it modular and have a custom css file for each project, define the design system in the front matter and define the default font styles/families/sizes to be used like so:
Is this possible? If so, how do I go about setting this up so that on build, Hugo looks for whether the front matter has a
styleparameter and then make sure that Tailwind knows to use styles from that file for this page.Edit: This is a similar question, but I don't know how to translate this into Hugo-speak.
can't evaluate field PostProcess in type interface
Over purged
In the production environment (run
hugo), all the styles generated are as follows:And all style written in templates are missing.
For example
index.htmlBut all works in development env.
How to style the markdown ?
How best to add styles to the tailwind css for blockquote quotes etc for the markdown sections of hugo ?
Is this the right approach ?
https://github.com/iandinwoodie/github-markdown-tailwindcss
Build times are too slow on the example site.
I am following the instructions on the README, but it's taking around 25 seconds to build the example website. I switched from Jekyll + Bootstrap to Hugo + Tailwind for performance gains.
Any idea how I can debug the issue?
Deactivate purging of Tailwind base classes
I had issues (#30) where base classes were purged so I let PurgeCSS ignore the site styling as well as the Tailwind basics.
(First time trying pull requests. Please review and let me know if it works or if there is a simpler solution.)
@tailwindcss/typography classes missing after building
Issue Description
I found an issue where PurgeCSS is removing @tailwindcss/typography classes.
blockquote does not have CSS | Production | Development | |-|-| |
| 
|
code does not have CSS | Production | Development | |-|-| |
| 
|
I think there are other CSS classes that are not included.
I compiled the
publicsite using this commandhugo -s exampleSite --themesDir=../...What seems to work?
postcss.config.jsremoving this line from postcss.config.js works, but I get a large CSS file.
Adding a
divwith classprosewithblockquoteas it's child preventblockquoteCSS from being purged.How to Resolve?
It seems like
postcss.config.jsneeds to be edited to whitelistproseclasses, however I am not familiar with it and am still trying to figure out how to solve it.In the meantime I'll leave this information here in case the author/anyone out there has a solution.
Debloat and improve tailwindcss configuration
I've started to notice that your current configuration of purgeCSS will produce bugs on production, I've made my portfolio using this starter template and started to notice that some of the CSS classes that i've made were removed when building, which was really annoying not seeing the changes I've done in development.
Here are the changes the I've made to fix the problem
tailwind.config.js2.2 Remove the purgecss config on
postcss.config.jspostcss.config.jsit's unnecessary, the docs sayThis can be done easily using the
envbash command which will set enviroment variables, as an exampleWhich is done by adding purgeCSS ignore comment rules on
assets/css/styles.cssbetween line 1 and 6Without this, there will be removed classes
As an example if you use gohugo's auto generated structures such as
code fenceswhich include the class.highlightand you reference this class on an external stylesheet PurgeCSS will remove it on since it does not knows about it.I guess then you could easily make changes to the configuration. To fix these problems.
You have my portfolio repository as an example. Here are the changes that i've made to do the fix.
Doesn't change the final css: no watching
It seems that the tailwind doesn't watch the changes...
For example, if I add a class
max-w-3xl, then it doesn't show up in the final css unlessctrl+cand re-runhugo server ...feel like none of the current solutions solve the problem of Tailwind and Hugo collaboration
Tailwind content, purgecss problems and questions
Hey there, thanks for this great starter kit. See my repo here: https://github.com/artzte/juniper-swordplay
Bunch of n00b questions here; pardon me. I was using an older version of your theme and am trying to update.
The util classes aren't being detected in my setup, which I created following your directions here:
I'm confused by the tailwind config. The content entry is referencing relative to the local folder of the tailwind.config.js, which is not where the layouts are.
Also, why is purgeCSS needed? Tailwind already purges, which is why the content entries in the tailwind config are so critical.
Jit Mode?
Hi i try to enable Jit Mode i got this error
also have this with my old projects...
I would love to know if someone already has solution on this with the postcss
Looking forward for an answer thanks