Learn to use shortcodes

What is a shortcode

If we take a closer look at how web pages are structured, a clear pattern emerges. Most of them are built with familiar building blocks: a header, a main section, and a footer. Inside those sections, you’ll usually find child elements like navigation menus, sidebars, buttons, links and more.

If you preview your site’s homepage (http://localhost:1313), you’ll see those basic elements already in place. But apart from an instructional message on how to customize your homepage, the main section is intentionally blank.

Why?
Because instead of locking you into a hardcoded layout that requires coding to change, Alpha uses shortcodes to build and customize content.

Shortcodes are small, reusable templates designed for a specific purpose. For example, the warning message you see on the homepage? That’s generated by a shortcode.

To put it simply, imagine you want to draw the same cat on multiple pages, but in different spots. Instead of drawing it by hand every time, I hand you a rubber stamp of the cat. You just decide where to place it on each page.

Shortcodes work the same way for websites. They’re like stamps that let you quickly add pre-designed features or content, without having to rebuild them from scratch every time.

Alpha gives you a collection of “animal stamps” (shortcodes), each with a unique purpose, and lets you decide which one to use and where to place it. So aside from the header and footer, the page is yours to build, as you see fit.

Using shortcodes

Let’s open the homepage content file in VS Code.

In VS Code, open the Explorer panel, go to the /content/ folder, and open the _index.en.md file. You’ll see something like this:

+++
draft = false
date = "2025-05-24T10:31:27+02:00"
lastmod = ""
layout = "home"

title = "Home Page"

# SEO
description = "Home page description, a must for SEO and social shares"
seo_type = ""
seo_image = ""
twitter_username = ""
+++

{{< status_card TITLE="Just Shortcodes" TYPE="warning" >}}

The homepage is left **intentionally empty**!  
To build your homepage, combine shortcodes with regular text content.  
See the [Alpha shortcode documentation](https://alpha.oxypteros.com/docs/shortcodes/) for guidance.

{{< /status_card >}}

You should already understand the frontmatter section (+++ to +++) from previous steps. Everything after that is a shortcode, in this case, the status-card shortcode of Alpha.

At first glance, it might look like Greek. Right?

Put your browser and VS Code window side by side, and compare. You’ll notice that the text content rendered in the browser is exactly the same as what’s in the _index.en.md file. You should also recognize the Markdown parts like bold text (intentionally empty) and links.

Let’s customize the message.

Delete the current one and replace it with this:

{{< status_card TITLE="Homepage" TYPE="warning" >}}

I am learning to use shortcodes.

{{< /status_card >}}

Notice how your custom message now appears in the browser?

Now let’s experiment a bit. Change the TITLE and TYPE values like this:

{{< status_card TITLE="Hello!!!" TYPE="custom" >}}

I am learning to use shortcodes.

{{< /status_card >}}

You’ll get an error.
Can you tell from the error card what went wrong?

That’s right, the TYPE value cannot be just anything. It must be one of the following: error, warning, success, or info.

Let’s fix it:

{{< status_card TITLE="Hello!!!" TYPE="error" >}}
I am learning to use shortcodes.
{{< /status_card >}}

Now it works!

Let’s break the shortcode down:

{{<               # Start of a shortcode
status_card       # The name of the shortcode
TITLE="Hello!!!"  # A parameter
TYPE="error"      # A second (predefined) parameter
>}}               # The end of a shortcode

Shortcodes are defined by {{< >}}. A shortcode must have a name. It can have parameters (like TITLE and TYPE), and optionally, it can contain content. If it contains content, it needs a closing tag:

{{< /status_card >}}

Alpha comes with a dozen or more shortcodes. So… do you need to memorize all their names, parameters, and values?

Absolutely not.

Remember that error you saw earlier? That’s actually a custom Alpha error generated by the OCD, a built-in Alpha helper that informs you about errors and misconfigurations. (Don’t worry, we’ll explain OCD in more detail later.).
If something is misconfigured, either Hugo or OCD will let you know.

Let’s test a few more things:
Rename the shortcode from status_card to status:

{{< status TITLE="Hello!!!" TYPE="error" >}}

Hugo will give you this:

...failed to extract shortcode: template for shortcode "status" not found 

Change back the name to status-card and change TYPE to TIPE:

{{< status_card TITLE="Hello!!!" TIPE="error" >}}

OCD will tell you that TIPE is not a valid parameter and will list the available ones.
Change it back to TYPE and let’s delete the closing tag:

{{< status_card TITLE="Hello!!!" TYPE="error" >}}
This is my custom message on the shortcode!

Again Hugo tells you that the shortcode must be closed so the {{< /status_card >}} is necessary.

...failed to extract shortcode: shortcode "status-card" must be closed or self-closed 

Ctrl+Z to undo the last change.

If you visit the status_card shortcode documentation , you’ll find:

• What it looks like
• The code
• How it works
• How to use it

And for a local full list of all shortcodes, just use this in any page:

{{< help >}}

OCD will display a helpful list of all Alpha shortcodes, with usage and examples.
And yes, {{< help >}} is also a shortcode.

So no, you don’t need to memorize anything. Between Alpha’s shortcode documentation, OCD, and Hugo, you’re fully covered.

Just remember this pattern: {{< >}} And you’re ready to build powerful content with Alpha’s shortcodes.