Fix description and image on social cards

Author: webstackdev

src/components/Head/Social.astro

@@ -21,6 +21,8 @@ const site = resolveSiteUrl(Astro)
 <meta property="og:title" content={title} />
 <meta property="og:description" content={description} />
 <meta property="og:image" content={getSocialImageLink(path, site)} />
+<meta property="og:image:width" content="1200" />
+<meta property="og:image:height" content="630" />
 <meta property="og:image:alt" content={`Social card for ${title}`} />
 {/* Canonical URL of the page */}
 <meta property="og:url" content={absoluteUrl(path, site)} />
@@ -30,3 +32,7 @@ const site = resolveSiteUrl(Astro)
 <meta name="twitter:card" content="summary_large_image" />
 <meta name="twitter:site" content="@webstackdev" />
 <meta name="twitter:creator" content="@webstackdev" />
+<meta name="twitter:title" content={title} />
+<meta name="twitter:description" content={description} />
+<meta name="twitter:image" content={getSocialImageLink(path, site)} />
+<meta name="twitter:image:alt" content={`Social card for ${title}`} />

src/components/Head/__tests__/Social.spec.ts

@@ -0,0 +1,55 @@
+import { beforeEach, describe, expect, test } from 'vitest'
+import { experimental_AstroContainer as AstroContainer } from 'astro/container'
+import { JSDOM } from 'jsdom'
+
+describe('Social (Astro)', () => {
+  let container: AstroContainer
+
+  beforeEach(async () => {
+    container = await AstroContainer.create()
+  })
+
+  test('renders explicit Open Graph and Twitter image metadata', async () => {
+    const Social = (await import('@components/Head/Social.astro')).default
+    const title = 'Platform Engineering for Modern Teams'
+    const description =
+      'Platform engineer Kevin Brown builds resilient delivery platforms, cloud foundations, and better developer experience.'
+
+    const response = await container.renderToResponse(Social, {
+      props: {
+        title,
+        description,
+        path: '/',
+      },
+      request: new Request('https://example.com/'),
+      partial: false,
+    })
+
+    const renderedHtml = await response.text()
+    const document = new JSDOM(renderedHtml).window.document
+    const socialImageUrl = 'https://example.com/api/social-card?slug=home'
+
+    expect(document.querySelector('meta[property="og:title"]')?.getAttribute('content')).toBe(title)
+    expect(document.querySelector('meta[property="og:description"]')?.getAttribute('content')).toBe(
+      description
+    )
+    expect(document.querySelector('meta[property="og:image"]')?.getAttribute('content')).toBe(
+      socialImageUrl
+    )
+    expect(document.querySelector('meta[property="og:image:width"]')?.getAttribute('content')).toBe(
+      '1200'
+    )
+    expect(document.querySelector('meta[property="og:image:height"]')?.getAttribute('content')).toBe(
+      '630'
+    )
+    expect(document.querySelector('meta[name="twitter:title"]')?.getAttribute('content')).toBe(
+      title
+    )
+    expect(document.querySelector('meta[name="twitter:description"]')?.getAttribute('content')).toBe(
+      description
+    )
+    expect(document.querySelector('meta[name="twitter:image"]')?.getAttribute('content')).toBe(
+      socialImageUrl
+    )
+  })
+})

src/content/contact.json

@@ -34,7 +34,7 @@
       {
         "network": "linkedin",
         "name": "webstack-builders",
-        "url": "https://www.linkedin.com/company/webstack-builders",
+        "url": "https://www.linkedin.com/in/kevin-brown-developer/",
         "order": 2,
         "displayName": "LinkedIn",
         "iconName": "linkedin",

src/pages/api/social-card/__tests__/index.spec.ts

@@ -1,6 +1,14 @@
 import { beforeEach, describe, expect, it, vi } from 'vitest'
 import { GET } from '@pages/api/social-card'
 
+const avatarFetchMock = vi.hoisted(() => vi.fn())
+
+vi.mock('@assets/images/avatars/kevin-brown.webp', () => ({
+  default: {
+    src: '/_astro/kevin-brown.test.webp',
+  },
+}))
+
 type CollectionFixture = Array<{
   id: string
   data: {
@@ -33,6 +41,8 @@ vi.mock('astro-og-canvas', () => ({
   generateOpenGraphImage: generateOpenGraphImageMock,
 }))
 
+vi.stubGlobal('fetch', avatarFetchMock)
+
 const buildRequest = (url: string) =>
   GET({
     request: new Request(url),
@@ -69,6 +79,11 @@ describe('Social Card API - GET /api/social-card', () => {
   beforeEach(() => {
     generateOpenGraphImageMock.mockReset()
     generateOpenGraphImageMock.mockResolvedValue(Buffer.from('mock-image'))
+    avatarFetchMock.mockReset()
+    avatarFetchMock.mockResolvedValue({
+      ok: true,
+      arrayBuffer: async () => Uint8Array.from([1, 2, 3]).buffer,
+    })
     seedCollections()
   })
 
@@ -83,6 +98,9 @@ describe('Social Card API - GET /api/social-card', () => {
       expect.objectContaining({
         title: 'Sample Article',
         description: 'Article Description',
+        logo: expect.objectContaining({
+          size: [140, 140],
+        }),
       })
     )
 
@@ -104,6 +122,31 @@ describe('Social Card API - GET /api/social-card', () => {
     )
   })
 
+  it('uses updated platform engineering defaults for the homepage slug', async () => {
+    const response = await buildRequest('http://localhost/api/social-card?slug=home')
+
+    expect(response.status).toBe(200)
+    expect(generateOpenGraphImageMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        title: 'Platform Engineering by Kevin Brown',
+        description:
+          'Platform engineer helping teams harden delivery, modernize cloud platforms, and improve developer experience.',
+      })
+    )
+  })
+
+  it('uses the Kevin Brown avatar file when generating a card', async () => {
+    await buildRequest('http://localhost/api/social-card?slug=home')
+
+    expect(generateOpenGraphImageMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        logo: expect.objectContaining({
+          path: expect.stringMatching(/kevin-brown\.webp$/u),
+        }),
+      })
+    )
+  })
+
   it('returns an error response when generation fails', async () => {
     generateOpenGraphImageMock.mockRejectedValueOnce(new Error('boom'))
 

src/pages/api/social-card/index.ts

@@ -1,16 +1,21 @@
-import { fileURLToPath } from 'node:url'
+import { mkdir, readFile, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
 import type { APIRoute } from 'astro'
 import { getCollection } from 'astro:content'
 import { generateOpenGraphImage } from 'astro-og-canvas'
+import kevinBrownAvatar from '@assets/images/avatars/kevin-brown.webp'
 import { buildApiErrorResponse, handleApiFunctionError } from '@pages/api/_utils/errors'
 import { createApiFunctionContext } from '@pages/api/_utils/requestContext'
 
 export const prerender = false
 
 const ROUTE = '/api/social-card'
-const DEFAULT_TITLE = 'Webstack Builders'
-const DEFAULT_DESCRIPTION = 'Professional Web Development Services'
-const LOGO_PATH = fileURLToPath(new URL('../../../../assets/images/site/logo.png', import.meta.url))
+const DEFAULT_TITLE = 'Platform Engineering by Kevin Brown'
+const DEFAULT_DESCRIPTION =
+  'Platform engineer helping teams harden delivery, modernize cloud platforms, and improve developer experience.'
+const AVATAR_CACHE_DIR = join(tmpdir(), 'webstackbuilders-social-card')
+const AVATAR_CACHE_PATH = join(AVATAR_CACHE_DIR, 'kevin-brown.webp')
 
 type CollectionKey = 'articles' | 'caseStudies' | 'services' | 'downloads'
 type PaletteKey = 'articles' | 'case-studies' | 'services' | 'downloads' | 'default'
@@ -56,6 +61,26 @@ const gradientPalette: Record<PaletteKey, [number, number, number][]> = {
   ],
 }
 
+const getAvatarUrl = (requestUrl: URL): URL => new URL(kevinBrownAvatar.src, requestUrl)
+
+const ensureAvatarFile = async (requestUrl: URL): Promise<string> => {
+  try {
+    await readFile(AVATAR_CACHE_PATH)
+    return AVATAR_CACHE_PATH
+  } catch {
+    const response = await fetch(getAvatarUrl(requestUrl))
+
+    if (!response.ok) {
+      throw new Error(`Unable to load avatar image: ${response.status} ${response.statusText}`)
+    }
+
+    const avatarBuffer = Buffer.from(await response.arrayBuffer())
+    await mkdir(AVATAR_CACHE_DIR, { recursive: true })
+    await writeFile(AVATAR_CACHE_PATH, avatarBuffer)
+    return AVATAR_CACHE_PATH
+  }
+}
+
 /** Normalize slug parameters to a consistent format */
 const normalizeSlug = (value: string | null): string => {
   if (!value) return 'home'
@@ -119,6 +144,7 @@ export const GET: APIRoute = async ({ request, clientAddress, cookies }) => {
     const slug = normalizeSlug(url.searchParams.get('slug'))
     const titleOverride = url.searchParams.get('title')
     const descriptionOverride = url.searchParams.get('description')
+    const avatarPath = await ensureAvatarFile(url)
 
     const contentIndex = await buildContentIndex()
     const matchedEntry = contentIndex[slug]
@@ -138,8 +164,8 @@ export const GET: APIRoute = async ({ request, clientAddress, cookies }) => {
       bgGradient: gradientPalette[palette],
       padding: 80,
       logo: {
-        path: LOGO_PATH,
-        size: [180],
+        path: avatarPath,
+        size: [140, 140],
       },
       font: {
         title: {

src/pages/index.astro

@@ -11,8 +11,9 @@ import Newsletter from '@components/CallToAction/Newsletter/index.astro'
 import Skills from '@components/Home/Skills/index.astro'
 import Testimonials from '@components/Testimonials/index.astro'
 
-const pageDescription = 'Webstack Builders, Inc. Home Page'
-const pageTitle = 'Web Development & Digital Solutions - Webstack Builders, Inc.'
+const pageDescription =
+  'Platform engineer Kevin Brown builds resilient delivery platforms, cloud foundations, and better developer experience.'
+const pageTitle = 'Platform Engineering for Modern Teams'
 const sectionClasses = 'container mx-auto px-4 sm:px-6 lg:px-8 py-4 md:py-8 lg:py-12'
 ---