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 some additional items. But everything you see can be change without touching a single theme file.

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

Shortcodes are small, reusable templates designed for a specific purpose. Everything you see in the homepage is 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.md file. Below the frontmatter you’ll see something like this:

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

Rearrange your webpages as you see fit for your needs. 
Other than your text in Alpha everything else is **shortcodes**!

{{< /status_card >}}

That first item 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.md file. You should also recognize the Markdown part like bold text (shortcodes).

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 LiVa, a built-in Alpha helper that informs you about errors and misconfigurations. (Don’t worry, we’ll explain LiVa in more detail later.).
If something is misconfigured, either Hugo or LiVa 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" >}}

LiVa 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 >}}

LiVa 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, LiVa, and Hugo, you’re fully covered.

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