diff --git a/docs/pages/sdk/v5_3_x/VersionWarning.tsx b/docs/components/VersionWarning.tsx
similarity index 100%
rename from docs/pages/sdk/v5_3_x/VersionWarning.tsx
rename to docs/components/VersionWarning.tsx
diff --git a/docs/pages/shared/mutation-result.mdx b/docs/components/shared/mutation-result.mdx
similarity index 100%
rename from docs/pages/shared/mutation-result.mdx
rename to docs/components/shared/mutation-result.mdx
diff --git a/docs/pages/shared/query-result.mdx b/docs/components/shared/query-result.mdx
similarity index 100%
rename from docs/pages/shared/query-result.mdx
rename to docs/components/shared/query-result.mdx
diff --git a/docs/pages/shared/social-login-setup.mdx b/docs/components/shared/social-login-setup.mdx
similarity index 100%
rename from docs/pages/shared/social-login-setup.mdx
rename to docs/components/shared/social-login-setup.mdx
diff --git a/docs/pages/advanced/react-hooks/use-balance.mdx b/docs/pages/advanced/react-hooks/use-balance.mdx
index 447018c3..4370ea8e 100644
--- a/docs/pages/advanced/react-hooks/use-balance.mdx
+++ b/docs/pages/advanced/react-hooks/use-balance.mdx
@@ -1,4 +1,4 @@
-import QueryResult from "../../shared/query-result.mdx"
+import QueryResult from "@components/shared/query-result.mdx"
# useBalance [Hook for getting balance of kernel account]
diff --git a/docs/pages/advanced/react-hooks/use-create-basic-session.mdx b/docs/pages/advanced/react-hooks/use-create-basic-session.mdx
index 4e629ceb..60c818d5 100644
--- a/docs/pages/advanced/react-hooks/use-create-basic-session.mdx
+++ b/docs/pages/advanced/react-hooks/use-create-basic-session.mdx
@@ -1,4 +1,4 @@
-import MutationResult from '../../shared/mutation-result.mdx'
+import MutationResult from "@components/shared/mutation-result.mdx"
# useCreateBasicSession [Hook for creating session for kernel v2 account]
diff --git a/docs/pages/advanced/react-hooks/use-create-kernelclient-eoa.mdx b/docs/pages/advanced/react-hooks/use-create-kernelclient-eoa.mdx
index 4729e6a7..910f9a69 100644
--- a/docs/pages/advanced/react-hooks/use-create-kernelclient-eoa.mdx
+++ b/docs/pages/advanced/react-hooks/use-create-kernelclient-eoa.mdx
@@ -1,4 +1,4 @@
-import MutationResult from '../../shared/mutation-result.mdx'
+import MutationResult from "@components/shared/mutation-result.mdx"
# useCreateKernelClientEOA [Hook for creating kernel client with EOA]
diff --git a/docs/pages/advanced/react-hooks/use-create-kernelclient-passkey.mdx b/docs/pages/advanced/react-hooks/use-create-kernelclient-passkey.mdx
index cb4a6658..3c6f1043 100644
--- a/docs/pages/advanced/react-hooks/use-create-kernelclient-passkey.mdx
+++ b/docs/pages/advanced/react-hooks/use-create-kernelclient-passkey.mdx
@@ -1,4 +1,4 @@
-import MutationResult from '../../shared/mutation-result.mdx'
+import MutationResult from "@components/shared/mutation-result.mdx"
# useCreateKernelClientPasskey [Hook for creating kernel client with Passkey]
diff --git a/docs/pages/advanced/react-hooks/use-create-kernelclient-social.mdx b/docs/pages/advanced/react-hooks/use-create-kernelclient-social.mdx
index b00f7322..8336d311 100644
--- a/docs/pages/advanced/react-hooks/use-create-kernelclient-social.mdx
+++ b/docs/pages/advanced/react-hooks/use-create-kernelclient-social.mdx
@@ -1,4 +1,4 @@
-import MutationResult from '../../shared/mutation-result.mdx'
+import MutationResult from "@components/shared/mutation-result.mdx"
# useCreateKernelClientSocial [Hook for creating a kernel client with social login integration]
diff --git a/docs/pages/advanced/react-hooks/use-create-session.mdx b/docs/pages/advanced/react-hooks/use-create-session.mdx
index 05caf43c..4cf9f3f0 100644
--- a/docs/pages/advanced/react-hooks/use-create-session.mdx
+++ b/docs/pages/advanced/react-hooks/use-create-session.mdx
@@ -1,4 +1,4 @@
-import MutationResult from '../../shared/mutation-result.mdx'
+import MutationResult from "@components/shared/mutation-result.mdx"
# useCreateSession [Hook for creating session for kernel v3 account]
diff --git a/docs/pages/advanced/react-hooks/use-disconnect-kernelclient.mdx b/docs/pages/advanced/react-hooks/use-disconnect-kernelclient.mdx
index 08640084..eac758bb 100644
--- a/docs/pages/advanced/react-hooks/use-disconnect-kernelclient.mdx
+++ b/docs/pages/advanced/react-hooks/use-disconnect-kernelclient.mdx
@@ -1,4 +1,4 @@
-import MutationResult from '../../shared/mutation-result.mdx'
+import MutationResult from "@components/shared/mutation-result.mdx"
# useDisconnectKernelClient [Hook for disconnecting kernel account client]
diff --git a/docs/pages/advanced/react-hooks/use-kernelclient.mdx b/docs/pages/advanced/react-hooks/use-kernelclient.mdx
index 6dc91bf8..ec45a709 100644
--- a/docs/pages/advanced/react-hooks/use-kernelclient.mdx
+++ b/docs/pages/advanced/react-hooks/use-kernelclient.mdx
@@ -1,4 +1,4 @@
-import QueryResult from "../../shared/query-result.mdx"
+import QueryResult from "@components/shared/query-result.mdx"
# useKernelClient [Hook for getting kernel account client]
diff --git a/docs/pages/advanced/react-hooks/use-send-transaction-with-session.mdx b/docs/pages/advanced/react-hooks/use-send-transaction-with-session.mdx
index 98d864a2..63be83f2 100644
--- a/docs/pages/advanced/react-hooks/use-send-transaction-with-session.mdx
+++ b/docs/pages/advanced/react-hooks/use-send-transaction-with-session.mdx
@@ -1,4 +1,4 @@
-import MutationResult from '../../shared/mutation-result.mdx'
+import MutationResult from "@components/shared/mutation-result.mdx"
# useSendTransactionWithSession [Hooks for sending transactions with session keys]
diff --git a/docs/pages/advanced/react-hooks/use-send-transaction.mdx b/docs/pages/advanced/react-hooks/use-send-transaction.mdx
index 00d06d8f..c4f93a41 100644
--- a/docs/pages/advanced/react-hooks/use-send-transaction.mdx
+++ b/docs/pages/advanced/react-hooks/use-send-transaction.mdx
@@ -1,4 +1,4 @@
-import MutationResult from '../../shared/mutation-result.mdx'
+import MutationResult from "@components/shared/mutation-result.mdx"
# useSendTransaction [Hook for sending transaction]
diff --git a/docs/pages/advanced/react-hooks/use-send-useroperation-with-session.mdx b/docs/pages/advanced/react-hooks/use-send-useroperation-with-session.mdx
index 0be5d956..741b0a52 100644
--- a/docs/pages/advanced/react-hooks/use-send-useroperation-with-session.mdx
+++ b/docs/pages/advanced/react-hooks/use-send-useroperation-with-session.mdx
@@ -1,4 +1,4 @@
-import MutationResult from '../../shared/mutation-result.mdx'
+import MutationResult from "@components/shared/mutation-result.mdx"
# useSendUserOperationWithSession [Hooks for sending user operation with session keys]
diff --git a/docs/pages/advanced/react-hooks/use-send-useroperation.mdx b/docs/pages/advanced/react-hooks/use-send-useroperation.mdx
index 8bfa859b..105af9ed 100644
--- a/docs/pages/advanced/react-hooks/use-send-useroperation.mdx
+++ b/docs/pages/advanced/react-hooks/use-send-useroperation.mdx
@@ -1,4 +1,4 @@
-import MutationResult from '../../shared/mutation-result.mdx'
+import MutationResult from "@components/shared/mutation-result.mdx"
# useSendUserOperation [Hook for sending user operation]
diff --git a/docs/pages/advanced/react-hooks/use-session-kernelclient.mdx b/docs/pages/advanced/react-hooks/use-session-kernelclient.mdx
index 85164f89..55c62588 100644
--- a/docs/pages/advanced/react-hooks/use-session-kernelclient.mdx
+++ b/docs/pages/advanced/react-hooks/use-session-kernelclient.mdx
@@ -1,4 +1,4 @@
-import QueryResult from "../../shared/query-result.mdx"
+import QueryResult from "@components/shared/query-result.mdx"
# useSessionKernelClient [Hook for getting kernel account client with session plugin]
diff --git a/docs/pages/advanced/react-hooks/use-set-kernelclient.mdx b/docs/pages/advanced/react-hooks/use-set-kernelclient.mdx
index 738b3b3e..c97fedcd 100644
--- a/docs/pages/advanced/react-hooks/use-set-kernelclient.mdx
+++ b/docs/pages/advanced/react-hooks/use-set-kernelclient.mdx
@@ -1,4 +1,4 @@
-import MutationResult from '../../shared/mutation-result.mdx'
+import MutationResult from "@components/shared/mutation-result.mdx"
# useSetKernelClient [Hook for setting kernel account client]
diff --git a/docs/pages/advanced/react-hooks/use-switch-chain.mdx b/docs/pages/advanced/react-hooks/use-switch-chain.mdx
index 032c61c0..2a8aef82 100644
--- a/docs/pages/advanced/react-hooks/use-switch-chain.mdx
+++ b/docs/pages/advanced/react-hooks/use-switch-chain.mdx
@@ -1,4 +1,4 @@
-import MutationResult from '../../shared/mutation-result.mdx'
+import MutationResult from "@components/shared/mutation-result.mdx"
# useSwitchChain [Hook for switching chain]
diff --git a/docs/pages/onboarding/social-login.mdx b/docs/pages/onboarding/social-login.mdx
index fbe9b1a6..e77f3d6b 100644
--- a/docs/pages/onboarding/social-login.mdx
+++ b/docs/pages/onboarding/social-login.mdx
@@ -1,4 +1,4 @@
-import SocialLoginSetup from '../shared/social-login-setup.mdx'
+import SocialLoginSetup from "@components/shared/social-login-setup.mdx"
# Social Login [Social login allows users to authenticate using their existing social media accounts such as Google or Facebook.]
diff --git a/docs/pages/sdk/v5_3_x/advanced/chain-abstraction.mdx b/docs/pages/sdk/v5_3_x/advanced/chain-abstraction.mdx
index ff705247..80878481 100644
--- a/docs/pages/sdk/v5_3_x/advanced/chain-abstraction.mdx
+++ b/docs/pages/sdk/v5_3_x/advanced/chain-abstraction.mdx
@@ -1,4 +1,4 @@
-import VersionWarning from "../VersionWarning"
+import VersionWarning from "@components/VersionWarning"
Page not found – ZeroDev
+
+ 404
+ That page has moved or no longer exists.
+
+ The documentation was reorganised. Most old links redirect
+ automatically, so this one points at a page that was retired without a
+ replacement.
+
+
+
+
+
diff --git a/docs/public/robots.txt b/docs/public/robots.txt
new file mode 100644
index 00000000..5147ec8c
--- /dev/null
+++ b/docs/public/robots.txt
@@ -0,0 +1,19 @@
+User-agent: *
+Allow: /
+
+User-agent: GPTBot
+Allow: /
+
+User-agent: Claude-Web
+Allow: /
+
+User-agent: Anthropic-AI
+Allow: /
+
+User-agent: ChatGPT-User
+Allow: /
+
+User-agent: Google-Extended
+Allow: /
+
+Sitemap: https://docs.zerodev.app/sitemap.xml
diff --git a/package.json b/package.json
index c29f06e0..53a53230 100644
--- a/package.json
+++ b/package.json
@@ -3,7 +3,7 @@
"type": "module",
"scripts": {
"dev": "vocs dev",
- "build": "vocs build",
+ "build": "vocs build && node scripts/sitemap.mjs",
"start": "node server.mjs",
"preview": "vocs preview",
"check:redirects": "node scripts/check-redirects.mjs",
diff --git a/redirects.config.js b/redirects.config.js
index 09e2c486..8f03f642 100644
--- a/redirects.config.js
+++ b/redirects.config.js
@@ -125,6 +125,10 @@ export const redirects = [
{ from: "/recovery-flow/portal", to: "/advanced/account-recovery/portal" },
// Smart Routing Address (and global-address duplicate)
+ //
+ // /global-address never reaches this server: a Cloudflare rule 301s it to
+ // /smart-routing-address first, so a reader takes two hops. The rule below is
+ // the target we want and takes effect once that Cloudflare rule is gone.
{ from: "/smart-routing-address", to: "/onramp/smart-routing-address/quickstart" },
{ from: "/global-address", to: "/onramp/smart-routing-address/quickstart" },
diff --git a/scripts/check-redirects.mjs b/scripts/check-redirects.mjs
index 0334ceb9..9be09563 100644
--- a/scripts/check-redirects.mjs
+++ b/scripts/check-redirects.mjs
@@ -48,10 +48,8 @@ function sidebarLinks() {
.map((m) => stripTrailingSlash(m[1])));
}
-// Orphaned on purpose. The React hooks tree documents @zerodev/waas, which is
-// unmaintained: DES-21 settled on keeping the pages for old links but hiding
-// them from crawlers, so they stay out of the sidebar. New orphan targets
-// outside these must not be added.
+// Orphaned on purpose: the react-hooks tree is unmaintained and stays hidden,
+// the rest is a known gap. Do not add new orphan targets outside these.
const ORPHAN_OK = ["/advanced/react-hooks/", "/api-and-toolings/", "/smart-accounts/permissions/1-click-trading"];
const SIDEBAR = sidebarLinks();
@@ -84,6 +82,17 @@ for (const { from, to } of redirects) {
}
}
+// The v5.3.x canonical tags are derived from this table (see vocs.config.tsx).
+// A page that stops mapping falls back to crediting itself and quietly competes
+// again. The set's index has no equivalent and is excluded.
+for (const route of ROUTES) {
+ if (!route.startsWith("/sdk/v5_3_x/")) continue;
+ const current = resolveRedirect(route.replace("/sdk/v5_3_x", "/sdk"));
+ if (!current?.startsWith("/")) {
+ errors.push(`${route} has no current page to credit, so its canonical falls back to itself`);
+ }
+}
+
for (const [prefix, target] of PREFIX) {
if (!ROUTES.has(stripTrailingSlash(target))) {
errors.push(`prefix ${prefix} -> ${target} (no such page)`);
diff --git a/scripts/sitemap.mjs b/scripts/sitemap.mjs
new file mode 100644
index 00000000..7ee9469d
--- /dev/null
+++ b/scripts/sitemap.mjs
@@ -0,0 +1,121 @@
+// Writes docs/dist/sitemap.xml after `vocs build`.
+//
+// Read from the built HTML, not the page sources, so the sitemap cannot
+// contradict what a page declares. Listed only if the page asks to be indexed:
+// no noindex, and a canonical pointing at itself.
+
+import { readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { resolveRedirect, stripTrailingSlash } from "../resolve-redirect.js";
+
+export const ORIGIN = "https://docs.zerodev.app";
+
+const ROOT = fileURLToPath(new URL("..", import.meta.url));
+const DIST = join(ROOT, "docs", "dist");
+
+// Under this many characters of visible text a page has nothing to rank for.
+const MIN_TEXT = 50;
+
+function pages(dir, prefix = "") {
+ const out = [];
+ for (const entry of readdirSync(dir)) {
+ const full = join(dir, entry);
+ if (statSync(full).isDirectory())
+ out.push(...pages(full, `${prefix}/${entry}`));
+ else if (entry === "index.html") out.push([prefix || "/", full]);
+ }
+ return out;
+}
+
+const textOf = (html) =>
+ html
+ .replace(/<(script|style)\b[^>]*>[\s\S]*?<\/\1>/gi, "")
+ .replace(/<[^>]+>/g, " ")
+ .replace(/\s+/g, " ")
+ .trim();
+
+const tag = (html, re) => html.match(re)?.[1] ?? null;
+
+export function sitemapEntries() {
+ const skipped = { redirected: 0, noindex: 0, duplicate: 0, empty: 0 };
+ const urls = [];
+ const uncanonical = [];
+
+ for (const [route, file] of pages(DIST)) {
+ // .vocs holds the search index, not pages.
+ if (route.startsWith("/.")) continue;
+
+ if (resolveRedirect(route)) {
+ skipped.redirected++;
+ continue;
+ }
+
+ const html = readFileSync(file, "utf8");
+
+ if (/]+name=["']robots["'][^>]+noindex/i.test(html)) {
+ skipped.noindex++;
+ continue;
+ }
+
+ // No canonical means the head config stopped rendering, which vocs does
+ // silently. Collect and fail rather than listing the page: a sitemap that
+ // keeps working while the tags vanish hides the regression.
+ const canonical = tag(
+ html,
+ /]+rel=["']canonical["'][^>]+href=["']([^"']+)["']/i,
+ );
+ if (!canonical) {
+ uncanonical.push(route);
+ continue;
+ }
+ if (stripTrailingSlash(canonical) !== stripTrailingSlash(ORIGIN + route)) {
+ skipped.duplicate++;
+ continue;
+ }
+
+ if (textOf(html).length < MIN_TEXT) {
+ skipped.empty++;
+ continue;
+ }
+
+ urls.push(route === "/" ? `${ORIGIN}/` : ORIGIN + route);
+ }
+
+ return { urls: urls.sort(), skipped, uncanonical };
+}
+
+function main() {
+ const { urls, skipped, uncanonical } = sitemapEntries();
+
+ if (uncanonical.length) {
+ console.error(`${uncanonical.length} built page(s) have no canonical tag:`);
+ for (const r of uncanonical.slice(0, 10)) console.error(` ${r}`);
+ if (uncanonical.length > 10) {
+ console.error(` ...${uncanonical.length - 10} more`);
+ }
+ console.error("check the head() function in vocs.config.tsx");
+ process.exit(1);
+ }
+
+ const xml = [
+ '',
+ '',
+ ...urls.map((u) => ` ${u} ",
+ "",
+ ].join("\n");
+
+ writeFileSync(join(DIST, "sitemap.xml"), xml);
+
+ const dropped = Object.entries(skipped)
+ .filter(([, n]) => n)
+ .map(([k, n]) => `${n} ${k}`)
+ .join(", ");
+ console.log(
+ `sitemap.xml: ${urls.length} urls${dropped ? ` (skipped ${dropped})` : ""}`,
+ );
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) main();
diff --git a/vocs.config.tsx b/vocs.config.tsx
index 7c0bc7e5..36341d77 100644
--- a/vocs.config.tsx
+++ b/vocs.config.tsx
@@ -1,4 +1,5 @@
-import { resolve } from "node:path";
+import { readFileSync, readdirSync } from "node:fs";
+import { join, resolve } from "node:path";
import { defineConfig } from "vocs";
import dotenv from "dotenv";
import { resolveRedirect } from "./resolve-redirect.js";
@@ -12,6 +13,65 @@ const componentsDir = resolve(process.cwd(), "docs/components");
dotenv.config();
+// Absolute, so the copy served on new-docs.zerodev.app credits this host
+// instead of competing with it. A path-only canonical would resolve against
+// whichever host served the page.
+const ORIGIN = "https://docs.zerodev.app";
+
+// /sdk/v5_3_x/x is the old version of /sdk/x, which already has a vetted
+// redirect target, so the old set credits the current pages without a
+// hand-written map. check:redirects fails if a page stops mapping.
+function canonicalPath(path: string) {
+ if (!path.startsWith("/sdk/v5_3_x")) return path;
+ const current = resolveRedirect(path.replace("/sdk/v5_3_x", "/sdk"));
+ // Off-site targets and the set's index have no equivalent: credit itself.
+ return current?.startsWith("/") ? current : path;
+}
+
+// @zerodev/waas, no release in about two years. Kept so old links resolve,
+// hidden so it stops competing with the current docs.
+const isUnmaintained = (path: string) =>
+ path.startsWith("/advanced/react-hooks/");
+
+const SITE_DESCRIPTION =
+ "Build a Web3 experience that feels like Web2, using account abstraction through ZeroDev. Say goodbye to gas, seed phrases, transaction prompts, and more.";
+
+// Stopgap. Vocs emits a description only where the page supplies one, and most
+// do not, so they ship bare. Collect the ones that already have their own so
+// the fallback never doubles up.
+const PAGES_DIR = resolve(process.cwd(), "docs/pages");
+
+// Either frontmatter `description:` or a bracketed suffix on the H1, as in
+// `# Social Login [Social login lets users...]`. The trailing-bracket test
+// excludes a markdown link, which is `[text](url)`.
+function hasDescription(src: string) {
+ const close = src.startsWith("---") ? src.indexOf("\n---", 3) : -1;
+ if (close > 0 && /^description:\s*\S/m.test(src.slice(3, close))) return true;
+ const h1 = src.match(/^#[^#\n].*$/m)?.[0];
+ return Boolean(h1 && /\[[^\]]+\]\s*$/.test(h1));
+}
+
+function routesWithDescription(dir = PAGES_DIR, prefix = "") {
+ const out = new Set();
+ for (const entry of readdirSync(dir, { withFileTypes: true })) {
+ const full = join(dir, entry.name);
+ if (entry.isDirectory()) {
+ for (const r of routesWithDescription(full, `${prefix}/${entry.name}`)) {
+ out.add(r);
+ }
+ continue;
+ }
+ if (!/\.mdx?$/.test(entry.name)) continue;
+ const src = readFileSync(full, "utf8");
+ if (!hasDescription(src)) continue;
+ const name = entry.name.replace(/\.mdx?$/, "");
+ out.add(name === "index" ? prefix || "/" : `${prefix}/${name}`);
+ }
+ return out;
+}
+
+const HAS_DESCRIPTION = routesWithDescription();
+
export default defineConfig({
iconUrl: "/favicon.ico",
logoUrl: {
@@ -85,20 +145,28 @@ export default defineConfig({
title: "ZeroDev",
titleTemplate: "%s – ZeroDev",
description: "The most powerful smart account.",
- head: (
- <>
-