Simpl

Not a unique name I know.

Warning

• NOT READY FOR PUBLIC CONSUMPTION
• This is an experiment creating a Hugo theme.
• This is my first time creating a theme.
• This is my first time navigating Hugo modules.

Features

• Work in progress.
• It's pretty barebones.
• TailwindCSS v4.
• Has Dark and Light Mode based on system settings.
• Mobile'ish.
• There has been some attention paid to a11y, but it may still fall short while I work through things.
• Early attempts at i18n.

Prettier and Stylesheets

This repo configures Tailwind-aware formatting through .prettierrc using tailwindStylesheet, which points to assets/css/prettier-tailwind.css.

This is editor/build-tool metadata for formatting only. It is not part of the Hugo runtime stylesheet pipeline and is not shipped to browsers.

That file currently imports both assets/css/main.css and assets/css/syntax.css.

When adding additional stylesheets under assets/css/, update assets/css/prettier-tailwind.css to include them. If the location or filename of the combined stylesheet changes, also update the tailwindStylesheet value in .prettierrc.

Hugo 0.165 Migration Note

If your site config still uses languageCode, rename it to locale.

# before
languageCode = 'en-us'

# after
locale = 'en-us'

Installation

mkdir my-new-blog

hugo new site my-new-blog

hugo mod init github.com/org/repo

Edit hugo.toml

locale = 'en-us'
baseURL = 'https://example.com/'
title = 'My Simpl Themed Site'

[[menus.main]]

[params.Author]
github = 'username'
name = 'name'

[build]
_merge = 'deep'

[markup]
_merge = 'deep'

[module]
[[module.imports]]
path = "github.com/esacteksab/simpl"

[security]
  [security.exec]
    allow = ['^(dart-)?sass$', '^go$', '^git$', '^node$', '^postcss$', '^tailwindcss$']

This theme requires TailwindCSS, and PostCSS copy the package.json, tailwind.config.js and postcss.config.js from GitHub esacteksab/simpl to my-new-blog. Before we install packages, there may be things you don't want. Edit package.json accordingly. When ready, install the packages:

pnpm install

Then build/serve with hugo

If Hugo warns that npm dependencies are out of sync, run hugo mod npm pack (and pnpm install) to refresh generated dependency metadata.

hugo
hugo serve -D

Troubleshooting

If you see an error like access denied: "tailwindcss" is not whitelisted in policy "security.exec.allow", add the following to your site config:

[security]
  [security.exec]
    allow = ['^(dart-)?sass$', '^go$', '^git$', '^node$', '^postcss$', '^tailwindcss$']

Then run:

hugo mod npm pack
pnpm install
hugo

If you see binary "tailwindcss" is not a Node.js script, Hugo is usually picking up a package-manager shim instead of the CLI entry script. Ensure @tailwindcss/cli is installed, then recreate direct links for Hugo:

pnpm add -D tailwindcss @tailwindcss/cli
rm -f node_modules/.bin/tailwindcss node_modules/.bin/postcss
ln -s ../@tailwindcss/cli/dist/index.mjs node_modules/.bin/tailwindcss
ln -s ../postcss-cli/index.js node_modules/.bin/postcss
hugo

Menu

By default, the site displays Home, Posts and Tags. You can override this in your hugo.toml with [[menus.main]].

If you want no items in the menu simply define an empty TOML table:

locale = 'en-us'
baseURL = 'https://example.com/'
title = 'My Simpl Themed Site'

[[menus.main]]

If you just want Home and Posts, you can do so like below:

baseURL = 'https://example.com/'
locale = 'en-us'
title = 'My Simpl Themed Site'

[[menus.main]]
  name = 'Home'
  pageRef = '/'
  weight = 10

[[menus.main]]
  name = 'Posts'
  pageRef = '/posts'
  weight = 20

You can add others and change the weight to define the order in which they're displayed. Hugo's documentation on Menus is well written and should help you further.

Social Media

The site uses a list of various social media platforms defined in social.toml in the theme's data directory.

In combination with some Hugo parameters. In your hugo.toml add the following:

[params.Author]
github = 'username'
gitlab = 'username'
linkedin = 'username'

These map to the declarations in social.toml mentioned above:

[[social_icons]]
    id = "github"
    url = "https://github.com/%s"
    title = "GitHub"
    icon = "fab fa-github"

[[social_icons]]
    id = "gitlab"
    url = "https://gitlab.com/%s"
    title = "GitLab"
    icon = "fab fa-gitlab"

[[social_icons]]
id = "linkedin"
url = "https://linkedin.com/in/%s"
title = "LinkedIn"
icon = "fab fa-linkedin"

The username above is mapped to %s if you're uncertain what the value should be.

Favicon

The site by default tries to load some files related to (MDN): favicon that don't exist in the static directory of the theme. I use favicon.io to convert an existing PNG to ico. They provide you with a .zip that contains the files you need.

ls favicon_io
android-chrome-192x192.png
android-chrome-512x512.png
apple-touch-icon.png
favicon.ico
favicon-16x16.png
favicon-32x32.png
site.webmanifest

You can put these in your static dir and they will exist where they should when the site is built and published.

Accent Colors

Caution

This should be considered a beta feature, subject to change. Not likely to be deprecated though as I quite like it.

You can enable this by passing Params.accentColor = '$color' where $color doesn't necessarily need to be a color, just a string, but I choose $color. You do you.

[Params]
  accentColor = 'blue'

Then in assets/css/blue.css notice whatever blue is here is what you pass in the Params.accentColor above.

@import "tailwindcss";

@media (prefers-color-scheme: dark) {
  :root {
    --accent-color: var(--color-sky-500);
  }
}

@media (prefers-color-scheme: light) {
  :root {
    --accent-color: var(--color-blue-700);
  }
}

Since this theme uses TailwindCSS, I choose to use their color patterns, but these values (--color-blue-700 or --color-sky-500) don't need to be TailwindCSS values, you could pass any supported value here.

GitInfo

You can display the abbreviated hash by setting enableGitInfo = true in hugo.toml. Additionally, you can pass Params.gitURL = 'https://<your git repo here>' like so to make this has a link to the commit:

[Params]
  gitURL = 'https://github.com/esacteksab/simpl'

Deploying to Cloudflare Pages

Hugo's documentation on Host and deploy is pretty extensive. Cloudflare also publishes a Hugo specific guide.

I develop almost exclusively on GitHub, so I use Cloudflare's Git integration.

A few things to note that I learned by trial and error:

• If you're using a custom domain, you will need to deploy after you've configured custom domain. This ensures your stylesheets use the appropriate hostname.
• This theme was built with Hugo Extended Edition, so in Cloudflare, you can pass an environment variable HUGO_VERSION with a value of 0.145.0+extended to ensure it uses the extended edition.

Any questions, please don't hesitate to open an Issue. I'm new to Hugo so we'll figure it out together!