From c2cad7fb53ca295dff9490555f4863b6bf57760d Mon Sep 17 00:00:00 2001
From: Greg Swinehart <greg@posit.co>
Date: Fri, 31 Jul 2026 13:07:56 -0700
Subject: [PATCH] Add canonical URL support via canonical_url frontmatter

Every page now emits a self-referencing <link rel="canonical"> tag by
default. Posts whose canonical version lives elsewhere (e.g. the same
post on posit.co/blog) can set canonical_url in frontmatter to point
the canonical tag and blog JSON-LD there instead.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 content/blog/CLAUDE.md       | 1 +
 layouts/partials/head.html   | 3 +++
 layouts/partials/jsonld.html | 5 +++--
 3 files changed, 7 insertions(+), 2 deletions(-)

diff --git a/content/blog/CLAUDE.md b/content/blog/CLAUDE.md
index 93ec042ac..30f9ee90f 100644
--- a/content/blog/CLAUDE.md
+++ b/content/blog/CLAUDE.md
@@ -62,6 +62,7 @@ Freeform. Avoid duplicating `software` or `topics` values.
 | `nohero` | Boolean, hides the hero image |
 | `hidesubscription` | Boolean, hides the subscription CTA |
 | `photo.url` / `photo.author` | Stock photo attribution |
+| `canonical_url` | Set only when another site's copy is the canonical version (e.g. the same post on `posit.co/blog`); the `<link rel="canonical">` tag and JSON-LD then point there. Omit for the default: our page is canonical (self-referencing tag). |
 | `code-line-numbers` | Boolean, turns on line-number gutters for every code block on the page |
 
 ## Project Blog Listing
diff --git a/layouts/partials/head.html b/layouts/partials/head.html
index efb953566..fc00edb47 100644
--- a/layouts/partials/head.html
+++ b/layouts/partials/head.html
@@ -9,6 +9,9 @@
   content="{{ with .Params.Keywords }}{{ delimit . ", " }}{{ else }}{{ $.Site.Params.Keywords }}{{ end }}"
 />
 <meta name="robots" content="noodp" />
+{{- /* Pages default to self-canonical; canonical_url in frontmatter defers to
+     another site's copy (e.g. posit.co/blog) */ -}}
+<link rel="canonical" href="{{ or .Params.canonical_url .Permalink }}" />
 {{- if $.Site.Params.pwa.enabled }}<link rel="manifest" href="/manifest.json" />{{ end -}}
 
 {{- /* Custom Open Graph and Twitter images for blog posts */ -}}
diff --git a/layouts/partials/jsonld.html b/layouts/partials/jsonld.html
index e3ecbdc40..c5b14e143 100644
--- a/layouts/partials/jsonld.html
+++ b/layouts/partials/jsonld.html
@@ -27,12 +27,13 @@
   -}}
 
 {{- else if and (eq .Section "blog") .IsPage -}}
+  {{- $canonical := or .Params.canonical_url .Permalink -}}
   {{- $ld = dict
         "@context" "https://schema.org"
         "@type" "BlogPosting"
         "headline" .Title
-        "url" .Permalink
-        "mainEntityOfPage" (dict "@type" "WebPage" "@id" .Permalink)
+        "url" $canonical
+        "mainEntityOfPage" (dict "@type" "WebPage" "@id" $canonical)
         "datePublished" (.Date.Format "2006-01-02T15:04:05-07:00")
         "dateModified" (.Lastmod.Format "2006-01-02T15:04:05-07:00")
         "publisher" $org