Skip to content

dirkolbrich/hugo-tailwindcss-starter-theme

Repository files navigation

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
  • 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