Shortcodes

Alright, let’s get our hands dirty. You’ve just written a shortcode, either by bending one of WordPress’s built-in marvels to your will or by forging a completely custom one from raw PHP. You feel like a digital wizard. Don’t get cocky. The single most important step, the one that separates the pros from the amateurs who break their live site on a Tuesday afternoon, is testing. And I mean real testing, not just glancing at it and saying “yep, looks good.”

Right, let’s talk about shortcodes getting frisky with each other. You’ve probably already hit this wall: you try to put a shortcode inside another shortcode, and instead of a beautiful, nested masterpiece, you get a string of sad, broken HTML comments or the whole thing just vomits onto the page. That’s because by default, shortcodes are like toddlers; they don’t play well with others and they certainly don’t share their toys.

Right, let’s talk about shortcodes with named parameters. You’ve probably seen the basic ones that just take a single chunk of content, but named parameters are where these little magic spells really start to feel like proper functions. They’re the difference between a blunt instrument and a scalpel. The genius of named parameters is that they make your shortcodes self-documenting and far less brittle. You don’t have to remember if the third parameter is the background color or the text color; you just name it. It’s the same reason we use wp_query arguments instead of a long, ordered list of parameters that nobody can remember.

Alright, let’s get our hands dirty with the three most important variables you’ll be wrestling with inside your shortcode templates: .Get, .Inner, and .Page. Think of them as the tools Hugo hands you to crack open the content your user provided and the context of the page they’re on. They’re powerful, but they have their quirks. I’ll call them out. The .Get Method: Your Swiss Army Knife (That Sometimes Forgets a Blade) You use .Get to fetch a parameter passed into your shortcode from the markdown file. It seems simple, and for the most part, it is. But its behavior changes based on whether you’re dealing with a positional parameter or a named parameter, and this is where people face-plant.

Right, so you’ve outgrown the built-in shortcodes. Good. They’re fine for a quick hello, but you’re building something real. That means writing your own. And Hugo, in its infinite wisdom, gives us a wonderfully simple yet powerful way to do this: the layouts/shortcodes directory. Think of this directory as your personal toolbox. Every file you drop in here becomes a new shortcode you can call from your content. Create a file named cat-picture.html? Boom, you now have a &#123;&#123;< cat-picture >&#125;&#125; shortcode. The name of the file is the name of the shortcode. It’s so straightforward it’s almost absurd, a rare moment of sheer clarity in the world of tech.

Now, let’s talk about actually calling these shortcodes. You’ve got your shortcode name, and you’re ready to plaster it all over your posts. There are two ways to do this, and WordPress, in its infinite wisdom, decided to make them look exactly like HTML tags. This is either a moment of pure genius or a recipe for confusion, depending on how much coffee you’ve had. I lean towards genius, because it’s immediately familiar.

Right, let’s talk about Hugo’s built-in shortcodes. Think of these as your get-out-of-jail-free cards for embedding content that would normally require a tedious mix of raw HTML, external scripts, and a prayer to the internet gods. They’re Hugo’s way of saying, “I got you, friend. Don’t sweat the tedious stuff.” The Workhorse: figure You’ll use figure more than any other. It’s for images, but it does the job properly. Unlike just slapping an <img> tag in your Markdown, figure automatically handles the alt text, caption, and wrapping it all in the semantically correct HTML5 <figure> element. It also gives you optional classes for styling and even lightbox functionality.

Let’s be honest: you don’t want to write raw HTML in your posts. It’s clunky, it breaks your flow, and one misplaced angle bracket can turn your beautiful page into a digital abstract art piece. But sometimes, you need to embed something more dynamic than an image or more structured than a paragraph. Enter the shortcode. Think of a shortcode as a text-based macro. You type a simple, WordPress-specific instruction in square brackets, and WordPress performs a little magic trick, replacing your simple text with something far more powerful—be it a complex gallery, a contact form, or a custom-designed call-out box. It’s the CMS equivalent of a hotkey; a power-user shortcut that keeps you out of the block editor’s “Code view” and in the flow of writing.