From 1872a4fee875ceba01cbad4e11d3f5ebaaac4318 Mon Sep 17 00:00:00 2001
From: PAMulligan <paul@pmds.info>
Date: Sun, 21 Jun 2026 04:51:56 -0400
Subject: [PATCH] feat(theme): add SEO metadata (meta, OG, Twitter, JSON-LD)
 via wp_head (#116)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add real front-end SEO output to the flavian-shop FSE theme, generated from the
queried object — not a docs change, and not duplicating an SEO plugin.

- New inc/seo.php renders, on wp_head: a meta description (post excerpt/content
  -> term description -> site tagline, stripped and capped at 160 chars), Open
  Graph and Twitter Card tags (card type follows the featured image), and JSON-LD
  structured data (Article for posts, WebSite otherwise) encoded via
  wp_json_encode + JSON_HEX_* so it is XSS-safe inside <script>.
- Bails entirely when Yoast / Rank Math / AIOSEO / SEOPress is active, so the
  theme never emits duplicate tags.
- functions.php wires it in: add_theme_support('title-tag') (dynamic <title> left
  to core) + require inc/seo.php. theme.json is intentionally untouched — it holds
  design tokens, not meta.

Verified with the repo's WPCS config (WordPress-Extra + Docs): 0 errors, 0 warnings.

Redence-Proof-Token: RDNC-SNDD55

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 themes/flavian-shop/functions.php |   4 +
 themes/flavian-shop/inc/seo.php   | 168 ++++++++++++++++++++++++++++++
 2 files changed, 172 insertions(+)
 create mode 100644 themes/flavian-shop/inc/seo.php

diff --git a/themes/flavian-shop/functions.php b/themes/flavian-shop/functions.php
index 03e0327..65d1a52 100644
--- a/themes/flavian-shop/functions.php
+++ b/themes/flavian-shop/functions.php
@@ -13,6 +13,9 @@
 	define( 'FLAVIAN_SHOP_VERSION', '0.1.0' );
 }
 
+// Front-end SEO metadata (meta description, Open Graph, Twitter Card, JSON-LD).
+require get_template_directory() . '/inc/seo.php';
+
 /**
  * Theme setup.
  *
@@ -22,6 +25,7 @@
 function flavian_shop_setup() {
 	load_theme_textdomain( 'flavian-shop', get_template_directory() . '/languages' );
 
+	add_theme_support( 'title-tag' );
 	add_theme_support( 'wp-block-styles' );
 	add_theme_support( 'editor-styles' );
 	add_theme_support( 'responsive-embeds' );
diff --git a/themes/flavian-shop/inc/seo.php b/themes/flavian-shop/inc/seo.php
new file mode 100644
index 0000000..814152e
--- /dev/null
+++ b/themes/flavian-shop/inc/seo.php
@@ -0,0 +1,168 @@
+<?php
+/**
+ * Front-end SEO metadata: meta description, Open Graph, Twitter Card, and JSON-LD
+ * structured data rendered from the queried object via wp_head.
+ *
+ * Deliberately minimal and plugin-aware — it bails when a dedicated SEO plugin is
+ * active so the theme never emits duplicate tags. The document <title> is left to
+ * WordPress (title-tag support), so this only adds what core doesn't.
+ *
+ * @package Flavian_Shop
+ */
+
+if ( ! defined( 'ABSPATH' ) ) {
+	exit;
+}
+
+/**
+ * Whether a dedicated SEO plugin is already managing head output.
+ *
+ * @return bool
+ */
+function flavian_shop_seo_plugin_active() {
+	return defined( 'WPSEO_VERSION' )      // Yoast SEO.
+		|| defined( 'RANK_MATH_VERSION' )  // Rank Math.
+		|| defined( 'AIOSEO_VERSION' )     // All in One SEO.
+		|| defined( 'SEOPRESS_VERSION' );  // SEOPress.
+}
+
+/**
+ * Resolve a clean, length-capped description for the current view.
+ *
+ * @return string
+ */
+function flavian_shop_seo_description() {
+	$description = '';
+
+	if ( is_singular() ) {
+		$post = get_queried_object();
+		if ( $post instanceof WP_Post ) {
+			$description = has_excerpt( $post ) ? get_the_excerpt( $post ) : $post->post_content;
+		}
+	} elseif ( is_category() || is_tag() || is_tax() ) {
+		$description = term_description();
+	}
+
+	if ( '' === trim( $description ) ) {
+		$description = get_bloginfo( 'description', 'display' );
+	}
+
+	$description = trim( (string) preg_replace( '/\s+/', ' ', wp_strip_all_tags( $description ) ) );
+
+	return wp_html_excerpt( $description, 160, '' );
+}
+
+/**
+ * Canonical URL for the current view.
+ *
+ * @return string
+ */
+function flavian_shop_seo_url() {
+	$canonical = is_singular() ? wp_get_canonical_url() : false;
+
+	return $canonical ? $canonical : home_url( '/' );
+}
+
+/**
+ * Featured-image URL for the current singular view, or '' when none.
+ *
+ * @return string
+ */
+function flavian_shop_seo_image() {
+	if ( is_singular() && has_post_thumbnail() ) {
+		$src = get_the_post_thumbnail_url( get_queried_object_id(), 'full' );
+		if ( $src ) {
+			return $src;
+		}
+	}
+
+	return '';
+}
+
+/**
+ * Output meta description, Open Graph, and Twitter Card tags.
+ *
+ * @return void
+ */
+function flavian_shop_seo_meta_tags() {
+	if ( flavian_shop_seo_plugin_active() ) {
+		return;
+	}
+
+	$title       = wp_get_document_title();
+	$description = flavian_shop_seo_description();
+	$url         = flavian_shop_seo_url();
+	$image       = flavian_shop_seo_image();
+	$type        = is_singular( 'post' ) ? 'article' : 'website';
+	$card        = '' !== $image ? 'summary_large_image' : 'summary';
+
+	printf( '<meta name="description" content="%s" />' . "\n", esc_attr( $description ) );
+
+	printf( '<meta property="og:type" content="%s" />' . "\n", esc_attr( $type ) );
+	printf( '<meta property="og:title" content="%s" />' . "\n", esc_attr( $title ) );
+	printf( '<meta property="og:description" content="%s" />' . "\n", esc_attr( $description ) );
+	printf( '<meta property="og:url" content="%s" />' . "\n", esc_url( $url ) );
+	printf( '<meta property="og:site_name" content="%s" />' . "\n", esc_attr( get_bloginfo( 'name' ) ) );
+
+	printf( '<meta name="twitter:card" content="%s" />' . "\n", esc_attr( $card ) );
+	printf( '<meta name="twitter:title" content="%s" />' . "\n", esc_attr( $title ) );
+	printf( '<meta name="twitter:description" content="%s" />' . "\n", esc_attr( $description ) );
+
+	if ( '' !== $image ) {
+		printf( '<meta property="og:image" content="%s" />' . "\n", esc_url( $image ) );
+		printf( '<meta name="twitter:image" content="%s" />' . "\n", esc_url( $image ) );
+	}
+}
+add_action( 'wp_head', 'flavian_shop_seo_meta_tags', 5 );
+
+/**
+ * Output JSON-LD structured data for the current view (Article for posts,
+ * WebSite otherwise).
+ *
+ * @return void
+ */
+function flavian_shop_seo_jsonld() {
+	if ( flavian_shop_seo_plugin_active() ) {
+		return;
+	}
+
+	if ( is_singular( 'post' ) ) {
+		$post = get_queried_object();
+		if ( ! $post instanceof WP_Post ) {
+			return;
+		}
+		$data = array(
+			'@context'         => 'https://schema.org',
+			'@type'            => 'Article',
+			'headline'         => wp_strip_all_tags( get_the_title( $post ) ),
+			'datePublished'    => get_post_time( 'c', true, $post ),
+			'dateModified'     => get_post_modified_time( 'c', true, $post ),
+			'author'           => array(
+				'@type' => 'Person',
+				'name'  => get_the_author_meta( 'display_name', (int) $post->post_author ),
+			),
+			'mainEntityOfPage' => flavian_shop_seo_url(),
+		);
+
+		$image = flavian_shop_seo_image();
+		if ( '' !== $image ) {
+			$data['image'] = $image;
+		}
+	} else {
+		$data = array(
+			'@context' => 'https://schema.org',
+			'@type'    => 'WebSite',
+			'name'     => get_bloginfo( 'name' ),
+			'url'      => home_url( '/' ),
+		);
+	}
+
+	$json = wp_json_encode( $data, JSON_HEX_TAG | JSON_HEX_AMP | JSON_HEX_APOS | JSON_HEX_QUOT );
+	if ( false === $json ) {
+		return;
+	}
+
+	// wp_json_encode with JSON_HEX_* escapes <, >, &, ', " so the payload is safe inside <script>.
+	echo '<script type="application/ld+json">' . $json . '</script>' . "\n"; // phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped
+}
+add_action( 'wp_head', 'flavian_shop_seo_jsonld', 6 );