From 96218b0eed591240ffacdf274b0851bc6f35e68e Mon Sep 17 00:00:00 2001
From: Oleksandr Zhuravlov <rejifald@gmail.com>
Date: Wed, 8 Jul 2026 21:43:53 +0300
Subject: [PATCH] fix(docs): strengthen crawl + indexing signals for the blog
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Google Search Console reported ~107 blog/docs URLs as "Discovered —
currently not indexed". There is no technical blocker (pages are statically
generated; robots/canonical/sitemap are clean; no noindex in HTML or headers)
— it's the young-domain crawl-budget pattern. These changes maximize the
signals that help Google prioritize crawling the URLs it has already
discovered.

- sitemap: emit each blog URL's real frontmatter date as <lastmod> instead of
  the build timestamp. Stamping every URL with the build time told Google that
  all ~107 pages changed on every deploy, so it treated lastmod as noise and
  ignored it — discarding the signal it uses to schedule crawls. Docs/home stay
  on the build time (no per-page date); the blog index uses the newest post.

- blog posts: add per-post BlogPosting JSON-LD (headline, datePublished,
  author, image, mainEntityOfPage) so crawlers can model each post as an
  Article instead of guessing — a content signal that aids prioritization and
  unlocks Article rich results.

- blog posts: add a per-post OG image route (/og/blog/[slug]) mirroring the
  docs one, wired into openGraph/twitter/JSON-LD. Posts previously declared a
  summary_large_image card with no image, so social cards rendered blank.

- home page: add a "From the blog" section linking the 4 latest posts. The
  home page is the most-crawled URL, so direct links from it are the strongest
  crawl-priority signal we can give a young blog's posts.

Verified: /sitemap.xml serves distinct per-post <lastmod> dates; docs
typecheck passes (the new typed OG route resolves); the home page renders the
section with 4 crawlable /blog links.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 apps/docs/app/(home)/blog/[slug]/page.tsx     | 147 +++++++++++-------
 .../app/(home)/components/from-the-blog.tsx   |  63 ++++++++
 apps/docs/app/(home)/page.tsx                 |   2 +
 apps/docs/app/og/blog/[slug]/route.tsx        |  44 ++++++
 apps/docs/app/sitemap.ts                      |  32 +++-
 5 files changed, 225 insertions(+), 63 deletions(-)
 create mode 100644 apps/docs/app/(home)/components/from-the-blog.tsx
 create mode 100644 apps/docs/app/og/blog/[slug]/route.tsx

diff --git a/apps/docs/app/(home)/blog/[slug]/page.tsx b/apps/docs/app/(home)/blog/[slug]/page.tsx
index 2bbec26f..3e5564c5 100644
--- a/apps/docs/app/(home)/blog/[slug]/page.tsx
+++ b/apps/docs/app/(home)/blog/[slug]/page.tsx
@@ -6,6 +6,7 @@ import {
     getRelatedPosts,
     postSlug,
 } from '@/lib/blog';
+import { jsonLdHtml } from '@/lib/json-ld';
 import { appName, siteUrl } from '@/lib/shared';
 
 import { DocsBody } from 'fumadocs-ui/layouts/docs/page';
@@ -21,63 +22,96 @@ export default async function BlogPostPage(props: PageProps<'/blog/[slug]'>) {
     const MDX = post.data.body;
     const related = getRelatedPosts(post);
 
-    return (
-        <main className="container mx-auto max-w-3xl px-4 py-16">
-            <Link
-                href="/blog"
-                className="text-fd-muted-foreground hover:text-fd-foreground mb-8 inline-block text-sm transition-colors"
-            >
-                ← Back to blog
-            </Link>
-            <article>
-                <header className="mb-10">
-                    <h1 className="mb-3 text-4xl font-semibold tracking-tight">
-                        {post.data.title}
-                    </h1>
-                    <p className="text-fd-muted-foreground text-sm">
-                        <span>{post.data.author}</span>
-                        <span aria-hidden> · </span>
-                        <time dateTime={post.data.date}>
-                            {formatPostDate(post.data.date)}
-                        </time>
-                    </p>
-                </header>
-                <Prerequisites hrefs={post.data.prerequisites} />
-                <DocsBody>
-                    <MDX components={getMDXComponents()} />
-                </DocsBody>
-            </article>
+    // Per-post structured data. The root layout emits site-wide WebSite +
+    // SoftwareApplication nodes; this classifies each post as an Article so a
+    // crawler can model author, publish date, and headline instead of guessing —
+    // the content-quality signal that helps Google prioritize a young blog's URLs
+    // for indexing (and unlocks Article rich results). `image`/`url` must resolve,
+    // so they mirror the OG route and canonical exactly.
+    const canonical = `${siteUrl}/blog/${slug}`;
+    const jsonLd = {
+        '@context': 'https://schema.org',
+        '@type': 'BlogPosting',
+        headline: post.data.title,
+        ...(post.data.description
+            ? { description: post.data.description }
+            : {}),
+        datePublished: post.data.date,
+        dateModified: post.data.date,
+        author: { '@type': 'Person', name: post.data.author },
+        publisher: { '@type': 'Organization', name: appName, url: siteUrl },
+        image: `${siteUrl}/og/blog/${slug}`,
+        mainEntityOfPage: { '@type': 'WebPage', '@id': canonical },
+        url: canonical,
+        ...(post.data.tags?.length
+            ? { keywords: post.data.tags.join(', ') }
+            : {}),
+        inLanguage: 'en-US',
+    };
 
-            {related.length > 0 ? (
-                <aside
-                    aria-label="Related posts"
-                    className="border-fd-border mt-16 border-t pt-10"
+    return (
+        <>
+            <script
+                type="application/ld+json"
+                dangerouslySetInnerHTML={{ __html: jsonLdHtml(jsonLd) }}
+            />
+            <main className="container mx-auto max-w-3xl px-4 py-16">
+                <Link
+                    href="/blog"
+                    className="text-fd-muted-foreground hover:text-fd-foreground mb-8 inline-block text-sm transition-colors"
                 >
-                    <h2 className="mb-6 text-sm font-semibold tracking-wide uppercase">
-                        Related reading
-                    </h2>
-                    <ul className="flex flex-col gap-6">
-                        {related.map((other) => (
-                            <li key={other.url}>
-                                <Link
-                                    href={`/blog/${postSlug(other)}`}
-                                    className="group block"
-                                >
-                                    <h3 className="group-hover:text-fd-primary text-lg font-medium tracking-tight transition-colors">
-                                        {other.data.title}
-                                    </h3>
-                                    {other.data.description ? (
-                                        <p className="text-fd-muted-foreground mt-1 text-sm">
-                                            {other.data.description}
-                                        </p>
-                                    ) : null}
-                                </Link>
-                            </li>
-                        ))}
-                    </ul>
-                </aside>
-            ) : null}
-        </main>
+                    ← Back to blog
+                </Link>
+                <article>
+                    <header className="mb-10">
+                        <h1 className="mb-3 text-4xl font-semibold tracking-tight">
+                            {post.data.title}
+                        </h1>
+                        <p className="text-fd-muted-foreground text-sm">
+                            <span>{post.data.author}</span>
+                            <span aria-hidden> · </span>
+                            <time dateTime={post.data.date}>
+                                {formatPostDate(post.data.date)}
+                            </time>
+                        </p>
+                    </header>
+                    <Prerequisites hrefs={post.data.prerequisites} />
+                    <DocsBody>
+                        <MDX components={getMDXComponents()} />
+                    </DocsBody>
+                </article>
+
+                {related.length > 0 ? (
+                    <aside
+                        aria-label="Related posts"
+                        className="border-fd-border mt-16 border-t pt-10"
+                    >
+                        <h2 className="mb-6 text-sm font-semibold tracking-wide uppercase">
+                            Related reading
+                        </h2>
+                        <ul className="flex flex-col gap-6">
+                            {related.map((other) => (
+                                <li key={other.url}>
+                                    <Link
+                                        href={`/blog/${postSlug(other)}`}
+                                        className="group block"
+                                    >
+                                        <h3 className="group-hover:text-fd-primary text-lg font-medium tracking-tight transition-colors">
+                                            {other.data.title}
+                                        </h3>
+                                        {other.data.description ? (
+                                            <p className="text-fd-muted-foreground mt-1 text-sm">
+                                                {other.data.description}
+                                            </p>
+                                        ) : null}
+                                    </Link>
+                                </li>
+                            ))}
+                        </ul>
+                    </aside>
+                ) : null}
+            </main>
+        </>
     );
 }
 
@@ -97,6 +131,7 @@ export async function generateMetadata(
     if (!post) notFound();
 
     const canonical = `${siteUrl}/blog/${slug}`;
+    const ogImage = `/og/blog/${slug}`;
 
     return {
         title: post.data.title,
@@ -110,11 +145,13 @@ export async function generateMetadata(
             description: post.data.description,
             authors: [post.data.author],
             publishedTime: post.data.date,
+            images: ogImage,
         },
         twitter: {
             card: 'summary_large_image',
             title: post.data.title,
             description: post.data.description,
+            images: ogImage,
         },
     };
 }
diff --git a/apps/docs/app/(home)/components/from-the-blog.tsx b/apps/docs/app/(home)/components/from-the-blog.tsx
new file mode 100644
index 00000000..50124fed
--- /dev/null
+++ b/apps/docs/app/(home)/components/from-the-blog.tsx
@@ -0,0 +1,63 @@
+import { Section, SectionHeading } from './primitives';
+
+import { formatPostDate, getSortedPosts, postSlug } from '@/lib/blog';
+
+import { ArrowRight } from 'lucide-react';
+import Link from 'next/link';
+
+// A "latest posts" band on the home page. Beyond being useful, this is
+// deliberate internal linking: the home page is the most-crawled URL on the
+// site, so a direct link from here to each post is the strongest crawl-priority
+// signal we can give a young blog sitting in "Discovered — currently not
+// indexed". Server-rendered, so every card is a static <a> in the HTML.
+export function FromTheBlog() {
+    const posts = getSortedPosts().slice(0, 4);
+    if (posts.length === 0) return null;
+
+    return (
+        <Section id="from-the-blog" className="border-b border-fd-border">
+            <SectionHeading
+                eyebrow="From the blog"
+                title="Notes on stitching APIs"
+                lead="Field notes on API stitching, agent-native integrations, and cutting AI cost."
+                align="center"
+            />
+
+            <ul className="mx-auto mt-12 grid max-w-4xl gap-5 sm:grid-cols-2">
+                {posts.map((post) => (
+                    <li key={post.url}>
+                        <Link
+                            href={`/blog/${postSlug(post)}`}
+                            className="group block h-full rounded-2xl border border-fd-border bg-fd-card p-7 transition-colors hover:bg-fd-accent"
+                        >
+                            <time
+                                dateTime={post.data.date}
+                                className="text-xs font-medium uppercase tracking-[0.14em] text-fd-muted-foreground"
+                            >
+                                {formatPostDate(post.data.date)}
+                            </time>
+                            <h3 className="mt-3 text-xl font-semibold tracking-tight text-fd-foreground group-hover:text-stitch">
+                                {post.data.title}
+                            </h3>
+                            {post.data.description ? (
+                                <p className="mt-3 text-sm leading-relaxed text-fd-muted-foreground">
+                                    {post.data.description}
+                                </p>
+                            ) : null}
+                        </Link>
+                    </li>
+                ))}
+            </ul>
+
+            <div className="mt-10 flex justify-center">
+                <Link
+                    href="/blog"
+                    className="group inline-flex items-center gap-2 text-sm font-semibold text-stitch hover:text-stitch-strong"
+                >
+                    Read the blog
+                    <ArrowRight className="size-4 transition-transform group-hover:translate-x-0.5" />
+                </Link>
+            </div>
+        </Section>
+    );
+}
diff --git a/apps/docs/app/(home)/page.tsx b/apps/docs/app/(home)/page.tsx
index 3068af55..d0e9db1e 100644
--- a/apps/docs/app/(home)/page.tsx
+++ b/apps/docs/app/(home)/page.tsx
@@ -3,6 +3,7 @@ import { Cta, Footer } from './components/cta';
 import { Demo } from './components/demo';
 import { Differentiator } from './components/differentiator';
 import { Features } from './components/features';
+import { FromTheBlog } from './components/from-the-blog';
 import { Hero } from './components/hero';
 import { Metrics } from './components/metrics';
 import { NotThis } from './components/not-this';
@@ -51,6 +52,7 @@ export default function HomePage() {
             <Features />
             <NotThis />
             <Differentiator />
+            <FromTheBlog />
             <Cta />
             <Footer />
         </main>
diff --git a/apps/docs/app/og/blog/[slug]/route.tsx b/apps/docs/app/og/blog/[slug]/route.tsx
new file mode 100644
index 00000000..643249ff
--- /dev/null
+++ b/apps/docs/app/og/blog/[slug]/route.tsx
@@ -0,0 +1,44 @@
+import { blogSource } from '@/lib/blog';
+import { appName } from '@/lib/shared';
+
+import { generate as DefaultImage } from 'fumadocs-ui/og';
+import { notFound } from 'next/navigation';
+import { ImageResponse } from 'next/og';
+
+export const revalidate = false;
+
+// Per-post Open Graph image, mirroring the docs OG route (`/og/docs/...`). The
+// blog post metadata sets `openGraph.type: 'article'` + a `summary_large_image`
+// Twitter card but shipped no image, so social cards rendered blank; this gives
+// every post a real 1200×630 card showing its own title. The BlogPosting JSON-LD
+// points its `image` here too, so the URL must resolve.
+export async function GET(
+    _req: Request,
+    { params }: RouteContext<'/og/blog/[slug]'>,
+) {
+    const { slug } = await params;
+    const post = blogSource.getPage([slug]);
+    if (!post) notFound();
+
+    return new ImageResponse(
+        (
+            <DefaultImage
+                title={post.data.title}
+                description={post.data.description}
+                site={appName}
+            />
+        ),
+        {
+            width: 1200,
+            height: 630,
+        },
+    );
+}
+
+export function generateStaticParams() {
+    return blogSource.generateParams().map((params) => ({
+        // Flatten fumadocs' `{ slug: string[] }` to this route's `{ slug: string }`,
+        // exactly as the blog post page does.
+        slug: params.slug?.[0] ?? '',
+    }));
+}
diff --git a/apps/docs/app/sitemap.ts b/apps/docs/app/sitemap.ts
index 4e3fa736..6a14165d 100644
--- a/apps/docs/app/sitemap.ts
+++ b/apps/docs/app/sitemap.ts
@@ -9,31 +9,47 @@ export const revalidate = false;
 const absolute = (path: string) => new URL(path, siteUrl).toString();
 
 export default function sitemap(): MetadataRoute.Sitemap {
-    // Static export (`revalidate = false`), so this is the build timestamp —
-    // a truthful "last generated" signal for crawlers.
-    const lastModified = new Date();
+    const posts = getSortedPosts();
+
+    // Docs pages carry no per-page date, so the build timestamp is the most
+    // truthful `lastmod` we have for them (and for the home page). Blog URLs get
+    // their real content dates below — see the note there.
+    const buildTime = new Date();
+
+    // The newest post's date is when the blog index last meaningfully changed.
+    const blogIndexModified = posts[0]
+        ? new Date(posts[0].data.date)
+        : buildTime;
+
     return [
         {
             url: absolute('/'),
-            lastModified,
+            lastModified: buildTime,
             changeFrequency: 'monthly',
             priority: 1,
         },
         ...source.getPages().map((page) => ({
             url: absolute(page.url),
-            lastModified,
+            lastModified: buildTime,
             changeFrequency: 'weekly' as const,
             priority: 0.8,
         })),
         {
             url: absolute(blogRoute),
-            lastModified,
+            lastModified: blogIndexModified,
             changeFrequency: 'weekly' as const,
             priority: 0.7,
         },
-        ...getSortedPosts().map((post) => ({
+        // A post's own publication date is a stable, per-URL `lastmod` that only
+        // moves when the content does. This is deliberate: stamping every URL
+        // with the build time (as this route used to) tells Google all ~100
+        // pages changed on every deploy, which it treats as noise and ignores —
+        // discarding the very signal it uses to schedule crawls. Truthful,
+        // stable dates are what a young domain stuck in "Discovered — currently
+        // not indexed" needs.
+        ...posts.map((post) => ({
             url: absolute(`${blogRoute}/${postSlug(post)}`),
-            lastModified,
+            lastModified: new Date(post.data.date),
             changeFrequency: 'monthly' as const,
             priority: 0.6,
         })),