Skip to content

Data-Driven Markdown Shortcodes

Data-Driven Markdown Shortcodes

Background and Motivation

In content-heavy technical sites, you often need to reuse the same UI components—such as alert boxes, tabs, or code demonstrations. The traditional approach is to write repetitive HTML or shortcode calls directly in Markdown. This not only increases maintenance overhead but also tightly couples the content with its presentation.

By storing presentation data (like titles, colors, and icons) in independent JSON or YAML files, your shortcodes only need to read the data and render the template. This approach offers several benefits:

  • Content editors can modify visual elements without knowing HTML/CSS.
  • Styles remain consistent; a global change only requires updating a single data file.
  • Reusability improves, as the same shortcode can be used across multiple pages with different data.

Core Concepts

Data File Structure

Place your data files in the data/ directory. Here is an example using YAML:

# data/alerts.yml
- id: warning
  title: "Warning"
  icon: "⚠️"
  color: "#ff9800"
  bg: "#fff3e0"
- id: tip
  title: "Tip"
  icon: "💡"
  color: "#4caf50"
  bg: "#e8f5e9"

Shortcode Implementation

In layouts/shortcodes/alert.html, you can implement the rendering logic:

{{ $data := .Site.Data.alerts }}
{{ $item := (index $data (isset .Params "type" | ternary .Params.Type "info")) }}
<div class="alert alert-{{ .Params.type | default "info" }}" style="border-left: 4px solid {{ .Item.color }}; background-color: {{ .Item.bg }};">
  <div class="alert-header">
    <span class="alert-icon">{{ .Item.icon }}</span>
    <strong>{{ .Item.title }}</strong>
  </div>
  <div class="alert-body">
    {{ .Inner | markdownify }}
  </div>
</div>

Usage

You can now use this shortcode in any Markdown file:


This is a warning message. The content will be safely converted to Markdown.

Implementation Steps

  1. Prepare Data Files: Create the necessary YAML/JSON files in the data/ directory, ensuring a consistent structure.
  2. Write Shortcode Templates: Create corresponding HTML templates in layouts/shortcodes/, using .Site.Data to read the data.
  3. Add Styling (Optional): Define generic classes (like .alert) in assets/css/custom.css, or embed inline styles directly within the template.
  4. Reference in Content: Use the
    Content
    syntax, placing the content you want to display inside the tags.
  5. Test and Refine: Run hugo server locally to preview the result, and adjust the data fields or templates based on the actual rendering.

Best Practices

  • Keep Data Granular: Only store fields required for presentation to avoid redundancy.
  • Unified Naming Conventions: Use stable field names like id, title, and icon in your data files to make templates easily reusable.
  • Version Control: Treat data files like code. Manage them with Git to track change history.
  • Performance Considerations: Since data files are read during Hugo’s build process, keep their file sizes small to prevent slowing down build times.

Frequently Asked Questions (FAQ)

Q1: What if I want to use multiple alert types on the same page?
A: Simply pass a different type parameter each time you call the shortcode. The shortcode will look up the corresponding entry from the data file based on the type.

Q2: Does the data file support JSON or YAML?
A: Hugo supports .json, .yaml, and .yml formats out of the box. You can choose whichever your team prefers.

Q3: How can non-technical staff maintain these data files?
A: Provide a simple CMS interface (such as Netlify CMS or Forestry) pointed at the data/ directory. This allows business or editorial staff to update data via forms without touching any code.

References