Merge pull request #96 from john-kurkowski/astro-seo

john-kurkowski · web-flow · commit 3bad20c468d9 · 2026-06-13T23:20:51.000-07:00
- Adopt `astro-seo` for canonical, description, Open Graph, Twitter, profile, and article metadata
- Make social preview image handling explicit across posts, including required alt text for image-backed posts and a new 1200x630 fallback image
- Use Netlify deploy-preview hosts for absolute metadata URLs so preview crawlers can fetch branch-only assets
- Add TypeScript metadata tests covering descriptions, social images, fallback metadata, and article Open Graph output
diff --git a/AGENTS.md b/AGENTS.md
@@ -2,3 +2,7 @@
 
 - After changing any file, before ending the turn, run `npm run check:fix`. Fix
   any reported issues until the command passes cleanly.
+- When changing application code, content schemas, build behavior, or tests,
+  also run `npm test`.
+- Mirror source paths when naming tests for application modules. For example,
+  tests for `src/config/site.ts` belong in `test/config/site.test.ts`.
diff --git a/astro.config.ts b/astro.config.ts
@@ -3,6 +3,7 @@ import mdx from "@astrojs/mdx"
 import sitemap from "@astrojs/sitemap"
 import tailwindcss from "@tailwindcss/vite"
 import { defineConfig } from "astro/config"
+import { getSiteUrl } from "./src/config/site"
 
 const parsePublishTime: RemarkPlugin = () => (_tree, file) => {
   const maybeDateString = /\d+-\d+-\d+/.exec(file.path)
@@ -30,7 +31,7 @@ export default defineConfig({
     },
   },
 
-  site: "https://johnkurkowski.com",
+  site: getSiteUrl(),
   integrations: [mdx(), sitemap()],
 
   vite: {
diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -1,6 +1,7 @@
 {
   "name": "john-kurkowski.github.io",
   "version": "1.0.0",
+  "type": "module",
   "description": "Source for https://johnkurkowski.com.",
   "scripts": {
     "astro": "astro",
@@ -11,7 +12,7 @@
     "prepare": "astro sync",
     "preview": "astro preview --host",
     "start": "astro dev --host",
-    "test": "npm run check",
+    "test": "npm run check && npm run build && node --test 'test/**/*.test.ts'",
     "type-check": "astro check"
   },
   "repository": {
@@ -28,6 +29,7 @@
     "@astrojs/sitemap": "^3.7.3",
     "@tailwindcss/vite": "^4.3.1",
     "astro": "^6.4.6",
+    "astro-seo": "^1.1.0",
     "tailwindcss": "^4.3.1"
   },
   "devDependencies": {
diff --git a/public/avatar-social.jpeg b/public/avatar-social.jpeg
diff --git a/src/components/layouts/Seo.astro b/src/components/layouts/Seo.astro
@@ -1,4 +1,6 @@
 ---
+import { SEO } from "astro-seo"
+
 const { frontmatter, siteMetadata } = Astro.props
 let title: string
 if (frontmatter.title?.includes(siteMetadata.title)) {
@@ -12,20 +14,87 @@ if (frontmatter.title?.includes(siteMetadata.title)) {
 const date = frontmatter.date ? new Date(frontmatter.date) : null
 
 const description = frontmatter.description || siteMetadata.description
+const isArticle = Boolean(date)
+const siteUrl = Astro.site || new URL(Astro.url.origin)
+const canonical = new URL(Astro.url.pathname, siteUrl).href
+const defaultImage = new URL("/avatar-social.jpeg", siteUrl).href
+const defaultImageDimensions = {
+  height: 630,
+  width: 1200,
+}
+const image = frontmatter.image
+const postImageUrls = import.meta.glob(
+  "../../content/posts/**/*.{png,jpg,jpeg,webp}",
+  {
+    eager: true,
+    import: "default",
+    query: "?url",
+  },
+) as Record<string, string>
+const rawImagePath =
+  typeof image === "string" ? image.replace(/^\.\//, "/") : ""
+const imageSrc =
+  typeof image === "string"
+    ? Object.entries(postImageUrls).find(([path]) =>
+        path.endsWith(rawImagePath),
+      )?.[1]
+    : image?.src
+const imageUrl = new URL(imageSrc || defaultImage, siteUrl).href
+const imageAlt = image ? frontmatter.imageAlt : "John Kurkowski"
+const imageDimensions = image
+  ? {
+      height: image.height,
+      width: image.width,
+    }
+  : defaultImageDimensions
+const article = date
+  ? {
+      authors: [siteMetadata.title],
+      publishedTime: date.toISOString(),
+      tags: frontmatter.tags,
+    }
+  : undefined
 ---
 
-<title>{title}</title>
-<meta property="og:title" content={title}>
+<SEO
+  charset="utf-8"
+  canonical={canonical}
+  description={description}
+  openGraph={{
+    basic: {
+      image: imageUrl,
+      title,
+      type: isArticle ? "article" : "website",
+      url: canonical,
+    },
+    optional: {
+      description,
+      siteName: siteMetadata.title,
+    },
+    image: {
+      alt: imageAlt,
+      height: imageDimensions.height,
+      width: imageDimensions.width,
+    },
+    ...(article ? { article } : {}),
+  }}
+  title={title}
+  twitter={{
+    card: "summary_large_image",
+    creator: "@bluu",
+    description,
+    image: imageUrl,
+    imageAlt,
+    site: "@bluu",
+    title,
+  }}
+/>
 
 <meta name="author" content={siteMetadata.title}>
-<meta property="og:author" content={siteMetadata.url}>
-
-<meta name="description" content={description}>
-<meta name="twitter:description" content={description}>
+<meta property="og:author" content={canonical}>
 
 {date && <meta http-equiv='date' content={date.toISOString()} />}
 
-<meta charset="utf-8">
 <meta content="John" property="profile:first_name">
 <meta content="Kurkowski" property="profile:last_name">
 
@@ -52,8 +121,3 @@ const description = frontmatter.description || siteMetadata.description
 
 <link href="/favicon.ico" rel="shortcut icon">
 <link href="/avatar@2X.jpeg" rel="apple-touch-icon">
-<meta content="/avatar@2X.jpeg" property="og:image">
-<meta content="/avatar@2X.jpeg" name="twitter:image:src">
-<meta content="summary" name="twitter:card">
-<meta content="@bluu" name="twitter:site">
-<meta content="@bluu" name="twitter:creator">
diff --git a/src/config/site.ts b/src/config/site.ts
@@ -1,3 +1,19 @@
+export const productionSiteUrl = "https://johnkurkowski.com"
+
+/**
+ * Social metadata needs absolute URLs, but Netlify deploy previews must point at
+ * their preview host so crawlers can fetch assets before they exist in
+ * production.
+ */
+export function getSiteUrl(env = process.env) {
+  return (
+    env.DEPLOY_PRIME_URL ||
+    env.DEPLOY_URL ||
+    env.URL ||
+    productionSiteUrl
+  ).replace(/\/$/, "")
+}
+
 export const siteMetadata = {
   description:
     "With 14+ years in the game, I help frontend teams ship incrementally, with test coverage confidence, without rewrites. Debug any app, existing or legacy. Collaborate on distributed teams via docs, code review, and mentorship.",
diff --git a/src/content.config.ts b/src/content.config.ts
@@ -7,12 +7,20 @@ import { z } from "astro/zod"
 const posts = defineCollection({
   loader: glob({ pattern: "**/[^_]*.{md,mdx}", base: "./src/content/posts" }),
 
-  schema: z.object({
-    description: z.string(),
-    title: z.string(),
-    categories: z.array(z.string()),
-    tags: z.array(z.string()),
-  }),
+  schema: ({ image }) =>
+    z
+      .object({
+        description: z.string(),
+        title: z.string(),
+        categories: z.array(z.string()),
+        tags: z.array(z.string()),
+        image: image().nullable(),
+        imageAlt: z.string().optional(),
+      })
+      .refine((data) => data.image === null || data.imageAlt, {
+        message: "imageAlt is required when image is set",
+        path: ["imageAlt"],
+      }),
 })
 
 export const collections = { posts }
diff --git a/src/content/posts/2011-10-06-avoid-git-first-drafts.mdx b/src/content/posts/2011-10-06-avoid-git-first-drafts.mdx
@@ -7,6 +7,7 @@ description:
   Here are pages rife with debate on using git pull vs. git pull --rebase. I’ve
   decided for myself there are times for both, that is, there are times for
   merge commits and not.
+image: null
 ---
 
 Here are
diff --git a/src/content/posts/2013-05-27-accumulating-multiple-failures-in-a-ValidationNEL.mdx b/src/content/posts/2013-05-27-accumulating-multiple-failures-in-a-ValidationNEL.mdx
@@ -8,6 +8,7 @@ description: >-
   To preface, Gravity likes to use 2 very predictable patterns throughout its
   Scala codebase, which is very important for a TIMTOWTDI language like Scala:
   the for-comprehension and ValidationNEL.
+image: null
 ---
 
 This is an adaptation of an internal blog post I made for
diff --git a/src/content/posts/2013-10-16-credo.mdx b/src/content/posts/2013-10-16-credo.mdx
@@ -8,6 +8,7 @@ description:
   think they add human value—to customers and teammates alike—and GTD value. All
   while keeping me happy with my career in the otherwise often bitter IT
   ecosystem.
+image: null
 ---
 
 Here’s a collection of the high-level concepts I’ve adopted over the years. I
diff --git a/src/content/posts/2014-01-28-good-ideas-from-mobile-design-that-are-good-everywhere.mdx b/src/content/posts/2014-01-28-good-ideas-from-mobile-design-that-are-good-everywhere.mdx
@@ -6,6 +6,8 @@ tags: [engineering, usability]
 description:
   A collection of 9 usability tips from mobile design, yet they benefit desktop
   users too. 2 birds, 1 stone.
+image: ./pagespeed_insights.png
+imageAlt: PageSpeed Insights - screenshot
 ---
 
 import gmailsNewCompose from './gmails-new-compose.png'
diff --git a/src/content/posts/2014-02-05-dont-learn-to-code-learn-to-program-but-come-back-in-10-years.mdx b/src/content/posts/2014-02-05-dont-learn-to-code-learn-to-program-but-come-back-in-10-years.mdx
@@ -8,6 +8,7 @@ description:
   no longer support the Learn to Code movement. I can no longer tell my friends
   to learn coding. Although I’m passionate about it, it’s too arcane and insular
   for mainstream practice.
+image: null
 ---
 
 I want to discuss why programming and coding are not the same, and why I can no
diff --git a/src/content/posts/2014-02-25-ongoing-learning-in-breadth-&-depth.mdx b/src/content/posts/2014-02-25-ongoing-learning-in-breadth-&-depth.mdx
@@ -8,6 +8,7 @@ description:
   changing daily, I’d like to offer some peace of mind. In my previous article,
   I questioned the rampant, disconnected proliferation of code. I don’t know why
   it is stuck the way it is.
+image: null
 ---
 
 To those overwhelmed by all the programming languages and tools you can learn,
diff --git a/src/content/posts/2014-09-05-code-as-craft-as-career.mdx b/src/content/posts/2014-09-05-code-as-craft-as-career.mdx
@@ -6,6 +6,7 @@ tags: [engineering, programming]
 description:
   As a career programmer, I pursue code mastery. Economics at scale however
   stamps out the craftsman. How do I stay ahead?
+image: null
 ---
 
 I see 2 paths of career programmers around me: 1) transition to leadership, 2)
diff --git a/src/content/posts/2014-09-08-paint-by-types.mdx b/src/content/posts/2014-09-08-paint-by-types.mdx
@@ -8,6 +8,8 @@ description:
   type-driven development. The type system self-documents better than any
   docstring or variable name ever did. It even guides your thinking and program
   architecture.
+image: ./paint-by-numbers.jpg
+imageAlt: Paint By Numbers example
 ---
 
 import paintByNumbers from './paint-by-numbers.jpg'
diff --git a/src/content/posts/2015-03-18-1st-class-ux-for-web-programmers.mdx b/src/content/posts/2015-03-18-1st-class-ux-for-web-programmers.mdx
@@ -6,6 +6,8 @@ tags: [engineering, usability]
 description:
   On the web, your users are no longer a secondary engineering concern. A
   thick-client framework, like Ember.js, makes UX 1st class.
+image: ./google-chrome-dinosaur.png
+imageAlt: Google Chrome's network error screen
 ---
 
 import googleChromeDinosaur from './google-chrome-dinosaur.png'
diff --git a/src/content/posts/2025-04-03-still-measuring-devs-with-leetcode.mdx b/src/content/posts/2025-04-03-still-measuring-devs-with-leetcode.mdx
@@ -8,6 +8,7 @@ description:
   Companies haven't listened to old advice on competitive hiring like DHH's
   "Hiring programmers with a take-home test" or Matasano Security's "the Hiring
   Post".
+image: null
 ---
 
 I'm disappointed to find tech interviews in 2025 are still asking LeetCode
diff --git a/src/content/posts/2025-05-20-procrastination-by-doing.mdx b/src/content/posts/2025-05-20-procrastination-by-doing.mdx
@@ -8,6 +8,10 @@ description:
   instead watch Netflix, unable to get off the couch. I will do productive work.
   It just won't be the assigned task. I have some tips to fight this
   procrastination."
+image: ./jar-of-rocks.webp
+imageAlt:
+  A pencil sketch of a jar mostly full of sand, with several rocks and pebbles
+  interspersed.
 ---
 
 import jarOfRocks from './jar-of-rocks.webp'
diff --git a/src/content/posts/2025-05-23-procrastination-by-perfection.mdx b/src/content/posts/2025-05-23-procrastination-by-perfection.mdx
@@ -7,6 +7,7 @@ description:
   "I also suffer from a less common form of procrastination than my previous
   article. I would not attempt something at all if I knew I couldn't do it
   perfectly. On a hobby of mine, I discovered a decent workaround."
+image: null
 ---
 
 I also suffer from a less common form of procrastination than my [previous
diff --git a/src/content/posts/2026-04-07-hands-on-home-row-for-ai-assisted-coding.mdx b/src/content/posts/2026-04-07-hands-on-home-row-for-ai-assisted-coding.mdx
@@ -8,6 +8,8 @@ description:
   tools I spent years sharpening. Agent orchestration may be the industry
   productivity boost I long wanted. While engineering discipline still matters,
   I feel wistful for hands-on coding.
+image: ./2026-04-07-hands-on-home-row-for-ai-assisted-coding/03-terminal-multiple-agents.png
+imageAlt: Wireframe of 3 agent panes handling separate coding tasks in parallel.
 ---
 
 import cursorLikeLayoutWireframe from './2026-04-07-hands-on-home-row-for-ai-assisted-coding/01-cursor-layout.png'
diff --git a/test/components/layouts/Seo.test.ts b/test/components/layouts/Seo.test.ts
diff --git a/test/config/site.test.ts b/test/config/site.test.ts
