Using Shortcodes in Markdown

Shortcodes are simple snippets that let you embed complex functionality into your Markdown documents without writing HTML or complex code. They're commonly used in static site generators.

What are Shortcodes?

Shortcodes are placeholders that get replaced with rendered content during the build process. They typically look like this:

&#123;&#123;< shortcode-name param1="value1" >&#125;&#125;

or

&#123;&#123;% shortcode-name %&#125;&#125;
Content here
&#123;&#123;% /shortcode-name %&#125;&#125;

Common Shortcode Syntax Formats

Hugo Syntax

<!-- Self-closing -->
&#123;&#123;< youtube id="dQw4w9WgXcQ" >&#125;&#125;

<!-- With content -->
&#123;&#123;% note type="warning" %&#125;&#125;
This is important information!
&#123;&#123;% /note %&#125;&#125;

Jekyll/Liquid Syntax

{% youtube "dQw4w9WgXcQ" %}

{% highlight javascript %}
console.log("Hello World");
{% endhighlight %}

Gatsby/MDX Components

<YouTube videoId="dQw4w9WgXcQ" />

<Note type="warning">
  This is important information!
</Note>

Built-in Shortcodes

Hugo Built-in Shortcodes

Figure/Image

&#123;&#123;< figure src="/images/sunset.jpg" 
           title="Beautiful Sunset"
           caption="Taken in California"
           alt="Sunset over ocean"
           width="800" >&#125;&#125;

YouTube

&#123;&#123;< youtube dQw4w9WgXcQ >&#125;&#125;

<!-- With parameters -->
&#123;&#123;< youtube id="dQw4w9WgXcQ" autoplay="true" >&#125;&#125;

Twitter

&#123;&#123;< twitter user="github" id="1234567890" >&#125;&#125;

Instagram

&#123;&#123;< instagram BWNjjyYFxVx >&#125;&#125;

Gist

&#123;&#123;< gist username 0123456789abcdef >&#125;&#125;

Jekyll Built-in Tags

Highlight Code

{% highlight ruby linenos %}
def hello
  puts "Hello World"
end
{% endhighlight %}

Include Files

{% include header.html %}

{% include_relative ../shared/footer.html %}

Link to Posts

{% post_url 2024-01-15-my-post %}

{% link _posts/2024-01-15-my-post.md %}

Creating Custom Shortcodes

Hugo Custom Shortcodes

Create a file in layouts/shortcodes/button.html:

<a href="&#123;&#123; .Get "url" &#125;&#125;" class="button &#123;&#123; .Get "style" &#125;&#125;">
  &#123;&#123; .Inner &#125;&#125;
</a>

Usage:

&#123;&#123;< button url="/docs" style="primary" >&#125;&#125;
Read Documentation
&#123;&#123;< /button >&#125;&#125;

More Complex Example

layouts/shortcodes/callout.html:

{{ $type := .Get "type" | default "info" }}
<div class="callout callout-&#123;&#123; $type &#125;&#125;">
  <div class="callout-title">
    &#123;&#123; with .Get "title" &#125;&#125;&#123;&#123; . &#125;&#125;&#123;&#123; end &#125;&#125;
  </div>
  <div class="callout-content">
    &#123;&#123; .Inner | markdownify &#125;&#125;
  </div>
</div>

Usage:

{{% callout type="warning" title="Important" %}}
This is a **warning** message with *Markdown* support.
{{% /callout %}}

Jekyll Custom Tag

Create a plugin in _plugins/custom_tag.rb:

module Jekyll
  class CustomTag < Liquid::Tag
    def initialize(tag_name, params, tokens)
      super
      @params = params
    end

    def render(context)
      "<div class='custom-tag'>#{@params}</div>"
    end
  end
end

Liquid::Template.register_tag('custom', Jekyll::CustomTag)

Usage:

{% custom "My custom content" %}

Practical Shortcode Examples

Alert/Notice Boxes

{{% alert type="info" %}}
ℹ️ This is an informational message.
{{% /alert %}}

{{% alert type="warning" %}}
⚠️ This is a warning message.
{{% /alert %}}

{{% alert type="danger" %}}
🚨 This is a danger message.
{{% /alert %}}

Code Tabs

&#123;&#123;< tabs >&#125;&#125;
  &#123;&#123;< tab "JavaScript" >&#125;&#125;
  ```javascript
  console.log("Hello");

{{< /tab >}}

{{< tab "Python" >}}

print("Hello")

{{< /tab >}} {{< /tabs >}}

### Expandable Sections

```markdown
&#123;&#123;< expand "Click to expand" >&#125;&#125;
This content is hidden by default and can be expanded.

It can contain **any Markdown** including:
- Lists
- Code blocks
- Images
&#123;&#123;< /expand >&#125;&#125;

Embed External Content

<!-- CodePen -->
&#123;&#123;< codepen user="username" id="abcdefg" >&#125;&#125;

<!-- JSFiddle -->
&#123;&#123;< jsfiddle url="https://jsfiddle.net/username/abc123" >&#125;&#125;

<!-- CodeSandbox -->
&#123;&#123;< codesandbox id="abc123" >&#125;&#125;

Gallery/Lightbox

&#123;&#123;< gallery >&#125;&#125;
  &#123;&#123;< img src="image1.jpg" caption="First image" >&#125;&#125;
  &#123;&#123;< img src="image2.jpg" caption="Second image" >&#125;&#125;
  &#123;&#123;< img src="image3.jpg" caption="Third image" >&#125;&#125;
&#123;&#123;< /gallery >&#125;&#125;

Table of Contents

&#123;&#123;< toc >&#125;&#125;

<!-- With options -->
&#123;&#123;< toc levels="2,3" >&#125;&#125;

Mermaid Diagrams

&#123;&#123;< mermaid >&#125;&#125;
graph TD;
    A-->B;
    A-->C;
    B-->D;
    C-->D;
&#123;&#123;< /mermaid >&#125;&#125;

Advanced Shortcode Patterns

Parameterized Shortcodes

<!-- Named parameters -->
&#123;&#123;< card title="My Title" 
         image="/images/card.jpg" 
         link="/read-more" 
         button="Learn More" >&#125;&#125;

<!-- Positional parameters -->
&#123;&#123;< youtube "dQw4w9WgXcQ" "16:9" >&#125;&#125;

Nested Shortcodes

&#123;&#123;< columns >&#125;&#125;
  &#123;&#123;< column size="6" >&#125;&#125;
    Left column content
  &#123;&#123;< /column >&#125;&#125;
  
  &#123;&#123;< column size="6" >&#125;&#125;
    Right column content
  &#123;&#123;< /column >&#125;&#125;
&#123;&#123;< /columns >&#125;&#125;

Conditional Rendering

Hugo example:

{{ if .Get "show" }}
<div class="optional-content">
  &#123;&#123; .Inner &#125;&#125;
</div>
&#123;&#123; end &#125;&#125;

Accessing Page Variables

<!-- In shortcode template -->
<div class="page-info">
  <h3>&#123;&#123; .Page.Title &#125;&#125;</h3>
  <p>Last modified: &#123;&#123; .Page.Lastmod &#125;&#125;</p>
  <p>Reading time: &#123;&#123; .Page.ReadingTime &#125;&#125; minutes</p>
</div>

Shortcode Best Practices

1. Keep It Simple: Shortcodes should be easy to remember and use
2. Clear Naming: Use descriptive names that indicate functionality
3. Documentation: Document all parameters and usage examples
4. Error Handling: Provide sensible defaults and handle missing parameters
5. Performance: Avoid complex computations in frequently used shortcodes
6. Accessibility: Ensure generated HTML is accessible
7. Mobile Friendly: Test shortcodes on mobile devices

Common Use Cases

Documentation

<!-- API endpoint documentation -->
&#123;&#123;< api method="GET" path="/api/users" >&#125;&#125;
Returns a list of all users.
&#123;&#123;< /api >&#125;&#125;

<!-- Parameter documentation -->
&#123;&#123;< param name="userId" type="string" required="true" >&#125;&#125;
The unique identifier for the user.
&#123;&#123;< /param >&#125;&#125;

E-learning

<!-- Quiz questions -->
&#123;&#123;< quiz >&#125;&#125;
  &#123;&#123;< question "What is 2+2?" >&#125;&#125;
    &#123;&#123;< answer correct="true" >&#125;&#125;4&#123;&#123;< /answer >&#125;&#125;
    &#123;&#123;< answer >&#125;&#125;3&#123;&#123;< /answer >&#125;&#125;
    &#123;&#123;< answer >&#125;&#125;5&#123;&#123;< /answer >&#125;&#125;
  &#123;&#123;< /question >&#125;&#125;
&#123;&#123;< /quiz >&#125;&#125;

Product Showcase

&#123;&#123;< product-card
     name="Premium Widget"
     price="$99.99"
     image="/products/widget.jpg"
     rating="4.5"
     reviews="245" >&#125;&#125;

Shortcodes vs. Components

Feature	Shortcodes	React Components
Build Time	✅ Rendered at build	❌ Runtime
Interactivity	❌ Static	✅ Dynamic
Learning Curve	✅ Simple	⚠️ Moderate
Flexibility	⚠️ Limited	✅ High
Performance	✅ Fast	⚠️ Depends on bundle

Migrating from HTML to Shortcodes

Before (Raw HTML)

<div class="alert alert-warning" role="alert">
  <h4 class="alert-heading">Warning!</h4>
  <p>This is a warning message.</p>
</div>

After (Shortcode)

{{% alert type="warning" title="Warning!" %}}
This is a warning message.
{{% /alert %}}

Debugging Shortcodes

Hugo Debug

<!-- In shortcode template -->
&#123;&#123; printf "%#v" . &#125;&#125;

<!-- Print all params -->
&#123;&#123; range $key, $value := .Params &#125;&#125;
  &#123;&#123; $key &#125;&#125;: &#123;&#123; $value &#125;&#125;
&#123;&#123; end &#125;&#125;

Jekyll Debug

def render(context)
  puts "Debug: #{@params.inspect}"
  # ... rest of code
end

Performance Considerations

1. Caching: Cache expensive computations
2. Lazy Loading: Defer non-critical content
3. Minimize API Calls: Batch requests when possible
4. Optimize Images: Use appropriate sizes and formats
5. Code Splitting: Load JavaScript only when needed

Conclusion

Shortcodes provide a powerful way to extend Markdown with custom functionality while keeping content files clean and maintainable. They're an essential tool for building modern static sites and documentation systems.

Additional Resources

• Hugo Shortcodes Documentation
• Jekyll Liquid Tags
• MDX Components
• Eleventy Shortcodes