Alpha Theme

Configuration Files

My initial goal for Alpha was to use as few Alpha specific configuration keys as possible.
While I can’t say that goal was fully achieved, I believe I avoided unnecessary complexity without compromising Alpha’s customization features.

Overview

The main configuration files of Alpha are located in the config/ folder inside Alpha’s theme folder /themes/alpha/config/_default:

config/_default/
├── hugo.toml
├── languages.toml
├── menus.toml
└── params.toml

Note: Alpha also includes a hugo.toml file at the root of the theme. This serves only as a template.

To safely customize Alpha without risking your changes being overwritten during updates, it’s highly recommended to copy the default theme configuration from:

themes/alpha/config/_default

…into your site’s root:

config/

This way, Hugo will use your locals version values, and future Alpha updates won’t override your settings.

Note: If you’re using Alpha as a Hugo module, you can download a pre-packaged version of the config folder here:Download Alpha Config

Attention: Avoid Config Merging Issues

If your project already has a complex setup with:

  • A populated config/_default/ folder, or
  • A large, root-level hugo.toml

Do not merge files blindly!!!.

  1. Instead backup/rename your original files:
mv config/_default config/_default.old
mv hugo.toml hugo.toml.old
  1. Copy Alpha’s config folder to your root config/:
cp -r themes/alpha/config/_default config/
  1. Carefully integrate any custom values you had in your old config.
  2. Test your site thoroughly before deploying.

Config Files


Questions no one asked

But I’m answering them anyway.

Can I use Hugo’s default configuration keys in hugo.toml?

Hugo is an extensive and potentially complex ecosystem. It’s nearly impossible to test every possible configuration. You can use any setting that enhances your site, but be sure to thoroughly test for conflicts with Alpha’s defaults before deploying to production.

I don’t like TOML. Can I use another format?

Alpha uses TOML exclusively because I find it beginner friendly, with clear, readable key value pairs.
If you prefer YAML or JSON, you’ll need to manually adapt Alpha’s config files to your desired format.