Skip to content

armgit / alook

Public Imported from GitHub
0

Multi-Agent Collaboration for Team and Friends

feat(web): redesign blog homepage (#693)

Gener3590406072ab
diff --git a/src/web/blog/src/app/blog/(index)/model.test.ts b/src/web/blog/src/app/blog/(index)/model.test.ts
new file mode 100644
index 000000000..b25e6ca4b
--- /dev/null
+++ b/src/web/blog/src/app/blog/(index)/model.test.ts
@@ -0,0 +1,69 @@
+import { describe, expect, it } from "vitest";
+import type { BlogPost } from "@blog/lib/blog/posts";
+import { buildBlogIndexModel, formatBlogPostDate } from "./model";
+
+function post(
+ slug: string,
+ date: string,
+ image?: string,
+): BlogPost {
+ return {
+ slug,
+ title: slug,
+ date,
+ author: "Alook",
+ excerpt: `${slug} excerpt`,
+ readingTime: "5 min read",
+ image,
+ };
+}
+
+describe("buildBlogIndexModel", () => {
+ it("selects the newest post as Featured and excludes it from ordered Recent", () => {
+ const model = buildBlogIndexModel([
+ post("personal-ai-company", "2026-08-01"),
+ post("local-ai-agents", "2026-09-01"),
+ post("ai-agent-vs-chatbot", "2026-08-20"),
+ ]);
+
+ expect(model.featured?.slug).toBe("local-ai-agents");
+ expect(model.recent.map((item) => item.slug)).toEqual([
+ "ai-agent-vs-chatbot",
+ "personal-ai-company",
+ ]);
+ expect(model.recent).not.toContainEqual(
+ expect.objectContaining({ slug: "local-ai-agents" }),
+ );
+ });
+
+ it("preserves hero images and resolves missing ones through the canonical OG fallback", () => {
+ const model = buildBlogIndexModel([
+ post("ai-agent-vs-chatbot", "2026-08-20", "/blog/ai-agent-vs-chatbot/hero.webp"),
+ post("local-ai-agents", "2026-09-01"),
+ ]);
+
+ expect(model.featured?.imageUrl).toBe("/og/blog/local-ai-agents");
+ expect(model.recent[0]?.imageUrl).toBe(
+ "/blog/ai-agent-vs-chatbot/hero.webp",
+ );
+ expect(model.featured?.topicId).toBe("foundations-team-design");
+ });
+
+ it.each(["America/Los_Angeles", "Pacific/Honolulu"])(
+ "keeps date-only metadata on the authored calendar day in %s",
+ (timeZone) => {
+ const previousTimeZone = process.env.TZ;
+ process.env.TZ = timeZone;
+
+ try {
+ expect(formatBlogPostDate("2026-09-01")).toBe("Sep 1, 2026");
+ } finally {
+ if (previousTimeZone === undefined) {
+ delete process.env.TZ;
+ } else {
+ process.env.TZ = previousTimeZone;
+ }
+ }
+ },
+ );
+});
diff --git a/src/web/blog/src/app/blog/(index)/model.ts b/src/web/blog/src/app/blog/(index)/model.ts
new file mode 100644
index 000000000..b63323e43
--- /dev/null
+++ b/src/web/blog/src/app/blog/(index)/model.ts
@@ -0,0 +1,46 @@
+import type { BlogPost } from "@blog/lib/blog/posts";
+import { getBlogTopicBySlug } from "@blog/lib/blog/topics";
+import { getBlogOgImage } from "../[slug]/og-image";
+
+export type BlogIndexPost = BlogPost & {
+ imageUrl: string;
+ topicId: string;
+ topicLabel: string;
+};
+
+export type BlogIndexModel = {
+ featured: BlogIndexPost | undefined;
+ recent: BlogIndexPost[];
+};
+
+export function buildBlogIndexModel(
+ posts: readonly BlogPost[],
+): BlogIndexModel {
+ const orderedPosts = [...posts].sort(
+ (a, b) => new Date(b.date).getTime() - new Date(a.date).getTime(),
+ );
+ const indexPosts = orderedPosts.map((post) => {
+ const topic = getBlogTopicBySlug(post.slug);
+
+ return {
+ ...post,
+ imageUrl: getBlogOgImage(post),
+ topicId: topic?.id ?? "other",
+ topicLabel: topic?.label ?? "More from Alook",
+ };
+ });
+
+ return {
+ featured: indexPosts[0],
+ recent: indexPosts.slice(1),
+ };
+}
+
+export function formatBlogPostDate(date: string): string {
+ return new Date(date).toLocaleDateString("en-US", {
+ year: "numeric",
+ month: "short",
+ day: "numeric",
+ timeZone: "UTC",
+ });
+}
diff --git a/src/web/blog/src/app/blog/(index)/page.tsx b/src/web/blog/src/app/blog/(index)/page.tsx
index 70b0d2740..de6870221 100644
--- a/src/web/blog/src/app/blog/(index)/page.tsx
+++ b/src/web/blog/src/app/blog/(index)/page.tsx
@@ -1,13 +1,12 @@
import type { Metadata } from "next";
+import Image from "next/image";
import Link from "next/link";
import { getAllPosts } from "@blog/lib/blog/posts";
-import {
- blogTopics,
- getBlogTopicEntryBySlug,
- getPostsForTopic,
-} from "@blog/lib/blog/topics";
+import { blogTopics } from "@blog/lib/blog/topics";
+import { buildBlogIndexModel, formatBlogPostDate } from "./model";
+import { RecentPosts } from "./recent-posts";
-const pageTitle = "Multi-Agent Collaboration & AI Team";
+const pageTitle = "Blog";
const description =
"Thoughts on building AI companies, agent collaboration, and the future of personal software.";
@@ -44,6 +43,7 @@ const collectionJsonLd = {
export default async function BlogPage() {
const posts = await getAllPosts();
+ const { featured, recent } = buildBlogIndexModel(posts);
return (
<>
@@ -51,151 +51,59 @@ export default async function BlogPage() {
type="application/ld+json"
dangerouslySetInnerHTML={{ __html: JSON.stringify(collectionJsonLd) }}
/>
- <div className="mx-auto max-w-5xl px-6 pt-10 sm:pt-20 pb-24">
- <header className="max-w-3xl">
- <h1 className="font-news text-5xl sm:text-6xl font-semibold tracking-tight leading-none">
- {pageTitle}
+ <div className="mx-auto max-w-270 px-4 pb-24 pt-12 sm:px-6 sm:pt-20">
+ <header>
+ <h1 className="font-news text-3xl font-semibold leading-none tracking-tight sm:text-[2.5rem] sm:leading-12">
+ Blog
</h1>
- <p className="mt-4 text-[1.0625rem] text-muted-foreground font-sans leading-relaxed max-w-xl">
- {description}
- </p>
- <p className="mt-4 text-xs font-mono uppercase tracking-[0.15em] text-muted-foreground/60">
- <a
- href="/blog/feed.xml"
- className="transition-opacity hover:opacity-70"
- >
- RSS
- </a>
- <span className="mx-2 opacity-40">·</span>
- <a href="/llms.txt" className="transition-opacity hover:opacity-70">
- llms.txt
- </a>
- </p>
</header>
- <nav
- aria-label="Blog topics"
- className="mt-12 grid gap-px overflow-hidden rounded-xl border border-border bg-border sm:grid-cols-2 lg:grid-cols-4"
- >
- {blogTopics.map((topic, index) => (
- <a
- key={topic.id}
- href={`#${topic.id}`}
- className="group bg-background px-5 py-5 transition-colors hover:bg-muted/60"
+ {featured ? (
+ <section aria-label="Featured article" className="mt-8">
+ <Link
+ href={`/blog/${featured.slug}`}
+ className="group grid rounded-lg focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-4 focus-visible:ring-offset-background sm:grid-cols-2 sm:gap-12"
>
- <span className="font-mono text-[11px] tabular-nums text-muted-foreground/50">
- {String(index + 1).padStart(2, "0")}
+ <span className="relative block aspect-video overflow-hidden rounded-lg bg-muted">
+ <Image
+ src={featured.imageUrl}
+ alt=""
+ fill
+ preload
+ sizes="(max-width: 639px) calc(100vw - 2rem), 31rem"
+ className="object-cover transition-transform duration-200 group-hover:scale-[1.015] motion-reduce:transform-none"
+ />
</span>
- <span className="mt-3 block font-sans text-sm font-medium leading-snug group-hover:translate-x-0.5 transition-transform duration-200">
- {topic.label}
+ <span className="flex flex-col justify-center pt-6 sm:py-4">
+ <span className="flex flex-wrap items-center gap-x-3 gap-y-1 font-sans text-sm text-muted-foreground">
+ <span>{featured.topicLabel}</span>
+ <span aria-hidden="true">
+ ·
+ </span>
+ <time dateTime={featured.date}>
+ {formatBlogPostDate(featured.date)}
+ </time>
+ </span>
+ <h2 className="mt-3 font-news text-3xl font-semibold leading-tight tracking-tight">
+ {featured.title}
+ </h2>
+ <span className="mt-3 line-clamp-3 font-sans leading-relaxed text-foreground/70">
+ {featured.excerpt}
+ </span>
</span>
- </a>
- ))}
- </nav>
-
- <div className="mt-24 space-y-24">
- {blogTopics.map((topic, topicIndex) => {
- const topicPosts = getPostsForTopic(topic, posts);
- const pillar = topicPosts.find(
- (post) => post.slug === topic.pillarSlug
- );
- const supportPosts = topicPosts.filter(
- (post) => post.slug !== topic.pillarSlug
- );
-
- return (
- <section
- key={topic.id}
- id={topic.id}
- className="scroll-mt-24"
- aria-labelledby={`${topic.id}-heading`}
- >
- <div className="grid gap-5 border-t border-border pt-7 md:grid-cols-[11rem_1fr] md:gap-10">
- <p className="font-mono text-xs uppercase tracking-[0.16em] text-muted-foreground/60">
- Topic {String(topicIndex + 1).padStart(2, "0")}
- </p>
- <div>
- <h2
- id={`${topic.id}-heading`}
- className="font-news text-3xl sm:text-4xl font-semibold tracking-tight leading-tight"
- >
- {topic.label}
- </h2>
- <p className="mt-3 max-w-2xl font-sans text-foreground/70 leading-relaxed">
- {topic.description}
- </p>
- </div>
- </div>
-
- {pillar && (
- <Link
- href={`/blog/${pillar.slug}`}
- className="group mt-10 block rounded-xl border border-border bg-muted/25 p-6 sm:p-8 transition-colors hover:bg-muted/50"
- >
- <span className="font-mono text-[11px] uppercase tracking-[0.16em] text-muted-foreground/60">
- Start here
- </span>
- <div className="mt-4 grid gap-4 md:grid-cols-[1fr_14rem] md:gap-10">
- <div>
- <h3 className="font-news text-2xl sm:text-3xl font-semibold tracking-tight leading-tight group-hover:translate-x-0.5 transition-transform duration-200">
- {pillar.title}
- </h3>
- <p className="mt-3 font-sans text-foreground/75 leading-relaxed">
- {pillar.excerpt}
- </p>
- </div>
- <div className="md:border-l md:border-border md:pl-6">
- <p className="font-mono text-[11px] uppercase tracking-[0.14em] text-muted-foreground/60">
- Use this to
- </p>
- <p className="mt-2 text-sm leading-relaxed text-foreground/80">
- {getBlogTopicEntryBySlug(pillar.slug)?.userJob}
- </p>
- <p className="mt-4 text-xs text-muted-foreground">
- {formatPostDate(pillar.date)} &middot;{" "}
- {pillar.readingTime}
- </p>
- </div>
- </div>
- </Link>
- )}
+ </Link>
+ </section>
+ ) : (
+ <p className="mt-16 font-sans text-muted-foreground">
+ New stories are on the way.
+ </p>
+ )}
- <div className="mt-4 grid gap-px overflow-hidden rounded-xl border border-border bg-border sm:grid-cols-2">
- {supportPosts.map((post) => (
- <article key={post.slug} className="bg-background">
- <Link
- href={`/blog/${post.slug}`}
- className="group flex h-full flex-col p-6 transition-colors hover:bg-muted/40"
- >
- <p className="font-mono text-[11px] uppercase tracking-[0.14em] text-muted-foreground/60">
- {getBlogTopicEntryBySlug(post.slug)?.userJob}
- </p>
- <h3 className="mt-3 font-news text-xl sm:text-2xl font-semibold tracking-tight leading-snug group-hover:translate-x-0.5 transition-transform duration-200">
- {post.title}
- </h3>
- <p className="mt-3 font-sans text-sm text-foreground/70 leading-relaxed">
- {post.excerpt}
- </p>
- <p className="mt-auto pt-5 text-xs text-muted-foreground">
- {formatPostDate(post.date)} &middot; {post.readingTime}
- </p>
- </Link>
- </article>
- ))}
- </div>
- </section>
- );
- })}
- </div>
+ <RecentPosts
+ posts={recent}
+ topics={blogTopics.map(({ id, label }) => ({ id, label }))}
+ />
</div>
</>
);
}
-
-function formatPostDate(date: string): string {
- return new Date(date).toLocaleDateString("en-US", {
- year: "numeric",
- month: "long",
- day: "numeric",
- });
-}
diff --git a/src/web/blog/src/app/blog/(index)/recent-posts.test.ts b/src/web/blog/src/app/blog/(index)/recent-posts.test.ts
new file mode 100644
index 000000000..e77f54f03
--- /dev/null
+++ b/src/web/blog/src/app/blog/(index)/recent-posts.test.ts
@@ -0,0 +1,166 @@
+import { createElement, type PropsWithChildren } from "react";
+import TestRenderer, { act, type ReactTestRenderer } from "react-test-renderer";
+import { describe, expect, it, vi } from "vitest";
+import type { BlogIndexPost } from "./model";
+import { RecentPosts } from "./recent-posts";
+
+vi.mock("next/image", () => ({
+ default: (props: Record<string, unknown>) => createElement("img", props),
+}));
+
+vi.mock("next/link", () => ({
+ default: ({ children, ...props }: PropsWithChildren<Record<string, unknown>>) =>
+ createElement("a", props, children),
+}));
+
+function recentPost(
+ slug: string,
+ topicId: string,
+ topicLabel: string,
+): BlogIndexPost {
+ return {
+ slug,
+ title: slug,
+ date: "2026-08-20",
+ author: "Alook",
+ excerpt: `${slug} excerpt`,
+ readingTime: "5 min read",
+ imageUrl: `/og/blog/${slug}`,
+ topicId,
+ topicLabel,
+ };
+}
+
+function renderedTitles(renderer: ReactTestRenderer): string[] {
+ return renderer.root
+ .findAllByType("h3")
+ .map((heading) => heading.children.join(""));
+}
+
+describe("RecentPosts", () => {
+ it("filters Recent cards, renders the empty state, and returns to All", () => {
+ const posts = [
+ recentPost("newest", "foundations", "Foundations"),
+ recentPost("middle", "coding", "Coding"),
+ recentPost("oldest", "foundations", "Foundations"),
+ ];
+ const topics = [
+ { id: "foundations", label: "Foundations" },
+ { id: "coding", label: "Coding" },
+ { id: "empty", label: "Empty" },
+ ];
+ let renderer: ReactTestRenderer;
+
+ act(() => {
+ renderer = TestRenderer.create(
+ createElement(RecentPosts, { posts, topics }),
+ );
+ });
+
+ expect(renderedTitles(renderer!)).toEqual(["newest", "middle", "oldest"]);
+
+ const codingButton = renderer!.root
+ .findAllByType("button")
+ .find((button) => button.children.join("") === "Coding");
+ act(() => codingButton?.props.onClick());
+
+ expect(codingButton?.props["aria-pressed"]).toBe(true);
+ expect(renderedTitles(renderer!)).toEqual(["middle"]);
+
+ const emptyButton = renderer!.root
+ .findAllByType("button")
+ .find((button) => button.children.join("") === "Empty");
+ act(() => emptyButton?.props.onClick());
+
+ expect(emptyButton?.props["aria-pressed"]).toBe(true);
+ expect(renderedTitles(renderer!)).toEqual([]);
+ expect(renderer!.root.findByType("p").children.join("")).toBe(
+ "No recent stories in this topic yet.",
+ );
+
+ const allButton = renderer!.root
+ .findAllByType("button")
+ .find((button) => button.children.join("") === "All");
+ act(() => allButton?.props.onClick());
+
+ expect(allButton?.props["aria-pressed"]).toBe(true);
+ expect(renderedTitles(renderer!)).toEqual(["newest", "middle", "oldest"]);
+ });
+
+ it("syncs the selected topic with the URL hash and browser history", () => {
+ const posts = [
+ recentPost("newest", "foundations", "Foundations"),
+ recentPost("middle", "coding", "Coding"),
+ recentPost("oldest", "foundations", "Foundations"),
+ ];
+ const topics = [
+ { id: "foundations", label: "Foundations" },
+ { id: "coding", label: "Coding" },
+ ];
+ let hashChangeListener: (() => void) | undefined;
+ const replaceState = vi.fn();
+ const removeEventListener = vi.fn();
+
+ vi.stubGlobal("window", {
+ location: {
+ hash: "#%63oding",
+ pathname: "/blog",
+ search: "?source=qa",
+ },
+ history: { replaceState },
+ addEventListener: vi.fn(
+ (eventName: string, listener: () => void) => {
+ if (eventName === "hashchange") hashChangeListener = listener;
+ },
+ ),
+ removeEventListener,
+ });
+
+ let renderer: ReactTestRenderer;
+ try {
+ act(() => {
+ renderer = TestRenderer.create(
+ createElement(RecentPosts, { posts, topics }),
+ );
+ });
+
+ const codingButton = renderer!.root
+ .findAllByType("button")
+ .find((button) => button.children.join("") === "Coding");
+ expect(codingButton?.props["aria-pressed"]).toBe(true);
+ expect(renderedTitles(renderer!)).toEqual(["middle"]);
+
+ const foundationsButton = renderer!.root
+ .findAllByType("button")
+ .find((button) => button.children.join("") === "Foundations");
+ act(() => foundationsButton?.props.onClick());
+ expect(replaceState).toHaveBeenLastCalledWith(
+ null,
+ "",
+ "/blog?source=qa#foundations",
+ );
+
+ const allButton = renderer!.root
+ .findAllByType("button")
+ .find((button) => button.children.join("") === "All");
+ act(() => allButton?.props.onClick());
+ expect(replaceState).toHaveBeenLastCalledWith(
+ null,
+ "",
+ "/blog?source=qa",
+ );
+
+ window.location.hash = "#not-a-topic";
+ act(() => hashChangeListener?.());
+ expect(renderedTitles(renderer!)).toEqual(["newest", "middle", "oldest"]);
+
+ act(() => renderer!.unmount());
+ expect(removeEventListener).toHaveBeenCalledWith(
+ "hashchange",
+ hashChangeListener,
+ );
+ } finally {
+ vi.unstubAllGlobals();
+ }
+ });
+});
diff --git a/src/web/blog/src/app/blog/(index)/recent-posts.tsx b/src/web/blog/src/app/blog/(index)/recent-posts.tsx
new file mode 100644
index 000000000..f2938313b
--- /dev/null
+++ b/src/web/blog/src/app/blog/(index)/recent-posts.tsx
@@ -0,0 +1,148 @@
+"use client";
+
+import { useEffect, useMemo, useState } from "react";
+import Image from "next/image";
+import Link from "next/link";
+import type { BlogIndexPost } from "./model";
+import { formatBlogPostDate } from "./model";
+
+type BlogTopicFilter = {
+ id: string;
+ label: string;
+};
+
+type RecentPostsProps = {
+ posts: readonly BlogIndexPost[];
+ topics: readonly BlogTopicFilter[];
+};
+
+const allTopicsId = "all";
+
+export function RecentPosts({ posts, topics }: RecentPostsProps) {
+ const [selectedTopicId, setSelectedTopicId] = useState(allTopicsId);
+ const topicIds = useMemo(() => new Set(topics.map((topic) => topic.id)), [topics]);
+ const visiblePosts =
+ selectedTopicId === allTopicsId
+ ? posts
+ : posts.filter((post) => post.topicId === selectedTopicId);
+
+ useEffect(() => {
+ if (typeof window === "undefined") return;
+
+ const syncTopicFromHash = () => {
+ const hashTopicId = decodeURIComponent(window.location.hash.slice(1));
+ setSelectedTopicId(topicIds.has(hashTopicId) ? hashTopicId : allTopicsId);
+ };
+
+ syncTopicFromHash();
+ window.addEventListener("hashchange", syncTopicFromHash);
+ return () => window.removeEventListener("hashchange", syncTopicFromHash);
+ }, [topicIds]);
+
+ const selectTopic = (topicId: string) => {
+ setSelectedTopicId(topicId);
+ if (typeof window === "undefined") return;
+
+ const nextUrl =
+ topicId === allTopicsId
+ ? `${window.location.pathname}${window.location.search}`
+ : `${window.location.pathname}${window.location.search}#${topicId}`;
+ window.history.replaceState(null, "", nextUrl);
+ };
+
+ return (
+ <section aria-labelledby="recent-posts-heading" className="mt-12 sm:mt-20">
+ <h2
+ id="recent-posts-heading"
+ className="font-news text-2xl font-semibold tracking-tight sm:text-3xl"
+ >
+ Recent posts
+ </h2>
+ <div className="thin-scrollbar scrollbar-none -mx-4 mt-3 overflow-x-auto px-4 sm:-mx-6 sm:mt-6 sm:px-6">
+ <nav
+ aria-label="Filter recent posts"
+ className="flex w-max min-w-full flex-nowrap gap-6"
+ >
+ <TopicButton
+ id={allTopicsId}
+ label="All"
+ selected={selectedTopicId === allTopicsId}
+ onSelect={selectTopic}
+ />
+ {topics.map((topic) => (
+ <TopicButton
+ key={topic.id}
+ id={topic.id}
+ label={topic.label}
+ selected={selectedTopicId === topic.id}
+ onSelect={selectTopic}
+ />
+ ))}
+ </nav>
+ </div>
+
+ {visiblePosts.length > 0 ? (
+ <div className="mt-6 grid gap-x-8 gap-y-10 sm:mt-8 sm:grid-cols-3 sm:gap-y-12">
+ {visiblePosts.map((post) => (
+ <article key={post.slug}>
+ <Link
+ href={`/blog/${post.slug}`}
+ className="group block rounded-lg focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-4 focus-visible:ring-offset-background"
+ >
+ <span className="relative block aspect-video overflow-hidden rounded-lg bg-muted">
+ <Image
+ src={post.imageUrl}
+ alt=""
+ fill
+ sizes="(max-width: 639px) calc(100vw - 2rem), 20.5rem"
+ className="object-cover transition-transform duration-200 group-hover:scale-[1.015] motion-reduce:transform-none"
+ />
+ </span>
+ <h3 className="mt-4 font-news text-lg font-semibold leading-snug tracking-tight">
+ {post.title}
+ </h3>
+ <span className="mt-1 flex flex-wrap items-center gap-x-2 gap-y-1 font-sans text-sm text-muted-foreground">
+ <span>{post.topicLabel}</span>
+ <span aria-hidden="true">·</span>
+ <time dateTime={post.date}>{formatBlogPostDate(post.date)}</time>
+ </span>
+ </Link>
+ </article>
+ ))}
+ </div>
+ ) : (
+ <p className="mt-8 rounded-lg border border-border px-4 py-8 font-sans text-sm text-muted-foreground">
+ No recent stories in this topic yet.
+ </p>
+ )}
+ </section>
+ );
+}
+
+function TopicButton({
+ id,
+ label,
+ selected,
+ onSelect,
+}: {
+ id: string;
+ label: string;
+ selected: boolean;
+ onSelect: (id: string) => void;
+}) {
+ return (
+ <button
+ id={id === allTopicsId ? undefined : id}
+ type="button"
+ aria-pressed={selected}
+ onClick={() => onSelect(id)}
+ className={`min-h-11 shrink-0 whitespace-nowrap py-2 font-sans text-sm transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background ${
+ selected
+ ? "font-semibold text-foreground underline decoration-2 underline-offset-4"
+ : "font-medium text-muted-foreground hover:text-foreground"
+ }`}
+ >
+ {label}
+ </button>
+ );
+}
diff --git a/src/web/blog/src/app/blog/[slug]/article-meta.test.ts b/src/web/blog/src/app/blog/[slug]/article-meta.test.ts
new file mode 100644
index 000000000..c62c965d7
--- /dev/null
+++ b/src/web/blog/src/app/blog/[slug]/article-meta.test.ts
@@ -0,0 +1,92 @@
+import { createElement } from "react";
+import TestRenderer, { act, type ReactTestRenderer } from "react-test-renderer";
+import { describe, expect, it, vi } from "vitest";
+import type { BlogPost } from "@blog/lib/blog/posts";
+import { BlogPostByline, buildBlogPostMetadata } from "./article-meta";
+
+vi.mock("./og-image", () => ({
+ getBlogOgImage: () => "/blog/example/hero.webp",
+}));
+
+const post: BlogPost = {
+ slug: "example",
+ title: "Visible article title",
+ seoTitle: "Search article title",
+ date: "2026-08-20",
+ dateModified: "2026-09-01",
+ author: "Alook",
+ excerpt: "Article excerpt",
+ readingTime: "5 min read",
+};
+
+describe("article metadata", () => {
+ it("preserves templated article titles and adds descriptive OG image alt", () => {
+ const metadata = buildBlogPostMetadata(post);
+
+ expect(metadata.title).toBe("Search article title");
+ expect(metadata.openGraph).toMatchObject({
+ type: "article",
+ publishedTime: "2026-08-20",
+ modifiedTime: "2026-09-01",
+ images: [
+ {
+ url: "/blog/example/hero.webp",
+ width: 1200,
+ height: 630,
+ alt: "Search article title",
+ },
+ ],
+ });
+ });
+
+ it("omits revision metadata and copy when the post has not been revised", () => {
+ const unmodifiedPost = { ...post };
+ delete unmodifiedPost.dateModified;
+
+ const metadata = buildBlogPostMetadata(unmodifiedPost);
+ expect(metadata.openGraph).not.toHaveProperty("modifiedTime");
+
+ let renderer: ReactTestRenderer;
+ act(() => {
+ renderer = TestRenderer.create(
+ createElement(BlogPostByline, { post: unmodifiedPost }),
+ );
+ });
+
+ const times = renderer!.root.findAllByType("time");
+ expect(times).toHaveLength(1);
+ expect(times[0]?.props.dateTime).toBe("2026-08-20");
+ expect(times[0]?.children.join("")).toBe("August 20, 2026");
+ });
+
+ it.each(["America/Los_Angeles", "Pacific/Honolulu"])(
+ "renders semantic dates on the authored calendar day in %s",
+ (timeZone) => {
+ const previousTimeZone = process.env.TZ;
+ process.env.TZ = timeZone;
+ let renderer: ReactTestRenderer;
+
+ try {
+ act(() => {
+ renderer = TestRenderer.create(createElement(BlogPostByline, { post }));
+ });
+
+ const times = renderer!.root.findAllByType("time");
+ expect(times.map((time) => time.props.dateTime)).toEqual([
+ "2026-08-20",
+ "2026-09-01",
+ ]);
+ expect(times.map((time) => time.children.join(""))).toEqual([
+ "August 20, 2026",
+ "Updated September 1, 2026",
+ ]);
+ } finally {
+ if (previousTimeZone === undefined) {
+ delete process.env.TZ;
+ } else {
+ process.env.TZ = previousTimeZone;
+ }
+ }
+ },
+ );
+});
diff --git a/src/web/blog/src/app/blog/[slug]/article-meta.tsx b/src/web/blog/src/app/blog/[slug]/article-meta.tsx
new file mode 100644
index 000000000..6ae5056d9
--- /dev/null
+++ b/src/web/blog/src/app/blog/[slug]/article-meta.tsx
@@ -0,0 +1,71 @@
+import type { Metadata } from "next";
+import type { BlogPost } from "@blog/lib/blog/posts";
+import { getBlogSearchTitle } from "@blog/lib/blog/metadata";
+import { getBlogOgImage } from "./og-image";
+
+export function buildBlogPostMetadata(post: BlogPost): Metadata {
+ const ogImage = getBlogOgImage(post);
+ const searchTitle = getBlogSearchTitle(post);
+
+ return {
+ title: searchTitle,
+ description: post.excerpt,
+ alternates: { canonical: `https://alook.ai/blog/${post.slug}` },
+ openGraph: {
+ title: searchTitle,
+ description: post.excerpt,
+ url: `https://alook.ai/blog/${post.slug}`,
+ type: "article",
+ publishedTime: post.date,
+ ...(post.dateModified ? { modifiedTime: post.dateModified } : {}),
+ authors: [post.author],
+ images: [
+ {
+ url: ogImage,
+ width: 1200,
+ height: 630,
+ alt: searchTitle,
+ },
+ ],
+ },
+ twitter: {
+ card: "summary_large_image",
+ title: searchTitle,
+ description: post.excerpt,
+ images: [ogImage],
+ },
+ };
+}
+
+export function BlogPostByline({
+ post,
+}: {
+ post: Pick<BlogPost, "author" | "date" | "dateModified" | "readingTime">;
+}) {
+ return (
+ <div className="mt-6 flex flex-wrap items-center gap-x-3 gap-y-1 text-sm text-muted-foreground">
+ <span className="font-medium text-foreground/70">{post.author}</span>
+ <span className="text-muted-foreground/40">/</span>
+ <time dateTime={post.date}>{formatArticleDate(post.date)}</time>
+ {post.dateModified && post.dateModified !== post.date ? (
+ <>
+ <span className="text-muted-foreground/40">/</span>
+ <time dateTime={post.dateModified}>
+ Updated {formatArticleDate(post.dateModified)}
+ </time>
+ </>
+ ) : null}
+ <span className="text-muted-foreground/40">/</span>
+ <span>{post.readingTime}</span>
+ </div>
+ );
+}
+
+function formatArticleDate(date: string): string {
+ return new Date(date).toLocaleDateString("en-US", {
+ year: "numeric",
+ month: "long",
+ day: "numeric",
+ timeZone: "UTC",
+ });
+}
diff --git a/src/web/blog/src/app/blog/[slug]/page.tsx b/src/web/blog/src/app/blog/[slug]/page.tsx
index baa13ad2a..2fe7c9c59 100644
--- a/src/web/blog/src/app/blog/[slug]/page.tsx
+++ b/src/web/blog/src/app/blog/[slug]/page.tsx
@@ -4,13 +4,13 @@ import Link from "next/link";
import { ArrowLeft, ArrowRight } from "lucide-react";
import { getAllPosts, getPostBySlug } from "@blog/lib/blog/posts";
import { buildBlogPostingJsonLd } from "@blog/lib/blog/json-ld";
-import { getBlogSearchTitle } from "@blog/lib/blog/metadata";
import {
getBlogTopicBySlug,
getBlogTopicEntryBySlug,
getNextTopicBridge,
getRelatedPosts,
} from "@blog/lib/blog/topics";
+import { BlogPostByline, buildBlogPostMetadata } from "./article-meta";
import { getBlogOgImage } from "./og-image";
// The ASSETS-only Worker intentionally has no incremental-cache binding, so a
@@ -31,39 +31,7 @@ export async function generateMetadata({
const post = await getPostBySlug(slug);
if (!post) return {};
- // Preserve existing hero images. Only posts without one use the bounded,
- // route-owned fallback; unlike the retired query route, the slug is resolved
- // against canonical post metadata on the server.
- const ogImage = getBlogOgImage(post);
- const searchTitle = getBlogSearchTitle(post);
-
- return {
- title: searchTitle,
- description: post.excerpt,
- alternates: { canonical: `https://alook.ai/blog/${post.slug}` },
- openGraph: {
- title: searchTitle,
- description: post.excerpt,
- url: `https://alook.ai/blog/${post.slug}`,
- type: "article",
- publishedTime: post.date,
- ...(post.dateModified ? { modifiedTime: post.dateModified } : {}),
- authors: [post.author],
- images: [
- {
- url: ogImage,
- width: 1200,
- height: 630,
- },
- ],
- },
- twitter: {
- card: "summary_large_image",
- title: searchTitle,
- description: post.excerpt,
- images: [ogImage],
- },
- };
+ return buildBlogPostMetadata(post);
}
export default async function BlogPostPage({
@@ -84,7 +52,10 @@ export default async function BlogPostPage({
`@blog/content/${slug}.mdx`
);
- const blogPostingJsonLd = buildBlogPostingJsonLd(post);
+ const blogPostingJsonLd = buildBlogPostingJsonLd(
+ post,
+ getBlogOgImage(post),
+ );
return (
<>
@@ -121,32 +92,7 @@ export default async function BlogPostPage({
<h1 className="font-news text-4xl sm:text-5xl font-semibold tracking-tight leading-[1.12]">
{post.title}
</h1>
- <div className="mt-6 flex flex-wrap items-center gap-x-3 gap-y-1 text-sm text-muted-foreground">
- <span className="font-medium text-foreground/70">{post.author}</span>
- <span className="text-muted-foreground/40">/</span>
- <span>
- {new Date(post.date).toLocaleDateString("en-US", {
- year: "numeric",
- month: "long",
- day: "numeric",
- })}
- </span>
- {post.dateModified && post.dateModified !== post.date ? (
- <>
- <span className="text-muted-foreground/40">/</span>
- <span>
- Updated{" "}
- {new Date(post.dateModified).toLocaleDateString("en-US", {
- year: "numeric",
- month: "long",
- day: "numeric",
- })}
- </span>
- </>
- ) : null}
- <span className="text-muted-foreground/40">/</span>
- <span>{post.readingTime}</span>
- </div>
+ <BlogPostByline post={post} />
</header>
<div className="blog-content blog-content-editorial font-sans text-lg leading-[1.7] text-foreground max-w-[65ch] [&_h2]:font-sans [&_h2]:text-[1.625rem] [&_h2]:font-semibold [&_h2]:tracking-tight [&_h2]:mt-16 [&_h2]:mb-6 [&_p]:mb-8 [&_blockquote]:border-l-[3px] [&_blockquote]:border-foreground/20 [&_blockquote]:pl-6 [&_blockquote]:italic [&_blockquote]:text-foreground/70 [&_blockquote]:my-10 [&_blockquote]:text-xl [&_blockquote]:leading-relaxed [&_code]:font-mono [&_code]:bg-muted [&_code]:px-2 [&_code]:py-1 [&_code]:rounded [&_code]:text-[0.875em] [&_pre]:bg-muted [&_pre]:rounded-lg [&_pre]:px-4 [&_pre]:py-4 [&_pre]:my-10 [&_pre]:overflow-x-auto [&_pre]:text-[0.875rem] [&_pre]:leading-relaxed [&_pre]:max-w-none [&_pre_code]:bg-transparent [&_pre_code]:p-0 [&_img]:rounded-lg [&_img]:my-12 [&_img]:w-full [&_img]:max-w-none [&_ul]:list-disc [&_ul]:pl-6 [&_ul]:mb-8 [&_ul]:-mt-1 [&_li]:mb-3 [&_li]:leading-[1.7] [&_strong]:font-semibold [&_em]:italic [&_a]:underline [&_a]:underline-offset-3 [&_a]:decoration-foreground/30 [&_a]:hover:decoration-foreground/60 [&_a]:transition-colors [&_table]:w-full [&_table]:my-10 [&_table]:border-collapse [&_table]:text-[0.9rem] [&_th]:text-left [&_th]:font-semibold [&_th]:py-3 [&_th]:px-4 [&_th]:border-b-2 [&_th]:border-border [&_td]:py-3 [&_td]:px-4 [&_td]:border-b [&_td]:border-border [&_tr:hover]:bg-muted/50">
diff --git a/src/web/blog/src/lib/blog/json-ld.test.ts b/src/web/blog/src/lib/blog/json-ld.test.ts
index 322e9dee2..d334bfecd 100644
--- a/src/web/blog/src/lib/blog/json-ld.test.ts
+++ b/src/web/blog/src/lib/blog/json-ld.test.ts
@@ -14,24 +14,44 @@ const base: BlogPost = {
};
describe("buildBlogPostingJsonLd", () => {
- it("omits dateModified when not set", () => {
- const jsonLd = buildBlogPostingJsonLd(base);
+ it("uses the article image and canonical URL when a hero exists", () => {
+ const jsonLd = buildBlogPostingJsonLd(
+ base,
+ "/blog/sample/hero.webp",
+ );
expect(jsonLd.datePublished).toBe("2026-06-08");
expect(jsonLd).not.toHaveProperty("dateModified");
expect(jsonLd.image).toBe("https://alook.ai/blog/sample/hero.webp");
+ expect(jsonLd.mainEntityOfPage).toEqual({
+ "@type": "WebPage",
+ "@id": "https://alook.ai/blog/sample",
+ });
+ expect(jsonLd.url).toBe("https://alook.ai/blog/sample");
+ });
+
+ it("uses the absolute route-owned OG fallback when no hero exists", () => {
+ const jsonLd = buildBlogPostingJsonLd(
+ { ...base, image: undefined },
+ "/og/blog/sample",
+ );
+
+ expect(jsonLd.image).toBe("https://alook.ai/og/blog/sample");
});
it("includes dateModified when set", () => {
- const jsonLd = buildBlogPostingJsonLd({
- ...base,
- dateModified: "2026-07-23",
- });
+ const jsonLd = buildBlogPostingJsonLd(
+ {
+ ...base,
+ dateModified: "2026-07-23",
+ },
+ base.image!,
+ );
expect(jsonLd.datePublished).toBe("2026-06-08");
expect(jsonLd.dateModified).toBe("2026-07-23");
});
it("uses the Alook organization as author for Alook Team", () => {
- const jsonLd = buildBlogPostingJsonLd(base);
+ const jsonLd = buildBlogPostingJsonLd(base, base.image!);
expect(jsonLd.author).toEqual({
"@type": "Organization",
@@ -45,10 +65,13 @@ describe("buildBlogPostingJsonLd", () => {
});
it("uses a Person author for a named writer", () => {
- const jsonLd = buildBlogPostingJsonLd({
- ...base,
- author: "Gus",
- });
+ const jsonLd = buildBlogPostingJsonLd(
+ {
+ ...base,
+ author: "Gus",
+ },
+ base.image!,
+ );
expect(jsonLd.author).toEqual({
"@type": "Person",
diff --git a/src/web/blog/src/lib/blog/json-ld.ts b/src/web/blog/src/lib/blog/json-ld.ts
index b7a6dc66d..ab25594a1 100644
--- a/src/web/blog/src/lib/blog/json-ld.ts
+++ b/src/web/blog/src/lib/blog/json-ld.ts
@@ -1,7 +1,11 @@
import type { BlogPost } from "./types";
import { ALOOK_ORGANIZATION } from "@/lib/seo/entities";
-export function buildBlogPostingJsonLd(post: BlogPost) {
+const siteUrl = "https://alook.ai";
+
+export function buildBlogPostingJsonLd(post: BlogPost, resolvedOgImage: string) {
+ const canonicalUrl = `${siteUrl}/blog/${post.slug}`;
+
return {
"@context": "https://schema.org",
"@type": "BlogPosting",
@@ -21,7 +25,11 @@ export function buildBlogPostingJsonLd(post: BlogPost) {
name: post.author,
},
publisher: { ...ALOOK_ORGANIZATION },
- url: `https://alook.ai/blog/${post.slug}`,
- ...(post.image ? { image: `https://alook.ai${post.image}` } : {}),
+ mainEntityOfPage: {
+ "@type": "WebPage",
+ "@id": canonicalUrl,
+ },
+ url: canonicalUrl,
+ image: new URL(resolvedOgImage, siteUrl).toString(),
};
}