From 2d0c36bd95ee19dc0576eae651a66cf50de999db Mon Sep 17 00:00:00 2001
From: Duncan Crawbuck <duncan@crawbuck.com>
Date: Wed, 10 Jun 2026 15:23:44 -0700
Subject: [PATCH] Add hosted API docs links

---
 src/routes/$.tsx     | 87 +++++++++++++++++++++++++++++---------------
 src/routes/index.tsx | 35 +++++++++++++++---
 2 files changed, 88 insertions(+), 34 deletions(-)

diff --git a/src/routes/$.tsx b/src/routes/$.tsx
index b1f184c..2e5185e 100644
--- a/src/routes/$.tsx
+++ b/src/routes/$.tsx
@@ -1,5 +1,6 @@
 import { createFileRoute, notFound } from "@tanstack/react-router";
 import { DocsLayout } from "fumadocs-ui/layouts/notebook";
+import { getLayoutTabs, type LayoutTab } from "fumadocs-ui/layouts/shared";
 import { createServerFn } from "@tanstack/react-start";
 import { source } from "@/lib/source";
 import browserCollections from "fumadocs-mdx:collections/browser";
@@ -23,6 +24,7 @@ import {
 } from "@/lib/metadata";
 import { getSdkContextFromRouterPath, SDK_CONTEXT_SLUGS } from "@/lib/sdk-navigation";
 import { buildDocsApiPath } from "@/lib/url-base";
+import { Code } from "lucide-react";
 
 import { staticCacheMiddleware } from "@/lib/static-cache-middleware";
 
@@ -152,6 +154,7 @@ const clientLoader = browserCollections.docs.createClientLoader({
 });
 const NAVBAR_ONLY_TABS = new Set(["support", "changelog"]);
 const SDK_CONTEXT_SET = new Set<string>(SDK_CONTEXT_SLUGS);
+const API_REFERENCE_URL = "https://api.superwall.com/docs";
 
 function parseSDKSubPath(url: string): string | null {
   const withoutBase = url.replace(/^\/docs/, "") || "/";
@@ -163,48 +166,74 @@ function parseSDKSubPath(url: string): string | null {
   return withoutBase.slice(sdkPrefix.length);
 }
 
+function getDocsLayoutTabs(
+  pageTree: Awaited<ReturnType<typeof source.serializePageTree>>,
+  currentSubPath: string | null,
+): LayoutTab[] {
+  const tabs = getLayoutTabs(pageTree, {
+    transform: (option) => {
+      const tabPrefix = option.url.replace(/^\/docs\//, "").split("/")[0];
+      if (NAVBAR_ONLY_TABS.has(tabPrefix)) return null;
+
+      let { url } = option;
+      if (currentSubPath && option.urls) {
+        if (SDK_CONTEXT_SET.has(tabPrefix)) {
+          const candidate = `/docs/${tabPrefix}/${currentSubPath}`;
+          if (option.urls.has(candidate)) {
+            url = candidate;
+          }
+        }
+      }
+
+      return {
+        ...option,
+        url,
+        icon: (
+          <span className="flex size-full items-center justify-center [&_svg]:!size-5">
+            {option.icon}
+          </span>
+        ),
+        props: {
+          ...option.props,
+          children: option.icon,
+        },
+      };
+    },
+  });
+
+  tabs.push({
+    title: "API",
+    url: API_REFERENCE_URL,
+    icon: (
+      <span className="flex size-full items-center justify-center [&_svg]:!size-5">
+        <Code />
+      </span>
+    ),
+    props: {
+      target: "_blank",
+      rel: "noreferrer noopener",
+      children: <Code />,
+    },
+  });
+
+  return tabs;
+}
+
 function Page() {
   const loaderData = Route.useLoaderData();
   const data = useFumadocsLoader(loaderData);
   const { nav, ...base } = baseOptions();
   const currentSubPath = parseSDKSubPath(loaderData.url);
+  const layoutTabs = getDocsLayoutTabs(data.pageTree, currentSubPath);
 
   return (
     <DocsLayout
       {...base}
       tabMode="navbar"
+      tabs={layoutTabs}
       nav={{ ...nav, mode: "auto" }}
       tree={data.pageTree}
       sidebar={{
-        tabs: {
-          transform: (option, node) => {
-            const tabPrefix = option.url.replace(/^\/docs\//, "").split("/")[0];
-            if (NAVBAR_ONLY_TABS.has(tabPrefix)) return null;
-
-            let { url } = option;
-            if (currentSubPath && option.urls) {
-              if (SDK_CONTEXT_SET.has(tabPrefix)) {
-                const candidate = `/docs/${tabPrefix}/${currentSubPath}`;
-                if (option.urls.has(candidate)) {
-                  url = candidate;
-                }
-              }
-            }
-            return {
-              ...option,
-              url,
-              icon: (
-                <span className="flex size-full items-center justify-center [&_svg]:!size-5">
-                  {option.icon}
-                </span>
-              ),
-              props: {
-                ...option.props,
-                children: option.icon,
-              },
-            };
-          },
-        },
         prefetch: true,
         footer: <SidebarDiscordLink />,
       }}
diff --git a/src/routes/index.tsx b/src/routes/index.tsx
index 5d24b0b..a13a416 100644
--- a/src/routes/index.tsx
+++ b/src/routes/index.tsx
@@ -8,6 +8,7 @@ import {
   CircleHelp,
   History,
   AlertTriangle,
+  Code,
   Users,
   Cpu,
 } from "lucide-react";
@@ -123,6 +124,12 @@ const docsCards: DocCard[] = [
     href: buildDocsPath("integrations"),
     icon: <Puzzle className="size-5" />,
   },
+  {
+    title: "API",
+    description: "Explore Superwall's hosted API reference.",
+    href: "https://api.superwall.com/docs",
+    icon: <Code className="size-5" />,
+  },
   {
     title: "Support",
     description: "FAQs, troubleshooting guides, and help for common issues.",
@@ -188,12 +195,10 @@ function OverviewCard({ title, description, href, icon }: DocCard) {
   });
   const normalizedHref = normalizeDocsInternalHref(href);
   const resolvedHref = resolveSdkAwareDocsHref(normalizedHref, currentRouterPath);
+  const isExternal = /^[a-zA-Z][a-zA-Z\d+\-.]*:/.test(resolvedHref);
 
-  return (
-    <Link
-      to={toRouterPath(resolvedHref)}
-      className="group flex flex-col gap-3 rounded-xl border border-fd-border bg-fd-secondary/50 p-5 transition-all duration-200 hover:border-fd-primary/40 hover:bg-fd-secondary"
-    >
+  const content = (
+    <>
       <div className="flex items-center gap-3">
         <div className="flex size-9 shrink-0 items-center justify-center rounded-lg bg-fd-accent text-fd-foreground transition-colors duration-200 group-hover:bg-fd-primary/10 group-hover:text-fd-primary">
           {icon}
@@ -201,6 +206,26 @@ function OverviewCard({ title, description, href, icon }: DocCard) {
         <h3 className="font-semibold text-fd-foreground">{title}</h3>
       </div>
       <p className="text-sm leading-relaxed text-fd-muted-foreground">{description}</p>
+    </>
+  );
+
+  const className =
+    "group flex flex-col gap-3 rounded-xl border border-fd-border bg-fd-secondary/50 p-5 transition-all duration-200 hover:border-fd-primary/40 hover:bg-fd-secondary";
+
+  if (isExternal) {
+    return (
+      <a href={resolvedHref} target="_blank" rel="noreferrer noopener" className={className}>
+        {content}
+      </a>
+    );
+  }
+
+  return (
+    <Link
+      to={toRouterPath(resolvedHref)}
+      className={className}
+    >
+      {content}
     </Link>
   );
 }