Hugo Starter Theme with Tailwind CSS

Starter files for a Hugo theme with Tailwind CSS.

• set up to use Tailwind CSS v3.0+
• includes the official Tailwind CSS plugins
  • Typography for styling of markdown content
  • Forms for basic resets for form styles
  • Aspect Ratio to give elements a fixed aspect ratio
  • Line Clamp for truncating text
• 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
• no need to purge via PurgeCSS anymore, as the TailwindCSS JIT compiler only builds the necessary CSS classes
• 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 to hide the nav on small screens
• to keep that s***er down, the theme features a sticky footer
• color theme switcher for light, dark or system preferred color scheme
• included development 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.120.0 and above.

Basic usage to develop a separate Theme repo

• clone and rename the repo

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

• make the theme your own by removing the git history from the cloned starter repo and initiate a new git repo

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

• install the necessary node packages

npm install

• edit the hugo.toml file in exampleSite/ to reflect the new-theme-name

# in hugo.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-tailwindcss-starter-theme 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 hugo.toml file in new-site/ to reflect the new-theme-name

# in hugo.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 some helpers for the development phase (not visible in production):

• /partials/dev/parameters.html shows basic Hugo page parameters
• /partials/dev/size-indicator.html displays a floating circle in the upper right corner to indicate the current Tailwind CSS responsive breakpoint
• /partials/dev/container-indicator.html shows the container area as a color filled background

If you don't need any of these helpers anymore, just delete the {{- partial "dev/dev-tools.html" . -}} line from /layouts/_default/baseof.html.

Reference

• documentation for Hugo's PostCSS setup
• inspiration to make TailwindCSS v3 JIT-compiler work with Hugo in dev and production mode via a blog post by Bryce Wray