feat(blog): site health + AI-citation fixes (A1/AI1 — harden Article schema)

components/cover-image.tsx

@@ -1,6 +1,7 @@
 import Image from "next/image";
 import Link from "next/link";
 import { Post } from "../types/post";
+import { DEFAULT_ARTICLE_IMAGE_URL } from "../lib/structured-data";
 
 interface Props extends Partial<Pick<Post, "title" | "slug">> {
   coverImage: Post["featuredImage"];
@@ -22,13 +23,16 @@ export default function CoverImage({
   sizes = "(max-width: 768px) 100vw, (max-width: 1200px) 780px, 780px",
 }: Props) {
   const basePath = isCommunity ? "/community/" : "/technology/";
+  // Never let the link's accessible name or the image alt end up empty (some
+  // cards render without a title) — an empty aria-label is an anchor-less link.
+  const safeTitle = title || "Keploy blog article";
 
   const image = (
     <Image
       width={2000}
       height={1000}
-      alt={`Cover Image for ${title}`}
-      src={coverImage?.node.sourceUrl}
+      alt={`Cover Image for ${safeTitle}`}
+      src={coverImage?.node?.sourceUrl || DEFAULT_ARTICLE_IMAGE_URL}
       className={`w-full h-auto object-cover${imgClassName ? ` ${imgClassName}` : ""}${slug ? " transition-transform duration-300 hover:scale-[1.01]" : ""}`}
       priority={priority}
       loading={priority ? "eager" : "lazy"}
@@ -39,7 +43,7 @@ export default function CoverImage({
   return (
     <div className="w-full overflow-hidden">
       {slug ? (
-        <Link href={`${basePath}${slug}`} aria-label={title}>
+        <Link href={`${basePath}${slug}`} aria-label={safeTitle}>
           {image}
         </Link>
       ) : (

lib/structured-data.ts

@@ -1,10 +1,25 @@
 import { sanitizeAuthorSlug } from "../utils/sanitizeAuthorSlug";
+import { decodeEntities } from "../utils/seo";
 
 export const SITE_URL = "https://keploy.io/blog";
 export const MAIN_SITE_URL = "https://keploy.io";
 export const ORG_NAME = "Keploy";
 export const BLOG_NAME = "Keploy Blog";
 export const ORG_LOGO_URL = `${SITE_URL}/favicon/android-chrome-512x512.png`;
+// Stable @id for the Keploy Organization entity. Every place that emits an
+// Organization node (global node, per-post publisher, author worksFor) points
+// at this same @id so AI/search engines resolve ONE Keploy entity instead of
+// treating each inline copy as a separate organization (entity fragmentation).
+export const ORG_ID = `${MAIN_SITE_URL}/#organization`;
+// Default article image when a post's WordPress featuredImage is null (common on
+// older/migrated posts). Mirrors HOME_OG_IMAGE_URL in lib/constants.ts so the
+// schema image matches the og:image the page actually renders.
+export const DEFAULT_ARTICLE_IMAGE_URL =
+  "https://wp.keploy.io/wp-content/uploads/2023/11/thumbnil-.png";
+// Author fallback when a post has no usable ppmaAuthorName. A named team
+// Person with its own profile URL is a valid author node; the previous
+// fallback ("Keploy") produced a URL-less Person, a weaker E-E-A-T signal.
+export const AUTHOR_FALLBACK_NAME = "Keploy Team";
 export const SOCIAL_LINKS = [
   "https://twitter.com/Keployio",
   "https://www.linkedin.com/company/keploy/",
@@ -81,6 +96,7 @@ type BlogPostingInput = {
 export const getOrganizationSchema = () => ({
   "@context": "https://schema.org",
   "@type": "Organization",
+  "@id": ORG_ID,
   name: ORG_NAME,
   url: MAIN_SITE_URL,
   logo: ORG_LOGO_URL,
@@ -128,6 +144,29 @@ export const getWebSiteSchema = (searchTarget = `${SITE_URL}/search?q={search_te
   },
 });
 
+/**
+ * Reusable ImageObject node. Google/AI engines prefer a typed ImageObject over
+ * a bare URL string (it can carry caption + dimensions), and it's the shape the
+ * Article `image` field and listing/cover images should share.
+ */
+export const getImageObjectSchema = ({
+  url,
+  caption,
+  width,
+  height,
+}: {
+  url: string;
+  caption?: string;
+  width?: number;
+  height?: number;
+}) => ({
+  "@type": "ImageObject",
+  url,
+  ...(caption ? { caption } : {}),
+  ...(typeof width === "number" ? { width } : {}),
+  ...(typeof height === "number" ? { height } : {}),
+});
+
 export const getBreadcrumbListSchema = (items: BreadcrumbItem[]) => ({
   "@context": "https://schema.org",
   "@type": "BreadcrumbList",
@@ -139,6 +178,69 @@ export const getBreadcrumbListSchema = (items: BreadcrumbItem[]) => ({
   })),
 });
 
+// Coerce a possibly-null/malformed WordPress date into a valid ISO 8601 string,
+// or null if unparseable. Stops empty / "Invalid Date" values from reaching the
+// schema, which is a structured-data validation error.
+const toISODate = (value?: string): string | null => {
+  if (!value) return null;
+  const d = new Date(value);
+  return isNaN(d.getTime()) ? null : d.toISOString();
+};
+
+type ListEntry = { url: string; name: string };
+
+const toListItems = (items: ListEntry[]) =>
+  items.map((it, index) => ({
+    "@type": "ListItem",
+    position: index + 1,
+    url: it.url,
+    name: it.name,
+  }));
+
+/**
+ * ItemList for a grid/collection of posts. Emitted standalone (has @context) so
+ * AI/search engines can map the ordered set of links on listing pages, which
+ * currently ship zero collection schema.
+ */
+export const getItemListSchema = (items: ListEntry[], listName?: string) => ({
+  "@context": "https://schema.org",
+  "@type": "ItemList",
+  ...(listName ? { name: listName } : {}),
+  itemListElement: toListItems(items),
+});
+
+/**
+ * CollectionPage for an archive/listing route (community, technology, tag,
+ * authors). Wraps the post/author grid as an ItemList mainEntity so the whole
+ * archive is a modeled collection rather than an unlabeled wall of cards.
+ */
+export const getCollectionPageSchema = ({
+  name,
+  url,
+  description,
+  items,
+}: {
+  name: string;
+  url: string;
+  description?: string;
+  items: ListEntry[];
+}) => ({
+  "@context": "https://schema.org",
+  "@type": "CollectionPage",
+  name,
+  url,
+  ...(description ? { description } : {}),
+  isPartOf: {
+    "@type": "Blog",
+    name: BLOG_NAME,
+    url: SITE_URL,
+  },
+  mainEntity: {
+    "@type": "ItemList",
+    itemListElement: toListItems(items),
+  },
+});
+
 export const getBlogPostingSchema = ({
   title,
   url,
@@ -156,9 +258,8 @@ export const getBlogPostingSchema = ({
   reviewerImage,
   reviewerDescription,
 }: BlogPostingInput) => {
-  const resolvedAuthorName = Array.isArray(authorName)
-    ? (authorName[0] || ORG_NAME)
-    : (authorName || ORG_NAME);
+  const resolvedAuthorName =
+    (Array.isArray(authorName) ? authorName[0] : authorName) || AUTHOR_FALLBACK_NAME;
   const authorSlug = sanitizeAuthorSlug(resolvedAuthorName);
 
   // GEO-13: blog/technology posts render as TechArticle
@@ -177,6 +278,12 @@ export const getBlogPostingSchema = ({
     authorNode.image = authorImage;
   }
 
+  // Never emit an empty/invalid datePublished. Prefer the post's own date,
+  // then its modified date, and only as a last resort the current build time.
+  const resolvedPublished =
+    toISODate(datePublished) || toISODate(dateModified) || new Date().toISOString();
+  const resolvedModified = toISODate(dateModified) || resolvedPublished;
+
   const schema: Record<string, unknown> = {
     "@context": "https://schema.org",
     "@type": schemaType,
@@ -185,11 +292,12 @@ export const getBlogPostingSchema = ({
       "@type": "WebPage",
       "@id": url,
     },
-    datePublished,
-    dateModified: dateModified || datePublished,
+    datePublished: resolvedPublished,
+    dateModified: resolvedModified,
     author: authorNode,
     publisher: {
       "@type": "Organization",
+      "@id": ORG_ID,
       name: ORG_NAME,
       logo: {
         "@type": "ImageObject",
@@ -232,13 +340,24 @@ export const getBlogPostingSchema = ({
     schema.articleSection = articleSection;
   }
 
+  // Sanitize the WP excerpt before it enters the schema: strip HTML tags and
+  // decode entities (script-safe) so unescaped markup/entities can't produce a
+  // structured-data parse warning. Only emit when something survives.
   if (description) {
-    schema.description = description;
+    const cleanDescription = decodeEntities(description);
+    if (cleanDescription) {
+      schema.description = cleanDescription;
+    }
   }
 
-  if (imageUrl) {
-    schema.image = [imageUrl];
-  }
+  // Always emit an image so the Article schema never trips the "missing field
+  // image" validation error — WordPress returns a null featuredImage on many
+  // older/migrated posts. Fall back to the site's default OG cover, and emit a
+  // typed ImageObject (not a bare URL) so rich results can use its caption.
+  schema.image = getImageObjectSchema({
+    url: imageUrl || DEFAULT_ARTICLE_IMAGE_URL,
+    caption: title,
+  });
 
   // TechArticle-specific fields — only emit when set AND when we're
   // actually rendering a TechArticle.
@@ -263,6 +382,7 @@ export const getBlogSchema = () => ({
     "Technical blog covering AI-powered API test generation, eBPF-based testing, production behavior replay, dependency virtualization, and developer productivity by Keploy.",
   publisher: {
     "@type": "Organization",
+    "@id": ORG_ID,
     name: ORG_NAME,
     url: MAIN_SITE_URL,
     logo: {

pages/authors/index.tsx

@@ -6,7 +6,8 @@ import Container from "../../components/container";
 import AuthorMapping from "../../components/AuthorMapping";
 import { HOME_OG_IMAGE_URL } from "../../lib/constants";
 import { Post } from "../../types/post";
-import { getBreadcrumbListSchema, SITE_URL } from "../../lib/structured-data";
+import { getBreadcrumbListSchema, getCollectionPageSchema, SITE_URL } from "../../lib/structured-data";
+import { sanitizeAuthorSlug } from "../../utils/sanitizeAuthorSlug";
 import { REVALIDATE_CONTENT } from "../../lib/isr";
 
 export default function Authors({
@@ -34,6 +35,18 @@ export default function Authors({
             { name: "Home", url: SITE_URL },
             { name: "Authors", url: `${SITE_URL}/authors` },
           ]),
+          getCollectionPageSchema({
+            name: "Keploy Blog Authors",
+            url: `${SITE_URL}/authors`,
+            description:
+              "Engineers, developers, and QA experts writing on the Keploy blog about testing, automation, and software quality.",
+            items: authorArray
+              .filter((node) => node.ppmaAuthorName)
+              .map((node) => ({
+                url: `${SITE_URL}/authors/${sanitizeAuthorSlug(node.ppmaAuthorName)}`,
+                name: node.ppmaAuthorName,
+              })),
+          }),
         ]}
         canonicalUrl={`${SITE_URL}/authors`}
       >

pages/community/[slug].tsx

@@ -29,7 +29,7 @@ import {
   getBreadcrumbListSchema,
   SITE_URL,
 } from "../../lib/structured-data";
-import { sanitizeTitle, getSafeDescription } from "../../utils/seo";
+import { sanitizeTitle, getSafeDescription, buildPageTitle } from "../../utils/seo";
 import { getHowToSchema } from "../../lib/howToSchema";
 
 const PostBody = dynamic(() => import("../../components/post-body"));
@@ -219,7 +219,7 @@ export default function Post({ post, posts, reviewAuthorDetails, preview }) {
           <>
             <article>
               <Head>
-                <title>{`${post?.title || "Loading..."} | Keploy Blog`}</title>
+                <title>{buildPageTitle(post?.title)}</title>
                 {/* DM Sans + Baloo 2 are preloaded globally in _document.tsx */}
               </Head>
               <PostHeader

pages/community/index.tsx

@@ -6,7 +6,7 @@ import HeroPost from "../../components/hero-post";
 import Layout from "../../components/layout";
 import { getAllPostsForCommunity } from "../../lib/api";
 import Header from "../../components/header";
-import { getBreadcrumbListSchema, SITE_URL } from "../../lib/structured-data";
+import { getBreadcrumbListSchema, getCollectionPageSchema, SITE_URL } from "../../lib/structured-data";
 import { REVALIDATE_CONTENT } from "../../lib/isr";
 
 export default function Community({ allPosts: { edges, pageInfo }, preview }) {
@@ -18,6 +18,16 @@ export default function Community({ allPosts: { edges, pageInfo }, preview }) {
       { name: "Home", url: SITE_URL },
       { name: "Community", url: `${SITE_URL}/community` },
     ]),
+    getCollectionPageSchema({
+      name: "Keploy Community Blog",
+      url: `${SITE_URL}/community`,
+      description:
+        "Developer stories, open-source contributions, API testing tutorials, and hands-on engineering guides from the Keploy community.",
+      items: edges.map(({ node }) => ({
+        url: `${SITE_URL}/community/${node.slug}`,
+        name: node.title,
+      })),
+    }),
   ];
   function getExcerpt(content) {
     const maxWords = 50;
@@ -46,6 +56,9 @@ export default function Community({ allPosts: { edges, pageInfo }, preview }) {
       </Head>
       <Header />
       <Container>
+        <h1 className="text-3xl md:text-4xl font-bold tracking-tight mt-4 mb-8">
+          Keploy Community Blog
+        </h1>
         {/* <Intro /> */}
         {heroPost && (
           <HeroPost

pages/tag/[slug].tsx

@@ -7,7 +7,7 @@ import Container from "../../components/container";
 import { getAllPostsFromTags, getAllTags } from "../../lib/api";
 import TagsStories from "../../components/TagsStories";
 import { useRouter } from "next/router";
-import { getBreadcrumbListSchema, SITE_URL } from "../../lib/structured-data";
+import { getBreadcrumbListSchema, getCollectionPageSchema, SITE_URL } from "../../lib/structured-data";
 import { REVALIDATE_CONTENT, REVALIDATE_ERROR, REVALIDATE_NOT_FOUND } from "../../lib/isr";
 export default function PostByTags({ postsByTags, preview, tagSlug: tagSlugProp }) {
   const posts = postsByTags?.edges || [];
@@ -26,6 +26,19 @@ export default function PostByTags({ postsByTags, preview, tagSlug: tagSlugProp
           { name: "Tags", url: `${SITE_URL}/tag` },
           { name: `${tagDisplay || "Tag"}`, url: `${SITE_URL}/tag/${tagSlug || ""}` },
         ]),
+        getCollectionPageSchema({
+          name: `${tagDisplay} posts`,
+          url: `${SITE_URL}/tag/${tagSlug || ""}`,
+          description: `Keploy blog posts tagged "${tagDisplay}".`,
+          items: posts.map(({ node }: any) => {
+            const isCommunity =
+              node.categories?.edges?.[0]?.node?.name === "community";
+            return {
+              url: `${SITE_URL}/${isCommunity ? "community" : "technology"}/${node.slug}`,
+              name: node.title,
+            };
+          }),
+        }),
       ]}
       canonicalUrl={tagSlug ? `${SITE_URL}/tag/${tagSlug}` : `${SITE_URL}/tag`}
     >
@@ -34,6 +47,9 @@ export default function PostByTags({ postsByTags, preview, tagSlug: tagSlugProp
       </Head>
       <Header />
       <Container>
+        <h1 className="text-3xl md:text-4xl font-bold tracking-tight mt-4 mb-8">
+          {tagDisplay} posts
+        </h1>
         <TagsStories posts={posts} />
       </Container>
     </Layout>

pages/technology/[slug].tsx

@@ -27,7 +27,7 @@ import {
   getBreadcrumbListSchema,
   SITE_URL,
 } from "../../lib/structured-data";
-import { sanitizeTitle, getSafeDescription } from "../../utils/seo";
+import { sanitizeTitle, getSafeDescription, buildPageTitle } from "../../utils/seo";
 import { getHowToSchema } from "../../lib/howToSchema";
 
 const PostBody = dynamic(() => import("../../components/post-body"));
@@ -197,7 +197,7 @@ export default function Post({ post, posts, reviewAuthorDetails, preview }) {
           <>
             <article>
               <Head>
-                <title>{`${post?.title || "Loading..."} | Keploy Blog`}</title>
+                <title>{buildPageTitle(post?.title)}</title>
                 {/* DM Sans + Baloo 2 are preloaded globally in _document.tsx */}
               </Head>
               <PostHeader