Alpha Theme
From Zero with Zero
Frontmatter

Frontmatter

Written by oxypteros

Welcome back!

The main goal of this From Zero to Zero guide has been achieved. You’ve successfully deployed your personal site to the web and learned how to add content to it.

At this point, you’re ready to explore on your own using Hugo’s and Alpha’s documentation. Everything you can do with Alpha and Hugo is documented in detail.

But let’s stay together for a bit longer. The topics we’ll cover next are also explained in Alpha’s documentation, but I want to walk you through them step by step.
For example, in this chapter, we’ll dive into frontmatter and the specific keys supported by Alpha. You can always refer to the full list later in the Alpha documentation.

Frontmatter Keys

We’ve already mentioned what frontmatter is and what it does. What you might not know is that Alpha uses TOML for frontmatter, just like the hugo.toml configuration file.

Examples:

title = "My Article"           # A key with a string value
draft = false                  # A key with a boolean value
tags = ["red", "yellow"]       # A key with multiple string values

A Closer Look

  • Strings are enclosed in quotes (" "), like the title.
  • Booleans (true/false) and numbers are not in quotes. These are treated as actual values with special meaning, not just text.
    For example:
    • draft = false → tells Hugo: “Do not publish this page.”
    • draft = "false" → this is just a string, not the actual false value and has no special meaning for Hugo.
  • Arrays (lists) are wrapped in square brackets ([]) and contain comma-separated values:
    • tags = ["red", "yellow"]

Add a new key

  1. Start your Hugo server if it’s not running.
  2. Open index.en.md inside your content/articles/my-first-article/ folder.
  3. Under the line with description = "", add the tags key like this:
tags = ["red", "yellow"]

Now check the browser at http://localhost:1313/articles/my-first-article/
Can you see the tags on the page?
If not, did you save your file?

Remember to save the changes you make!

Add More Frontmatter Keys.

  • Add categories:
categories = ["My demo category"]
  • Add a license:
license = "copyright"

Now let’s edit some of the existing values:

  • Change license to "CC0"
  • Change the year in the date field to 2024

Take a look in the browser again. You can see the added and edited key values.

What happened?

When we add tags and categories, Hugo records that this content:

  • Belongs to the category, “My demo category”
  • Is tagged with “red” and “yellow”
  • Alpha then displays those on the page based on the design.

Let’s edit some more:

  • Set draft = true, save the file and then,
  • Change back the year to 2025

The year in your site remains 2024 even though you change it, because you set draft = true, and now the page doesn’t get rebuilt by Hugo.
You still see it in your browser because Hugo had already built the page before marking it as a draft. So the year value remains as it was the last time Hugo built the page.

If you tried to publish this right now (via GitHub → Cloudflare), the draft page would be skipped, and visiting it on your live site (https://[YOUR-PROJECT-NAME].pages.dev/articles/my-first-article) would return a 404 error. You can try it if you want.

Why draft is so important
  1. It’s a very useful feature to keep your work in progress hidden from your visitors.
  2. It’s one of the top causes of confusion:
    • “Why isn’t my page showing?”
    • “Why is this page missing from my site?”
    • “I can see it locally but not on production!”

In Alpha, new content defaults to draft = false, to avoid this confusion, so make sure you update it when needed.

Frontmatter Values

When we edited the frontmatter keys, some values may have seemed a bit random.Like "red" and "yellow" for the tags key. Meanwhile, others like "CC0" for the license key were more specific.

And that’s true!
In most frontmatter keys, you’re free to personalize the values however you like. But for others, you can’t just write anything.

For example:

  • The date key must always contain a valid date in ISO format (like "2025-04-01T12:00:00+00:00").
  • The license key accepts only a predefined list of values. If you input anything else, Alpha will ignore it.

Deep Dive to Frontmatter

You can find the full list of accepted values in the license frontmatter key of the documentation. The same applies to any frontmatter key that requires specific values.

If you visit that page, you’ll see this reference entry:

license
license = "" — (string, optional)
Adds a license notice for the page’s content.
Only predefined values are supported. Copyrighted content or Creative Common licences
Values: copyright, CC0, CC-BY, CC-BY-SA, CC-BY-ND,CC-BY-NC, CC-BY-NC-SA, CC-BY-NC-ND.

This entry summarizes the license frontmatter key:

  • What the key does.
  • How to format its value (string).
  • Whether it’s required (optional).
  • Which values are allowed.

If you read the whole reference list at first, you may feel slightly intimidated by the number of entries (there are around eighteen) and in this chapter, we only covered about five of them.

So your inquisitive mind may ask:

  • Do I have to write and fill out all of them?
  • How can I remember all of that?

Let’s answer all of that with a practical example.

The Kind Flag

Remember the Hugo command we used to create new content?

hugo new content articles/my-first-article/index.en.md

If you practiced, you know this command by heart: just hugo new content plus a file path.
Hugo creates a new file called index.en.md and includes five frontmatter keys with some default values like date and title.

Now try this command:

hugo new content --kind page articles/full-page/index.en.md

We just added the --kind page flag.

Open articles/full-page/index.en.md in VS Code and look at the frontmatter:
It now contains many more keys. In fact, it includes all the keys from the reference in the documentation!

Read through them carefully. If I were a betting man, I’d say you don’t misunderstand more than six of them just by reading. And if you browse the reference entries, that number drops even further.

Using the --kind flag when creating new content means you don’t have to manually add all the keys in every new article.

Also you don’t have to fill in all the values. You only need to edit the values you care about, especially if you want to optimize your content or take advantage of Alpha’s features.

We’ll come back to this later. For now, just remember this:

The recommended Alpha way is to use the --kind flag when creating content.

Now, a quick note on that before we move on.

At the previous chapter, I deliberately introduced you to the default Hugo command:

hugo new content articles/my-first-article/index.en.md

This is the most universal and theme-agnostic way to create new content in Hugo. It’s shorter, easier to grasp, and works with any Hugo theme, not just Alpha.

Now, I introduced you to the --kind flag:

hugo new content --kind page articles/full-page/index.en.md

While this is also a valid Hugo command, the value of the --kind flag (in this case, page) is Alpha-specific. It tells Alpha to use one of its custom archetypes, which pre-fills the frontmatter with recommended keys and values.

So why didn’t I tell you about --kind right away?
Because I wanted you to first learn the core Hugo behavior (the baseline that applies to any theme) and only then build on that with Alpha’s enhancements. That way, you understand both the foundations and the benefits of Alpha’s custom features.

Now that you’ve seen both in action, you can choose the way you prefer, though I’ll continue to recommend the --kind approach.