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
- Prepare Data Files: Create the necessary YAML/JSON files in the
data/directory, ensuring a consistent structure. - Write Shortcode Templates: Create corresponding HTML templates in
layouts/shortcodes/, using.Site.Datato read the data. - Add Styling (Optional): Define generic classes (like
.alert) inassets/css/custom.css, or embed inline styles directly within the template. - Reference in Content: Use the
syntax, placing the content you want to display inside the tags.Content - Test and Refine: Run
hugo serverlocally 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, andiconin 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.