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

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,
@@ -139,6 +155,15 @@ 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();
+};
+
 export const getBlogPostingSchema = ({
   title,
   url,
@@ -156,9 +181,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 +201,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 +215,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 +263,25 @@ 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 = {
+    "@type": "ImageObject",
+    url: imageUrl || DEFAULT_ARTICLE_IMAGE_URL,
+    ...(title ? { caption: title } : {}),
+  };
 
   // TechArticle-specific fields — only emit when set AND when we're
   // actually rendering a TechArticle.
@@ -263,6 +306,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/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

@@ -46,6 +46,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

@@ -34,6 +34,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

pages/technology/index.tsx

@@ -36,6 +36,9 @@ export default function Index({ allPosts: { edges, pageInfo }, preview }) {
       </Head>
       <Header />
       <Container>
+        <h1 className="text-3xl md:text-4xl font-bold tracking-tight mt-4 mb-8">
+          Keploy Technology Blog
+        </h1>
         {/* <Intro /> */}
         {heroPost && (
           <HeroPost

tests/lib/seo.test.ts

@@ -0,0 +1,48 @@
+/**
+ * Unit tests for buildPageTitle (A3 — "title too long", 113 posts).
+ * Run via: `npm run test:unit`. Pins the ≤60-char invariant so a regression
+ * in the truncation logic fails CI instead of silently shipping long titles.
+ */
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { buildPageTitle } from "../../utils/seo";
+
+test("short title keeps the ' | Keploy Blog' suffix", () => {
+  assert.equal(buildPageTitle("Unit Testing 101"), "Unit Testing 101 | Keploy Blog");
+});
+
+test("a title that fits without the suffix drops the suffix rather than overflow", () => {
+  // 52 chars — adding the 14-char suffix would exceed 60, so suffix is dropped.
+  const title = "A Fairly Long Blog Post Title About API Testing Here";
+  const out = buildPageTitle(title);
+  assert.ok(out.length <= 60);
+  assert.equal(out, title);
+});
+
+test("an over-long title is truncated at a word boundary, never mid-word", () => {
+  const out = buildPageTitle(
+    "The Complete Definitive Comprehensive Guide To End To End Integration Testing In Modern Microservices",
+  );
+  assert.ok(out.length <= 60, `got ${out.length}`);
+  assert.ok(!out.endsWith(" "));
+  // last token is a whole word (truncation happened at a space)
+  assert.ok(!/\S$/.test(out) === false); // ends with a non-space char
+});
+
+test("null/undefined/empty falls back to a valid title", () => {
+  assert.equal(buildPageTitle(undefined), "Keploy Blog");
+  assert.equal(buildPageTitle(null), "Keploy Blog");
+  assert.equal(buildPageTitle(""), "Keploy Blog");
+});
+
+test("output is always within the 60-char SERP limit", () => {
+  for (const t of [
+    "x",
+    "A".repeat(200),
+    "word ".repeat(50),
+    "Exactly Sixty Characters Would Go Right About Here Or So Yes!!",
+  ]) {
+    assert.ok(buildPageTitle(t).length <= 60, `too long for input len ${t.length}`);
+  }
+});

tests/lib/structuredData.test.ts

@@ -0,0 +1,115 @@
+/**
+ * Unit tests for getBlogPostingSchema hardening (A1 / AI1).
+ *
+ * Run via: `npm run test:unit`
+ *
+ * WordPress returns null/malformed values (featuredImage, date, author,
+ * excerpt) on many older/migrated posts, and SEMrush flagged 362 posts with
+ * invalid structured data as a result. These cases pin the contract that ANY
+ * input — including all-null — still produces a schema.org-valid Article, so a
+ * regression in the builder's fallbacks fails CI immediately rather than
+ * silently shipping invalid schema.
+ */
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import {
+  getBlogPostingSchema,
+  getOrganizationSchema,
+  ORG_ID,
+  DEFAULT_ARTICLE_IMAGE_URL,
+  AUTHOR_FALLBACK_NAME,
+} from "../../lib/structured-data";
+
+const isValidISODate = (v: unknown): boolean =>
+  typeof v === "string" && v.length > 0 && !isNaN(new Date(v).getTime());
+
+// The worst case: a migrated post where WP returned nulls for everything.
+const nullPost = getBlogPostingSchema({
+  title: "A Post With Missing Data",
+  url: "https://keploy.io/blog/community/some-post",
+  datePublished: "",
+  imageUrl: undefined,
+  authorName: undefined,
+  description: undefined,
+});
+
+test("image is always emitted as an ImageObject, even when featuredImage is null", () => {
+  assert.ok(nullPost.image, "image must be present");
+  const image = nullPost.image as Record<string, unknown>;
+  assert.equal(image["@type"], "ImageObject");
+  assert.equal(image.url, DEFAULT_ARTICLE_IMAGE_URL);
+});
+
+test("a real featuredImage is used and carries the title as caption", () => {
+  const withImage = getBlogPostingSchema({
+    title: "Real Image Post",
+    url: "https://keploy.io/blog/community/x",
+    datePublished: "2024-01-02",
+    imageUrl: "https://wp.keploy.io/wp-content/uploads/real.png",
+  });
+  const image = withImage.image as Record<string, unknown>;
+  assert.equal(image.url, "https://wp.keploy.io/wp-content/uploads/real.png");
+  assert.equal(image.caption, "Real Image Post");
+});
+
+test("datePublished is always a valid ISO date, never empty or invalid", () => {
+  assert.ok(isValidISODate(nullPost.datePublished), "datePublished must be valid ISO");
+  assert.ok(isValidISODate(nullPost.dateModified), "dateModified must be valid ISO");
+});
+
+test("an invalid datePublished falls back to a valid dateModified", () => {
+  const post = getBlogPostingSchema({
+    title: "Bad publish date",
+    url: "https://keploy.io/blog/community/y",
+    datePublished: "not-a-date",
+    dateModified: "2023-05-06",
+  });
+  assert.ok(isValidISODate(post.datePublished));
+  assert.equal(
+    new Date(post.datePublished as string).getUTCFullYear(),
+    2023,
+  );
+});
+
+test("author always resolves to a linked Keploy Team Person when missing", () => {
+  const author = nullPost.author as Record<string, unknown>;
+  assert.equal(author["@type"], "Person");
+  assert.equal(author.name, AUTHOR_FALLBACK_NAME);
+  assert.equal(author.url, "https://keploy.io/blog/authors/keploy-team");
+});
+
+test("description is stripped of HTML tags before entering the schema", () => {
+  const post = getBlogPostingSchema({
+    title: "HTML excerpt",
+    url: "https://keploy.io/blog/community/z",
+    datePublished: "2024-01-02",
+    description: "<p>Hello <strong>world</strong> &amp; more</p>",
+  });
+  const desc = post.description as string;
+  assert.ok(!/[<>]/.test(desc), "no raw HTML tags should remain");
+  assert.ok(desc.includes("Hello world"), "text content is preserved");
+});
+
+test("publisher and the Organization node share one stable @id", () => {
+  const org = getOrganizationSchema();
+  assert.equal(org["@id"], ORG_ID);
+  const publisher = nullPost.publisher as Record<string, unknown>;
+  assert.equal(publisher["@id"], ORG_ID);
+});
+
+test("core required Article fields are always present", () => {
+  for (const field of ["@context", "@type", "headline", "author", "publisher", "image", "datePublished"]) {
+    assert.ok(nullPost[field] !== undefined, `${field} must be present`);
+  }
+});
+
+test("technology posts render as TechArticle", () => {
+  const tech = getBlogPostingSchema({
+    title: "Tech post",
+    url: "https://keploy.io/blog/technology/x",
+    datePublished: "2024-01-02",
+    categorySlug: "technology",
+  });
+  assert.equal(tech["@type"], "TechArticle");
+});

utils/seo.ts

@@ -111,6 +111,28 @@ export function sanitizeTitle(rawTitle: string | undefined | null): string {
   return decodeEntitiesForAttribute(rawTitle);
 }
 
+const TITLE_SUFFIX = " | Keploy Blog";
+const MAX_TITLE_LENGTH = 60;
+
+/**
+ * Build a <title> that stays within the ~60-char SERP limit (SEMrush "title
+ * too long", 113 posts). Order of preference:
+ *   1. `Title | Keploy Blog` when it fits,
+ *   2. the bare title when adding the suffix would overflow but the title fits,
+ *   3. the title truncated at a word boundary as a last resort.
+ * Entity-decoded via sanitizeTitle so WP entities don't inflate the length.
+ */
+export function buildPageTitle(rawTitle: string | undefined | null): string {
+  const base = sanitizeTitle(rawTitle).trim();
+  if (!base) return "Keploy Blog";
+  const withSuffix = `${base}${TITLE_SUFFIX}`;
+  if (withSuffix.length <= MAX_TITLE_LENGTH) return withSuffix;
+  if (base.length <= MAX_TITLE_LENGTH) return base;
+  const clipped = base.slice(0, MAX_TITLE_LENGTH);
+  const lastSpace = clipped.lastIndexOf(" ");
+  return (lastSpace > 40 ? clipped.slice(0, lastSpace) : clipped).trimEnd();
+}
+
 /**
  * Generate a safe meta description for a blog post.
  * Uses Yoast metaDesc if available and long enough, otherwise generates from title.