From 6f1bf1a9710140c62c920897c3b743e99dda8789 Mon Sep 17 00:00:00 2001
From: Antoine van der Lee <4329185+AvdLee@users.noreply.github.com>
Date: Mon, 2 Mar 2026 09:20:51 +0100
Subject: [PATCH 1/4] Add JSON-LD structured data to docs pages

Inject TechArticle and BreadcrumbList schemas on all docs pages.
Add FAQPage schema on the FAQ page for rich search results.
---
 docs/src/components/starlight/Head.astro | 153 ++++++++++++++++++++++-
 1 file changed, 149 insertions(+), 4 deletions(-)

diff --git a/docs/src/components/starlight/Head.astro b/docs/src/components/starlight/Head.astro
index 8b194f3a..f0ccd2d8 100644
--- a/docs/src/components/starlight/Head.astro
+++ b/docs/src/components/starlight/Head.astro
@@ -1,10 +1,145 @@
 ---
-/**
- * Custom Head component for RocketSim docs
- * Includes proper favicon and meta tags matching the main site
- */
 import Default from "@astrojs/starlight/components/Head.astro";
 import PlausibleAnalytics from "@/components/PlausibleAnalytics.astro";
+
+const baseUrl = "https://www.rocketsim.app";
+const { entry } = Astro.props;
+const title = entry?.data?.title ?? "RocketSim Docs";
+const description = entry?.data?.description ?? "";
+const slug = entry?.slug ?? "";
+const pageUrl = `${baseUrl}/${slug}`;
+
+const pathSegments = slug.split("/").filter(Boolean);
+const breadcrumbItems = [
+  { name: "Home", url: baseUrl },
+  { name: "Docs", url: `${baseUrl}/docs` },
+];
+let currentPath = "";
+for (const segment of pathSegments.slice(1)) {
+  currentPath += `/${segment}`;
+  const name = segment
+    .split("-")
+    .map((w: string) => w.charAt(0).toUpperCase() + w.slice(1))
+    .join(" ");
+  breadcrumbItems.push({ name, url: `${baseUrl}/docs${currentPath}` });
+}
+if (breadcrumbItems.length > 2) {
+  breadcrumbItems[breadcrumbItems.length - 1].name = title;
+}
+
+const isFaqPage = slug.endsWith("support/faq");
+
+const schemas: Record<string, unknown>[] = [];
+
+if (title !== "RocketSim Docs" && title !== "404") {
+  schemas.push({
+    "@context": "https://schema.org",
+    "@type": "TechArticle",
+    headline: title,
+    description,
+    url: pageUrl,
+    author: {
+      "@type": "Organization",
+      name: "RocketSim",
+      url: baseUrl,
+    },
+    publisher: {
+      "@type": "Organization",
+      name: "RocketSim",
+      url: baseUrl,
+      logo: `${baseUrl}/images/rocketsim-app-icon.png`,
+    },
+    mainEntityOfPage: {
+      "@type": "WebPage",
+      "@id": pageUrl,
+    },
+  });
+}
+
+if (breadcrumbItems.length > 1) {
+  schemas.push({
+    "@context": "https://schema.org",
+    "@type": "BreadcrumbList",
+    itemListElement: breadcrumbItems.map((item, index) => ({
+      "@type": "ListItem",
+      position: index + 1,
+      name: item.name,
+      item: item.url,
+    })),
+  });
+}
+
+const faqEntries = isFaqPage
+  ? [
+      {
+        q: "Does RocketSim offer out-of-the App Store distribution?",
+        a: "Yes. Get in touch via support@rocketsim.app.",
+      },
+      {
+        q: "Are there non-recurring subscriptions?",
+        a: "Yes, you can consider buying Team Licenses at rocketsim.app/team-insights.",
+      },
+      {
+        q: "Can I reimburse my App Store subscription?",
+        a: "Yes, RocketSim offers Team Licenses as an alternative at rocketsim.app/team-insights.",
+      },
+      {
+        q: "Do you provide commercial or team licenses?",
+        a: "Yes, check out Team Licenses at rocketsim.app/team-insights.",
+      },
+      {
+        q: "Can I buy a lifetime RocketSim license?",
+        a: "No, but you can earn a lifetime license through SwiftLee Weekly's referral program. Join the newsletter and follow the instructions.",
+      },
+      {
+        q: "Why is my video not accepted by App Store Connect?",
+        a: "Videos are optimized for App Previews following Apple's specifications. Make sure to use a Simulator matching a device from the App Preview specifications.",
+      },
+      {
+        q: "Why wouldn't I just use xcrun simctl?",
+        a: "RocketSim uses xcrun simctl under the hood but enhances the output with touches, device bezels, and a visual interface for quicker access.",
+      },
+      {
+        q: "Why does RocketSim need screen recording permissions?",
+        a: "RocketSim is sandboxed and needs screen recording permissions to read Simulator window titles, which it uses to determine the currently active Simulator.",
+      },
+      {
+        q: "Where can I report bugs or feature requests?",
+        a: "Issues and feature requests are managed on GitHub at github.com/AvdLee/RocketSimApp/issues.",
+      },
+      {
+        q: "How can I get PNG images instead of JPEG?",
+        a: "Disable App Store Connect (ASC) Optimization. ASC requires JPEG images without alpha layer.",
+      },
+      {
+        q: "Why are my iPad captures upside-down?",
+        a: "RocketSim cannot detect landscape-left or landscape-right and defaults to one rotation. Rotate your Simulator twice and restart the recording.",
+      },
+      {
+        q: "Can I create transparent captures?",
+        a: "Yes, disable App Preview Optimized and set your background color to transparent.",
+      },
+      {
+        q: "Network Speed Control isn't working, what can I do?",
+        a: "Quit Xcode, all Simulators, and RocketSim, then reopen them. Check System Settings → Privacy & Security for pending permissions. On macOS Sequoia, enable the Network Extension in System Settings → General → Login Items & Extensions.",
+      },
+    ]
+  : [];
+
+if (isFaqPage && faqEntries.length > 0) {
+  schemas.push({
+    "@context": "https://schema.org",
+    "@type": "FAQPage",
+    mainEntity: faqEntries.map((faq) => ({
+      "@type": "Question",
+      name: faq.q,
+      acceptedAnswer: {
+        "@type": "Answer",
+        text: faq.a,
+      },
+    })),
+  });
+}
 ---
 
 <Default {...Astro.props}><slot /></Default>
@@ -22,4 +157,14 @@ import PlausibleAnalytics from "@/components/PlausibleAnalytics.astro";
 <!-- Additional meta for better SEO -->
 <meta name="author" content="RocketSim" />
 
+{
+  schemas.map((schema) => (
+    <script
+      type="application/ld+json"
+      is:inline
+      set:html={JSON.stringify(schema)}
+    />
+  ))
+}
+
 <PlausibleAnalytics />

From 2e8968fbd1460122d33aa7b5a650c2381d85cbe3 Mon Sep 17 00:00:00 2001
From: Antoine van der Lee <4329185+AvdLee@users.noreply.github.com>
Date: Mon, 2 Mar 2026 10:08:30 +0100
Subject: [PATCH 2/4] Fix breadcrumb links to only include routable paths

Skip intermediate URL segments that don't have index pages.
Breadcrumbs now link: Home > Docs > Current Page.
---
 docs/src/components/starlight/Head.astro | 14 ++------------
 1 file changed, 2 insertions(+), 12 deletions(-)

diff --git a/docs/src/components/starlight/Head.astro b/docs/src/components/starlight/Head.astro
index f0ccd2d8..65c01c47 100644
--- a/docs/src/components/starlight/Head.astro
+++ b/docs/src/components/starlight/Head.astro
@@ -9,22 +9,12 @@ const description = entry?.data?.description ?? "";
 const slug = entry?.slug ?? "";
 const pageUrl = `${baseUrl}/${slug}`;
 
-const pathSegments = slug.split("/").filter(Boolean);
 const breadcrumbItems = [
   { name: "Home", url: baseUrl },
   { name: "Docs", url: `${baseUrl}/docs` },
 ];
-let currentPath = "";
-for (const segment of pathSegments.slice(1)) {
-  currentPath += `/${segment}`;
-  const name = segment
-    .split("-")
-    .map((w: string) => w.charAt(0).toUpperCase() + w.slice(1))
-    .join(" ");
-  breadcrumbItems.push({ name, url: `${baseUrl}/docs${currentPath}` });
-}
-if (breadcrumbItems.length > 2) {
-  breadcrumbItems[breadcrumbItems.length - 1].name = title;
+if (title !== "RocketSim Docs" && title !== "404") {
+  breadcrumbItems.push({ name: title, url: pageUrl });
 }
 
 const isFaqPage = slug.endsWith("support/faq");

From 9519a3c62c67c7bdceb01c4c176425c80adcf257 Mon Sep 17 00:00:00 2001
From: Antoine van der Lee <4329185+AvdLee@users.noreply.github.com>
Date: Mon, 2 Mar 2026 10:50:53 +0100
Subject: [PATCH 3/4] Fix BreadcrumbList on 404 page and escape JSON-LD output

Skip BreadcrumbList structured data on 404 pages since error pages
should not publish structured data. Escape '<' as \u003c in JSON-LD
to prevent potential XSS if page titles ever contain </script>.
---
 docs/src/components/starlight/Head.astro | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/src/components/starlight/Head.astro b/docs/src/components/starlight/Head.astro
index 65c01c47..da892756 100644
--- a/docs/src/components/starlight/Head.astro
+++ b/docs/src/components/starlight/Head.astro
@@ -46,7 +46,7 @@ if (title !== "RocketSim Docs" && title !== "404") {
   });
 }
 
-if (breadcrumbItems.length > 1) {
+if (breadcrumbItems.length > 1 && title !== "404") {
   schemas.push({
     "@context": "https://schema.org",
     "@type": "BreadcrumbList",
@@ -152,7 +152,7 @@ if (isFaqPage && faqEntries.length > 0) {
     <script
       type="application/ld+json"
       is:inline
-      set:html={JSON.stringify(schema)}
+      set:html={JSON.stringify(schema).replaceAll("<", "\\u003c")}
     />
   ))
 }

From 8e551a327f1d34158aa2a710a82cd4b17dfc4bea Mon Sep 17 00:00:00 2001
From: Antoine van der Lee <4329185+AvdLee@users.noreply.github.com>
Date: Wed, 4 Mar 2026 15:10:43 +0100
Subject: [PATCH 4/4] Reuse StructuredData component for docs JSON-LD schemas

Move TechArticle, BreadcrumbList, and FAQPage structured data from
inline logic in Head.astro into the shared StructuredData component
with proper TypeScript types. Extract FAQ entries into a shared JSON
data file to avoid duplication with the markdown FAQ page. Apply XSS
escaping to all JSON-LD output globally.

Addresses reviewer feedback on PR #934.
---
 docs/src/components/starlight/Head.astro      | 151 +++---------------
 docs/src/data/faq-support.json                |  58 +++++++
 .../layouts/components/StructuredData.astro   | 141 +++++++++++++++-
 3 files changed, 221 insertions(+), 129 deletions(-)
 create mode 100644 docs/src/data/faq-support.json

diff --git a/docs/src/components/starlight/Head.astro b/docs/src/components/starlight/Head.astro
index da892756..86aa6449 100644
--- a/docs/src/components/starlight/Head.astro
+++ b/docs/src/components/starlight/Head.astro
@@ -1,135 +1,20 @@
 ---
 import Default from "@astrojs/starlight/components/Head.astro";
 import PlausibleAnalytics from "@/components/PlausibleAnalytics.astro";
+import StructuredData from "@/components/StructuredData.astro";
+import config from "@/config/config.json";
+import faqEntries from "@/data/faq-support.json";
 
-const baseUrl = "https://www.rocketsim.app";
 const { entry } = Astro.props;
 const title = entry?.data?.title ?? "RocketSim Docs";
 const description = entry?.data?.description ?? "";
 const slug = entry?.slug ?? "";
-const pageUrl = `${baseUrl}/${slug}`;
-
-const breadcrumbItems = [
-  { name: "Home", url: baseUrl },
-  { name: "Docs", url: `${baseUrl}/docs` },
-];
-if (title !== "RocketSim Docs" && title !== "404") {
-  breadcrumbItems.push({ name: title, url: pageUrl });
-}
+const pageUrl = `${config.site.base_url}/${slug}`;
 
+const isContentPage = title !== "RocketSim Docs" && title !== "404";
 const isFaqPage = slug.endsWith("support/faq");
 
-const schemas: Record<string, unknown>[] = [];
-
-if (title !== "RocketSim Docs" && title !== "404") {
-  schemas.push({
-    "@context": "https://schema.org",
-    "@type": "TechArticle",
-    headline: title,
-    description,
-    url: pageUrl,
-    author: {
-      "@type": "Organization",
-      name: "RocketSim",
-      url: baseUrl,
-    },
-    publisher: {
-      "@type": "Organization",
-      name: "RocketSim",
-      url: baseUrl,
-      logo: `${baseUrl}/images/rocketsim-app-icon.png`,
-    },
-    mainEntityOfPage: {
-      "@type": "WebPage",
-      "@id": pageUrl,
-    },
-  });
-}
-
-if (breadcrumbItems.length > 1 && title !== "404") {
-  schemas.push({
-    "@context": "https://schema.org",
-    "@type": "BreadcrumbList",
-    itemListElement: breadcrumbItems.map((item, index) => ({
-      "@type": "ListItem",
-      position: index + 1,
-      name: item.name,
-      item: item.url,
-    })),
-  });
-}
-
-const faqEntries = isFaqPage
-  ? [
-      {
-        q: "Does RocketSim offer out-of-the App Store distribution?",
-        a: "Yes. Get in touch via support@rocketsim.app.",
-      },
-      {
-        q: "Are there non-recurring subscriptions?",
-        a: "Yes, you can consider buying Team Licenses at rocketsim.app/team-insights.",
-      },
-      {
-        q: "Can I reimburse my App Store subscription?",
-        a: "Yes, RocketSim offers Team Licenses as an alternative at rocketsim.app/team-insights.",
-      },
-      {
-        q: "Do you provide commercial or team licenses?",
-        a: "Yes, check out Team Licenses at rocketsim.app/team-insights.",
-      },
-      {
-        q: "Can I buy a lifetime RocketSim license?",
-        a: "No, but you can earn a lifetime license through SwiftLee Weekly's referral program. Join the newsletter and follow the instructions.",
-      },
-      {
-        q: "Why is my video not accepted by App Store Connect?",
-        a: "Videos are optimized for App Previews following Apple's specifications. Make sure to use a Simulator matching a device from the App Preview specifications.",
-      },
-      {
-        q: "Why wouldn't I just use xcrun simctl?",
-        a: "RocketSim uses xcrun simctl under the hood but enhances the output with touches, device bezels, and a visual interface for quicker access.",
-      },
-      {
-        q: "Why does RocketSim need screen recording permissions?",
-        a: "RocketSim is sandboxed and needs screen recording permissions to read Simulator window titles, which it uses to determine the currently active Simulator.",
-      },
-      {
-        q: "Where can I report bugs or feature requests?",
-        a: "Issues and feature requests are managed on GitHub at github.com/AvdLee/RocketSimApp/issues.",
-      },
-      {
-        q: "How can I get PNG images instead of JPEG?",
-        a: "Disable App Store Connect (ASC) Optimization. ASC requires JPEG images without alpha layer.",
-      },
-      {
-        q: "Why are my iPad captures upside-down?",
-        a: "RocketSim cannot detect landscape-left or landscape-right and defaults to one rotation. Rotate your Simulator twice and restart the recording.",
-      },
-      {
-        q: "Can I create transparent captures?",
-        a: "Yes, disable App Preview Optimized and set your background color to transparent.",
-      },
-      {
-        q: "Network Speed Control isn't working, what can I do?",
-        a: "Quit Xcode, all Simulators, and RocketSim, then reopen them. Check System Settings → Privacy & Security for pending permissions. On macOS Sequoia, enable the Network Extension in System Settings → General → Login Items & Extensions.",
-      },
-    ]
-  : [];
-
-if (isFaqPage && faqEntries.length > 0) {
-  schemas.push({
-    "@context": "https://schema.org",
-    "@type": "FAQPage",
-    mainEntity: faqEntries.map((faq) => ({
-      "@type": "Question",
-      name: faq.q,
-      acceptedAnswer: {
-        "@type": "Answer",
-        text: faq.a,
-      },
-    })),
-  });
-}
+const ogImage = `${config.site.base_url}${config.metadata.meta_image}`;
 ---
 
 <Default {...Astro.props}><slot /></Default>
@@ -147,14 +32,26 @@ if (isFaqPage && faqEntries.length > 0) {
 <!-- Additional meta for better SEO -->
 <meta name="author" content="RocketSim" />
 
+<!-- Open Graph image for social sharing -->
+<meta property="og:site_name" content="RocketSim" />
+<meta property="og:image" content={ogImage} />
+<meta property="twitter:card" content="summary_large_image" />
+<meta property="twitter:image" content={ogImage} />
+<meta name="twitter:site" content="@rocketsim_app" />
+
 {
-  schemas.map((schema) => (
-    <script
-      type="application/ld+json"
-      is:inline
-      set:html={JSON.stringify(schema).replaceAll("<", "\\u003c")}
+  isContentPage && !isFaqPage && (
+    <StructuredData
+      type="techArticle"
+      techArticle={{ title, description, url: pageUrl }}
     />
-  ))
+  )
+}
+
+{
+  isFaqPage && (
+    <StructuredData type="faqPage" faqEntries={faqEntries} url={pageUrl} />
+  )
 }
 
 <PlausibleAnalytics />
diff --git a/docs/src/data/faq-support.json b/docs/src/data/faq-support.json
new file mode 100644
index 00000000..7e71d7f1
--- /dev/null
+++ b/docs/src/data/faq-support.json
@@ -0,0 +1,58 @@
+[
+  {
+    "question": "Do you offer out-of-the App Store distribution?",
+    "answer": "Yes, we do. Get in touch via support@rocketsim.app."
+  },
+  {
+    "question": "Are there non-recurring subscriptions as well?",
+    "answer": "Yes, you can consider buying Team Licenses at rocketsim.app/team-insights."
+  },
+  {
+    "question": "I can't reimburse App Store subscriptions, is there an alternative?",
+    "answer": "Yes, we offer Team Licenses at rocketsim.app/team-insights."
+  },
+  {
+    "question": "Do you provide the option for commercial or team licenses?",
+    "answer": "Yes, check out Team Licenses at rocketsim.app/team-insights."
+  },
+  {
+    "question": "Can I buy a lifetime license?",
+    "answer": "No, but you can join SwiftLee Weekly's referral program to get a lifetime RocketSim license. Just join the newsletter and follow the instructions in the email."
+  },
+  {
+    "question": "Why is my video not accepted by App Store Connect?",
+    "answer": "The videos are optimized for App Previews following Apple's specifications. App Store Connect does not accept each device, so your selected Simulator could not support App Previews. Make sure to use a Simulator matching a device from the App Preview specifications."
+  },
+  {
+    "question": "Why wouldn't I just use xcrun simctl?",
+    "answer": "RocketSim uses xcrun simctl as well, but it enhances the output and provides interfaces for quicker access. Recordings, for example, are enhanced with touches and device bezels that you won't get through the command line tools."
+  },
+  {
+    "question": "Why does RocketSim need screen recording permissions?",
+    "answer": "RocketSim is sandboxed and can't read NSWindow titles without screen recording permissions. RocketSim needs to read the title of the Simulator windows to determine the currently active Simulator."
+  },
+  {
+    "question": "Where can I follow active development?",
+    "answer": "RocketSim is developed by Antoine van der Lee. You can follow him or the official RocketSim Twitter Account for updates about development."
+  },
+  {
+    "question": "Where can I report bugs or feature requests?",
+    "answer": "Issues and feature requests are managed on GitHub at github.com/AvdLee/RocketSimApp/issues."
+  },
+  {
+    "question": "I only get JPEG images, how can I get PNG images again?",
+    "answer": "You've likely enabled App Store Connect (ASC) Optimization. ASC requires JPEG images without alpha layer. Disable the option and you should get PNGs again."
+  },
+  {
+    "question": "Why are my iPad captures upside-down?",
+    "answer": "RocketSim cannot detect landscape-left or landscape-right and defaults to one landscape rotation. The fix is simple: rotate your Simulator twice and restart the recording."
+  },
+  {
+    "question": "Can I create transparent captures?",
+    "answer": "Yes, make sure to disable App Preview Optimized and set your background color to transparent."
+  },
+  {
+    "question": "Network Speed Control isn't working for me, what can I do?",
+    "answer": "This is usually caused by missing system permissions. Quit Xcode, all Simulators, and RocketSim, then reopen them. Open System Settings → Privacy & Security and approve any pending RocketSim permissions. On macOS Sequoia and later, enable the Network Extension in System Settings → General → Login Items & Extensions."
+  }
+]
diff --git a/docs/src/layouts/components/StructuredData.astro b/docs/src/layouts/components/StructuredData.astro
index 6af253c6..a5123752 100644
--- a/docs/src/layouts/components/StructuredData.astro
+++ b/docs/src/layouts/components/StructuredData.astro
@@ -39,6 +39,24 @@ type OfferProps = {
   };
 };
 
+type TechArticleProps = {
+  type: "techArticle";
+  techArticle: {
+    title: string;
+    description: string;
+    url: string;
+  };
+};
+
+type FAQPageProps = {
+  type: "faqPage";
+  faqEntries: Array<{
+    question: string;
+    answer: string;
+  }>;
+  url: string;
+};
+
 type StaticProps = {
   type: "static";
 };
@@ -48,7 +66,7 @@ type WebsiteProps = {
 };
 
 // prettier-ignore
-export type Props = ArticleProps | ProductProps | OfferProps | StaticProps | WebsiteProps;
+export type Props = ArticleProps | ProductProps | OfferProps | TechArticleProps | FAQPageProps | StaticProps | WebsiteProps;
 
 // TypeScript interfaces for JSON-LD schemas
 interface SchemaBase {
@@ -157,6 +175,31 @@ interface OfferSchema extends SchemaBase {
   description?: string;
 }
 
+interface TechArticleSchema extends SchemaBase {
+  "@type": "TechArticle";
+  headline: string;
+  description: string;
+  url: string;
+  author: OrganizationSchema;
+  publisher: OrganizationSchema;
+  mainEntityOfPage: {
+    "@type": "WebPage";
+    "@id": string;
+  };
+}
+
+interface FAQPageSchema extends SchemaBase {
+  "@type": "FAQPage";
+  mainEntity: Array<{
+    "@type": "Question";
+    name: string;
+    acceptedAnswer: {
+      "@type": "Answer";
+      text: string;
+    };
+  }>;
+}
+
 const { type } = Astro.props;
 
 // Author data (hardcoded - single author blog)
@@ -341,6 +384,100 @@ if (type === "product") {
   schemas.push(breadcrumbSchema);
 }
 
+if (type === "techArticle") {
+  const { techArticle } = Astro.props;
+
+  const techArticleSchema: TechArticleSchema = {
+    "@context": "https://schema.org",
+    "@type": "TechArticle",
+    headline: techArticle.title,
+    description: techArticle.description,
+    url: techArticle.url,
+    author: organizationData,
+    publisher: {
+      ...organizationData,
+      logo: `${config.site.base_url}/images/rocketsim-app-icon.png`,
+    },
+    mainEntityOfPage: {
+      "@type": "WebPage",
+      "@id": techArticle.url,
+    },
+  };
+  schemas.push(techArticleSchema);
+
+  const breadcrumbSchema: BreadcrumbListSchema = {
+    "@context": "https://schema.org",
+    "@type": "BreadcrumbList",
+    "@id": `${techArticle.url}#breadcrumb`,
+    itemListElement: [
+      {
+        "@type": "ListItem",
+        position: 1,
+        name: "Home",
+        item: config.site.base_url,
+      },
+      {
+        "@type": "ListItem",
+        position: 2,
+        name: "Docs",
+        item: `${config.site.base_url}/docs`,
+      },
+      {
+        "@type": "ListItem",
+        position: 3,
+        name: techArticle.title,
+        item: techArticle.url,
+      },
+    ],
+  };
+  schemas.push(breadcrumbSchema);
+}
+
+if (type === "faqPage") {
+  const { faqEntries, url } = Astro.props;
+
+  const faqPageSchema: FAQPageSchema = {
+    "@context": "https://schema.org",
+    "@type": "FAQPage",
+    mainEntity: faqEntries.map((faq) => ({
+      "@type": "Question" as const,
+      name: faq.question,
+      acceptedAnswer: {
+        "@type": "Answer" as const,
+        text: faq.answer,
+      },
+    })),
+  };
+  schemas.push(faqPageSchema);
+
+  const breadcrumbSchema: BreadcrumbListSchema = {
+    "@context": "https://schema.org",
+    "@type": "BreadcrumbList",
+    "@id": `${url}#breadcrumb`,
+    itemListElement: [
+      {
+        "@type": "ListItem",
+        position: 1,
+        name: "Home",
+        item: config.site.base_url,
+      },
+      {
+        "@type": "ListItem",
+        position: 2,
+        name: "Docs",
+        item: `${config.site.base_url}/docs`,
+      },
+      {
+        "@type": "ListItem",
+        position: 3,
+        name: "FAQ",
+        item: url,
+      },
+    ],
+  };
+  schemas.push(breadcrumbSchema);
+}
+
 if (type === "offer") {
   const { offers } = Astro.props;
   // 1. SoftwareApplication with individual Offer schemas for each tier
@@ -439,7 +576,7 @@ if (type === "offer") {
     <script
       type="application/ld+json"
       is:inline
-      set:html={JSON.stringify(schema)}
+      set:html={JSON.stringify(schema).replaceAll("<", "\\u003c")}
     />
   ))
 }