Front Matter Templates

This page documents the custom front matter template system used by the Hugo adapter to generate static site front matter when syncing WordPress posts to GitHub. It covers available placeholders, how the template is stored and processed, format requirements, and example configurations.

For information about how the Hugo adapter converts post content to Markdown (the body after the front matter), see the Hugo Adapter page (3.2). For the Settings page UI where the template is entered and saved, see 5.1.

---

Overview

The front matter template system allows site operators to define exactly what metadata fields appear at the top of each generated Markdown file, using a plain-text template with {{placeholder}} tokens. At sync time, the Hugo adapter substitutes real post data for each placeholder and writes the result as the file header.

The template is free-form text, meaning any valid YAML or TOML structure can be expressed — including nested keys, arrays, and static values. Only the supported placeholders are dynamic; everything else in the template is passed through verbatim.

---

Processing Pipeline

Diagram: Front Matter Template Processing Flow

Sources: adapters/class-hugo-adapter.php33-38 adapters/class-hugo-adapter.php50-103

---

Storage

The template string is stored as a key within the ajc_bridge_settings WordPress option:

Option Name	Key	Type
ajc_bridge_settings	hugo_front_matter_template	string

The value is retrieved with get_option( 'ajc_bridge_settings', array() ) and accessed as $settings['hugo_front_matter_template']. If the key is absent (e.g., on first install), the adapter falls back to a built-in default template.

The template is entered through the Settings > Hugo Configuration section of the General settings tab in the WordPress admin. It is sanitized on save to prevent XSS.

Sources: adapters/class-hugo-adapter.php52-57 docs/front-matter-template-examples.md1-8

---

Default Template

When no custom template has been saved, the following YAML template is used:

Sources: adapters/class-hugo-adapter.php55

---

Available Placeholders

All placeholders use double-brace syntax: {{placeholder_name}}.

Placeholder	Value Source	Notes
{{title}}	$post->post_title	Raw post title string
{{date}}	get_the_date('c', $post)	ISO 8601 format (e.g. 2024-01-15T10:30:00+00:00)
{{author}}	get_userdata($post->post_author)->display_name	Falls back to "Unknown" if user not found
{{slug}}	$post->post_name	URL slug
{{id}}	(string)(int)$post->ID	Post ID, cast to integer for security before stringification
{{image_avif}}	Computed path	/images/{post_id}/featured.avif if featured image exists and was processed; empty string otherwise
{{image_webp}}	Computed path	/images/{post_id}/featured.webp if featured image exists and was processed; empty string otherwise
{{image_original}}	wp_get_attachment_url()	Original WordPress media library URL; falls back to empty string

Sources: adapters/class-hugo-adapter.php84-93 docs/front-matter-template-examples.md9-18

---

Image Placeholder Behavior

The image placeholders have two distinct behaviors depending on whether the Media_Processor has already processed and uploaded the featured image:

Diagram: Image Placeholder Resolution

When {{image_avif}} or {{image_webp}} are used but the post has no featured image (or media processing was skipped), these placeholders resolve to an empty string. The generated front matter will contain the key with an empty value.

Sources: adapters/class-hugo-adapter.php65-93

---

Format Requirements

The template system supports both YAML and TOML front matter formats. The delimiter lines must be included in the template itself — the adapter does not add them automatically.

Format	Delimiter	Example Opening Line
YAML	---	---
TOML	+++	+++

The adapter performs a direct str_replace() substitution — it does not parse or validate the template as YAML or TOML. The raw output string is prepended to the Markdown body with a blank line separator.

Sources: adapters/class-hugo-adapter.php96-100 docs/front-matter-template-examples.md109-114

---

Example Templates

Minimal YAML

PaperMod Theme (YAML)

TOML Format

Extended YAML with All Placeholders

Using {{id}} for Custom Resource Paths

Because {{id}} resolves to the numeric post ID, it can be composed into file paths manually:

Sources: docs/front-matter-template-examples.md22-106

---

Placeholder Substitution Implementation

Diagram: Code Entities in the Template System

The substitution at adapters/class-hugo-adapter.php96-100 uses PHP's str_replace() with two parallel arrays — one of placeholder strings and one of resolved values. Placeholders that appear multiple times in the template (e.g. {{title}} used in both title: and alt:) are all replaced in a single pass.

Sources: adapters/class-hugo-adapter.php84-103

---

Behavior Notes

• Empty image values: If no featured image is set, {{image_avif}}, {{image_webp}}, and {{image_original}} all resolve to empty strings. The YAML or TOML key will still appear with an empty value (e.g., image: "").
• Static content: Any text in the template that does not contain a {{...}} token is written to the output unchanged. You can add arbitrary static fields (e.g., draft: false, ShowToc: true) directly to the template.
• No automatic escaping: The plugin does not re-escape placeholder values for YAML/TOML. If a post title contains special YAML characters (e.g., :, "), wrap the placeholder in quotes in your template: title: "{{title}}".
• Security: The {{id}} placeholder casts $post->ID to an integer before stringification (adapters/class-hugo-adapter.php85) to prevent injection via a crafted post ID.
• Template validation: The plugin does not validate the template output as valid YAML or TOML. Syntax errors in the template will propagate to the generated file and may break the Hugo build.

Sources: adapters/class-hugo-adapter.php65-100 docs/front-matter-template-examples.md109-114