Skip to content

armgit / dbx

Public Imported from GitHub
0

25 MB lightweight cross-platform database client for 100+ databases, including MySQL, PostgreSQL, SQLite, Redis, MongoDB, DuckDB, SQL Server, and Dameng. Built-in AI, MCP Server, CLI, desktop and Docker. | 轻量级跨平台数据库管理工具,支持 MySQL、PostgreSQL、SQLite、Redis、MongoDB、达梦等 100+ 数据库,提供桌面端、Docker、CLI、内置 AI 助手和 MCP。

feat(docs): improve search metadata and AI-readable documentation

t8y28ffdbb29508c
diff --git a/docs/app/[lang]/docs/[[...slug]]/page.tsx b/docs/app/[lang]/docs/[[...slug]]/page.tsx
index cb84c3e115..feca860ca1 100644
--- a/docs/app/[lang]/docs/[[...slug]]/page.tsx
+++ b/docs/app/[lang]/docs/[[...slug]]/page.tsx
@@ -11,7 +11,10 @@ import { ImageZoom } from "fumadocs-ui/components/image-zoom";
import { Accordion, Accordions } from "fumadocs-ui/components/accordion";
import type { MDXContent } from "mdx/types";
import type { TOCItemType } from "fumadocs-core/toc";
-import { buildMetadata, getHtmlLang, SITE_URL } from "@/lib/metadata";
+import { buildMetadata } from "@/lib/metadata";
+import { resolveLang } from "@/lib/i18n";
+import { markdownPath } from "@/lib/llms";
+import { buildDocStructuredData, serializeStructuredData } from "@/lib/structuredData";
export async function generateMetadata({ params }: { params: Promise<{ lang: string; slug?: string[] }> }): Promise<Metadata> {
const { lang, slug } = await params;
@@ -22,11 +25,12 @@ export async function generateMetadata({ params }: { params: Promise<{ lang: str
const description = (page.data.description as string) || undefined;
return buildMetadata({
- title,
+ title: `${title} · ${lang === "cn" ? "使用文档" : "Documentation"}`,
description: description ?? "",
- path: slug ? `/${lang}/docs/${slug.join("/")}` : `/${lang}/docs`,
+ path: slug?.length ? `/${lang}/docs/${slug.join("/")}` : `/${lang}/docs`,
lang,
ogType: "article",
+ markdownPath: markdownPath(slug?.length ? `/${lang}/docs/${slug.join("/")}` : `/${lang}/docs`),
});
}
@@ -56,42 +60,15 @@ export default async function Page({ params }: { params: Promise<{ lang: string;
const title = page.data.title as string;
const description = (page.data.description as string) || "";
- const docPath = slug ? `/${lang}/docs/${slug.join("/")}` : `/${lang}/docs`;
-
- const breadcrumbJsonLd = {
- "@context": "https://schema.org",
- "@type": "BreadcrumbList",
- itemListElement: [
- { "@type": "ListItem", position: 1, name: "Home", item: SITE_URL },
- { "@type": "ListItem", position: 2, name: "Docs", item: `${SITE_URL}/${lang}/docs` },
- ...(slug
- ? slug.map((segment, i) => ({
- "@type": "ListItem" as const,
- position: i + 3,
- name: segment.replace(/-/g, " ").replace(/\b\w/g, (c) => c.toUpperCase()),
- item: `${SITE_URL}/${lang}/docs/${slug.slice(0, i + 1).join("/")}`,
- }))
- : []),
- ],
- };
-
- const articleJsonLd = {
- "@context": "https://schema.org",
- "@type": "TechArticle",
- headline: title,
- description,
- inLanguage: getHtmlLang(lang),
- isPartOf: {
- "@type": "WebSite",
- url: SITE_URL,
- },
- };
+ const docPath = slug?.length ? `/${lang}/docs/${slug.join("/")}` : `/${lang}/docs`;
+ const structuredData = buildDocStructuredData(resolveLang(lang), title, description, docPath);
return (
<main className="contents">
<DocsPage toc={toc}>
- <script type="application/ld+json" dangerouslySetInnerHTML={{ __html: JSON.stringify(breadcrumbJsonLd) }} />
- <script type="application/ld+json" dangerouslySetInnerHTML={{ __html: JSON.stringify(articleJsonLd) }} />
+ {structuredData.map((entry) => (
+ <script key={entry["@id"]} type="application/ld+json" dangerouslySetInnerHTML={{ __html: serializeStructuredData(entry) }} />
+ ))}
<DocsTitle>{title}</DocsTitle>
<DocsBody>
<MDX components={mdxComponents} />
diff --git a/docs/app/[lang]/layout.tsx b/docs/app/[lang]/layout.tsx
index b4e0d82236..b538be5a52 100644
--- a/docs/app/[lang]/layout.tsx
+++ b/docs/app/[lang]/layout.tsx
@@ -3,7 +3,7 @@ import type { ReactNode } from "react";
import type { Metadata, Viewport } from "next";
import { RouteProgress } from "@/components/RouteProgress";
import { buildMetadata, DEFAULT_DESCRIPTION, getHtmlLang, SITE_NAME, SITE_URL } from "@/lib/metadata";
-import { buildSiteStructuredData } from "@/lib/structuredData";
+import { buildSiteStructuredData, serializeStructuredData } from "@/lib/structuredData";
import { i18n, resolveLang } from "@/lib/i18n";
const LOCALE_MAP: Record<string, { locale: string; title: string; description: string }> = {
@@ -15,7 +15,7 @@ const LOCALE_MAP: Record<string, { locale: string; title: string; description: s
cn: {
locale: "zh_CN",
title: "DBX - 25MB,管理90+种数据库",
- description: "90+ 种数据库,仅 25 MB。支持桌面与 Docker 自托管,内置 AI 助手。",
+ description: "DBX 是免费开源的数据库管理工具,支持 MySQL、PostgreSQL、SQLite、Redis 等 90+ 种数据系统,提供 SQL 编辑、AI 助手、MCP 与 Docker 自托管。",
},
};
@@ -43,7 +43,6 @@ export async function generateMetadata({ params }: { params: Promise<{ lang: str
shortcut: "/favicon-64.png",
apple: "/logo.png",
},
- robots: { index: true, follow: true },
openGraph: { ...pageMetadata.openGraph, locale: meta.locale },
};
}
@@ -71,7 +70,7 @@ export default async function LangLayout({ params, children }: { params: Promise
data-domains="dbxio.com,www.dbxio.com"
/>
{siteStructuredData.map((structuredData) => (
- <script key={structuredData["@id"]} type="application/ld+json" dangerouslySetInnerHTML={{ __html: JSON.stringify(structuredData) }} />
+ <script key={structuredData["@id"]} type="application/ld+json" dangerouslySetInnerHTML={{ __html: serializeStructuredData(structuredData) }} />
))}
</head>
<body className="flex min-h-screen flex-col">
diff --git a/docs/app/[lang]/markdown/[...slug]/route.ts b/docs/app/[lang]/markdown/[...slug]/route.ts
new file mode 100644
index 0000000000..ade8347232
--- /dev/null
+++ b/docs/app/[lang]/markdown/[...slug]/route.ts
@@ -0,0 +1,21 @@
+import { source } from "@/lib/source";
+import { documentMarkdown } from "@/lib/llms";
+
+export const dynamic = "force-static";
+
+export async function GET(_request: Request, { params }: { params: Promise<{ lang: string; slug: string[] }> }) {
+ const { lang, slug } = await params;
+ const documentSlug = slug.join("/").replace(/\.md$/, "");
+ const page = source.getPage(documentSlug === "index" ? [] : documentSlug.split("/"), lang);
+ if (!page) return new Response("Not found", { status: 404 });
+ return new Response(await documentMarkdown(page), {
+ headers: { "Content-Type": "text/markdown; charset=utf-8" },
+ });
+}
+
+export function generateStaticParams() {
+ return source.generateParams().map(({ lang, slug }) => ({
+ lang,
+ slug: `${slug.length ? slug.join("/") : "index"}.md`.split("/"),
+ }));
+}
diff --git a/docs/app/[lang]/page.tsx b/docs/app/[lang]/page.tsx
index 5c0ff173af..adaf3d31e9 100644
--- a/docs/app/[lang]/page.tsx
+++ b/docs/app/[lang]/page.tsx
@@ -17,7 +17,7 @@ import { contributorsFromActivity } from "@/lib/contributors";
import { getAppVersion } from "@/lib/appVersion";
import { fetchLatestReleaseInfo } from "@/lib/latestRelease";
import { buildMetadata, getHtmlLang } from "@/lib/metadata";
-import { buildSoftwareApplicationStructuredData } from "@/lib/structuredData";
+import { buildSoftwareApplicationStructuredData, serializeStructuredData } from "@/lib/structuredData";
import { ArrowRight, Bot, Database, FileCode, GitCompare, Network, Search, Shield, Table, Terminal, Zap } from "lucide-react";
import { resolveLang, type DocsLang } from "@/lib/i18n";
@@ -448,11 +448,11 @@ const i18nText = {
const landingMeta = {
en: {
title: "DBX - 25 MB to manage 90+ databases!",
- description: "DBX brings connections, SQL editing, data grids, schema tools, AI assistance, and self-hosted access into one lightweight product.",
+ description: "Manage MySQL, PostgreSQL, SQLite, Redis and 90+ data systems with DBX, a free open-source database client. Desktop, Docker self-hosting, optional AI and MCP.",
},
cn: {
title: "DBX - 25MB,管理90+种数据库!",
- description: "DBX 将连接管理、SQL 编辑、数据表格、结构工具、AI 助手和自托管访问放进一个轻量产品里。",
+ description: "DBX 是免费开源的数据库管理工具,支持 MySQL、PostgreSQL、SQLite、Redis 等 90+ 种数据系统,提供 SQL 编辑、可选 AI 助手、MCP 和 Docker 自托管,覆盖 Windows、macOS 与 Linux。",
},
};
@@ -564,7 +564,7 @@ export default async function LandingPage({ params }: { params: Promise<{ lang:
return (
<main className="landing" lang={getHtmlLang(l)}>
- <script type="application/ld+json" dangerouslySetInnerHTML={{ __html: JSON.stringify(softwareStructuredData) }} />
+ <script type="application/ld+json" dangerouslySetInnerHTML={{ __html: serializeStructuredData(softwareStructuredData) }} />
{/* 漫游星空背景层:铺满整个深色着陆页,克制不抢焦点 */}
<Starfield />
{/* Nav */}
diff --git a/docs/app/llms-full.txt/route.ts b/docs/app/llms-full.txt/route.ts
new file mode 100644
index 0000000000..ffa399c88c
--- /dev/null
+++ b/docs/app/llms-full.txt/route.ts
@@ -0,0 +1,10 @@
+import { source } from "@/lib/source";
+import { documentMarkdown } from "@/lib/llms";
+
+export const dynamic = "force-static";
+
+export async function GET() {
+ const pages = [...source.getPages()].sort((left, right) => left.url.localeCompare(right.url, "en"));
+ const documents = await Promise.all(pages.map(documentMarkdown));
+ return new Response(documents.join("\n---\n\n"), { headers: { "Content-Type": "text/plain; charset=utf-8" } });
+}
diff --git a/docs/app/llms.txt/route.ts b/docs/app/llms.txt/route.ts
new file mode 100644
index 0000000000..2f6f3acbb4
--- /dev/null
+++ b/docs/app/llms.txt/route.ts
@@ -0,0 +1,8 @@
+import { source } from "@/lib/source";
+import { llmsIndex } from "@/lib/llms";
+
+export const dynamic = "force-static";
+
+export function GET() {
+ return new Response(llmsIndex(source.getPages()), { headers: { "Content-Type": "text/plain; charset=utf-8" } });
+}
diff --git a/docs/lib/llms.test.ts b/docs/lib/llms.test.ts
new file mode 100644
index 0000000000..3da522f708
--- /dev/null
+++ b/docs/lib/llms.test.ts
@@ -0,0 +1,29 @@
+import assert from "node:assert/strict";
+import { test } from "vitest";
+import { documentMarkdown, llmsIndex, markdownPath } from "./llms";
+
+test("Markdown endpoints preserve locale and normalize documentation roots", () => {
+ assert.equal(markdownPath("/cn/docs/"), "/cn/markdown/index.md");
+ assert.equal(markdownPath("/en/docs/mcp"), "/en/markdown/mcp.md");
+});
+
+test("document text preserves exact source provenance and code blocks", async () => {
+ const body = "## Example\n\n```sql\nSELECT 1;\n```";
+ const output = await documentMarkdown({ url: "/cn/docs/mcp", data: { title: "MCP 集成", description: "受控访问", getText: async () => body } });
+ assert.ok(output.startsWith("# MCP 集成\n"));
+ assert.ok(output.includes("Source: https://dbxio.com/cn/docs/mcp\n"));
+ assert.ok(output.includes("Language: zh-CN"));
+ assert.ok(output.includes(body));
+});
+
+test("LLM index contains both languages without mutating page order", () => {
+ const pages = [
+ { url: "/en/docs/mcp", data: { title: "MCP", description: "Tools", getText: async () => "" } },
+ { url: "/cn/docs/mcp", data: { title: "MCP 集成", description: "工具", getText: async () => "" } },
+ ];
+ const output = llmsIndex(pages);
+ assert.ok(output.includes("https://dbxio.com/en/markdown/mcp.md"));
+ assert.ok(output.includes("https://dbxio.com/cn/markdown/mcp.md"));
+ assert.ok(output.includes("Apache-2.0"));
+ assert.equal(pages[0].url, "/en/docs/mcp");
+});
diff --git a/docs/lib/llms.ts b/docs/lib/llms.ts
new file mode 100644
index 0000000000..9755e2f69e
--- /dev/null
+++ b/docs/lib/llms.ts
@@ -0,0 +1,40 @@
+import { DEFAULT_DESCRIPTION, getHtmlLang, SITE_URL } from "./metadata";
+
+export interface LlmPage {
+ url: string;
+ data: { title: string; description?: string; getText: (format: "processed") => Promise<string> };
+}
+
+export function markdownPath(url: string): string {
+ const normalized = url.replace(/\/+$/, "");
+ return normalized.replace(/^(\/(?:en|cn))\/docs(?=\/|$)/, "$1/markdown") + (/^\/(en|cn)\/docs$/.test(normalized) ? "/index.md" : ".md");
+}
+
+export async function documentMarkdown(page: LlmPage): Promise<string> {
+ const language = getHtmlLang(page.url.split("/")[1]);
+ return (
+ [`# ${page.data.title}`, page.data.description ? `> ${page.data.description}` : "", `Source: ${SITE_URL}${page.url.replace(/\/+$/, "")}`, `Language: ${language}`, `Relative links resolve against ${SITE_URL}${page.url.replace(/\/+$/, "")}.`, await page.data.getText("processed")]
+ .filter(Boolean)
+ .join("\n\n") + "\n"
+ );
+}
+
+export function llmsIndex(pages: LlmPage[]): string {
+ const sortedPages = [...pages].sort((left, right) => left.url.localeCompare(right.url, "en"));
+ return (
+ [
+ "# DBX",
+ `> ${DEFAULT_DESCRIPTION}`,
+ "DBX is an Apache-2.0 database client, not a database server. The desktop app is approximately 25 MB; optional drivers, JRE packages, and plugins add downloads. Database capabilities vary by driver and engine.",
+ "The built-in AI assistant uses the provider you configure. MCP exposes selected DBX connections under access policies. Do not assume all features work with every database or that AI requests stay on the device.",
+ "## Official sources",
+ `- [English website](${SITE_URL}/en)`,
+ `- [中文官网](${SITE_URL}/cn)`,
+ "- [Source code and license](https://github.com/t8y2/dbx)",
+ `- [Release notes](${SITE_URL}/en/changelog): verify versions and downloads here rather than treating this file as live release metadata.`,
+ `- [Supported databases](${SITE_URL}/en/databases)`,
+ `- [Complete documentation text](${SITE_URL}/llms-full.txt): both languages, with source URLs for each document.`,
+ ...["en", "cn"].flatMap((lang) => [lang === "en" ? "## English documentation" : "## 中文文档", ...sortedPages.filter((page) => page.url.startsWith(`/${lang}/`)).map((page) => `- [${page.data.title}](${SITE_URL}${markdownPath(page.url)}): ${page.data.description ?? ""}`)]),
+ ].join("\n\n") + "\n"
+ );
+}
diff --git a/docs/lib/metadata.test.ts b/docs/lib/metadata.test.ts
new file mode 100644
index 0000000000..8fe0aceb09
--- /dev/null
+++ b/docs/lib/metadata.test.ts
@@ -0,0 +1,28 @@
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { test } from "vitest";
+import { buildMetadata, DEFAULT_OG_IMAGE } from "./metadata";
+
+test("metadata normalizes canonicals and uses matching BCP 47 alternates", () => {
+ const metadata = buildMetadata({ title: "文档", description: "说明", path: "/cn/docs/?ref=test#intro", lang: "cn", markdownPath: "/cn/markdown/index.md" });
+ assert.equal(metadata.alternates?.canonical, "https://dbxio.com/cn/docs");
+ assert.deepEqual(metadata.alternates?.languages, { en: "https://dbxio.com/en/docs", "zh-CN": "https://dbxio.com/cn/docs", "x-default": "https://dbxio.com/en/docs" });
+ assert.deepEqual(metadata.alternates?.types, { "text/markdown": "https://dbxio.com/cn/markdown/index.md" });
+ assert.equal(metadata.openGraph?.url, metadata.alternates?.canonical);
+});
+
+test("locale replacement respects complete route segments", () => {
+ const metadata = buildMetadata({ title: "English", description: "Description", path: "/english", lang: "en" });
+ assert.equal(metadata.alternates?.languages?.["zh-CN"], "https://dbxio.com/english");
+});
+
+test("default social cards reuse the same artwork as both README headers", () => {
+ for (const file of ["README.md", "README.zh-CN.md"]) {
+ const readme = readFileSync(new URL(`../../${file}`, import.meta.url), "utf8");
+ assert.equal(readme.match(/<img\s+src="([^"]+)"/)?.[1], DEFAULT_OG_IMAGE);
+ }
+
+ const metadata = buildMetadata({ title: "DBX", description: "Database client", path: "/en", lang: "en" });
+ assert.deepEqual(metadata.openGraph?.images, [{ url: DEFAULT_OG_IMAGE, width: 1792, height: 896 }]);
+ assert.deepEqual(metadata.twitter?.images, [DEFAULT_OG_IMAGE]);
+});
diff --git a/docs/lib/metadata.ts b/docs/lib/metadata.ts
index 0896e20291..4274a2302a 100644
--- a/docs/lib/metadata.ts
+++ b/docs/lib/metadata.ts
@@ -2,8 +2,8 @@ import type { Metadata } from "next";
export const SITE_URL = "https://dbxio.com";
export const SITE_NAME = "DBX";
-export const DEFAULT_DESCRIPTION = "90+ databases in 25 MB. Desktop & Docker self-hosting, with built-in AI assistant.";
-export const DEFAULT_OG_IMAGE = "/logo.png";
+export const DEFAULT_DESCRIPTION = "DBX is a free, open-source database client for MySQL, PostgreSQL, SQLite, Redis and 90+ data systems, with SQL editing, AI assistance and Docker self-hosting.";
+export const DEFAULT_OG_IMAGE = "https://dl.dbxio.com/assets/readme-hero-20260820.png";
const LOCALE_MAP: Record<string, string> = {
en: "en_US",
@@ -20,7 +20,7 @@ export function getHtmlLang(lang: string): string {
}
function swapLang(path: string, to: string): string {
- return path.replace(/^\/(en|cn)/, `/${to}`);
+ return path.replace(/^\/(en|cn)(?=\/|$)/, `/${to}`);
}
interface BuildMetadataParams {
@@ -31,24 +31,15 @@ interface BuildMetadataParams {
ogType?: "website" | "article";
images?: string[];
lastModified?: Date;
+ markdownPath?: string;
}
-export function buildMetadata({
- title,
- description,
- path,
- lang,
- ogType = "website",
- images,
- lastModified,
-}: BuildMetadataParams): Metadata {
- const canonical = `${SITE_URL}${path}`;
+export function buildMetadata({ title, description, path, lang, ogType = "website", images, lastModified, markdownPath }: BuildMetadataParams): Metadata {
+ const normalizedPath = path.split(/[?#]/)[0].replace(/\/+$/, "") || "/";
+ const canonical = `${SITE_URL}${normalizedPath}`;
const locale = LOCALE_MAP[lang] ?? "en_US";
- const ogImages = images?.map((url) => ({
- url,
- width: url === DEFAULT_OG_IMAGE ? 512 : 1200,
- height: url === DEFAULT_OG_IMAGE ? 512 : 630,
- })) ?? [{ url: DEFAULT_OG_IMAGE, width: 512, height: 512 }];
+ const defaultImage = { url: DEFAULT_OG_IMAGE, width: 1792, height: 896 };
+ const ogImages = images?.map((url) => (url === DEFAULT_OG_IMAGE ? defaultImage : { url })) ?? [defaultImage];
const base: Metadata = {
title,
@@ -56,10 +47,16 @@ export function buildMetadata({
alternates: {
canonical,
languages: {
- en: `${SITE_URL}${swapLang(path, "en")}`,
- zh: `${SITE_URL}${swapLang(path, "cn")}`,
- "x-default": `${SITE_URL}${swapLang(path, "en")}`,
+ en: `${SITE_URL}${swapLang(normalizedPath, "en")}`,
+ "zh-CN": `${SITE_URL}${swapLang(normalizedPath, "cn")}`,
+ "x-default": `${SITE_URL}${swapLang(normalizedPath, "en")}`,
},
+ ...(markdownPath ? { types: { "text/markdown": `${SITE_URL}${markdownPath}` } } : {}),
+ },
+ robots: {
+ index: true,
+ follow: true,
+ googleBot: { index: true, follow: true, "max-image-preview": "large", "max-snippet": -1, "max-video-preview": -1 },
},
openGraph: {
title,
@@ -68,6 +65,7 @@ export function buildMetadata({
siteName: SITE_NAME,
type: ogType,
locale,
+ alternateLocale: Object.values(LOCALE_MAP).filter((alternate) => alternate !== locale),
images: ogImages,
},
twitter: {
diff --git a/docs/lib/structuredData.test.ts b/docs/lib/structuredData.test.ts
index 4debc309fc..666e004915 100644
--- a/docs/lib/structuredData.test.ts
+++ b/docs/lib/structuredData.test.ts
@@ -1,7 +1,7 @@
import assert from "node:assert/strict";
import { test } from "vitest";
-import { buildSiteStructuredData, buildSoftwareApplicationStructuredData } from "./structuredData";
+import { buildDocStructuredData, buildSiteStructuredData, buildSoftwareApplicationStructuredData, serializeStructuredData } from "./structuredData";
test("site structured data does not advertise a nonexistent search route", () => {
const [website, organization] = buildSiteStructuredData();
@@ -18,8 +18,24 @@ test("software structured data stays localized and versioned", () => {
assert.equal(english.applicationCategory, "DeveloperApplication");
assert.equal(english.softwareVersion, "0.5.71");
assert.equal(english.inLanguage, "en");
- assert.match(english.description, /90\+ databases/);
+ assert.match(english.description, /90\+ data systems/);
assert.equal(chinese.inLanguage, "zh-CN");
- assert.match(chinese.description, /90\+ 种数据库/);
+ assert.match(chinese.description, /90\+ 种数据系统/);
assert.equal(chinese.license, "https://github.com/t8y2/dbx/blob/main/LICENSE");
});
+
+test("documentation breadcrumbs use localized titles and real documentation roots", () => {
+ const [breadcrumb, article] = buildDocStructuredData("cn", "快速开始", "连接数据库", "/cn/docs/getting-started");
+ assert.equal(breadcrumb.itemListElement?.[0].name, "首页");
+ assert.equal(breadcrumb.itemListElement?.[1].item, "https://dbxio.com/cn/docs/what-is-dbx");
+ assert.equal(breadcrumb.itemListElement?.[2].name, "快速开始");
+ assert.equal(article.mainEntityOfPage, "https://dbxio.com/cn/docs/getting-started");
+ assert.equal(buildDocStructuredData("en", "Docs", "Documentation", "/en/docs/what-is-dbx")[0].itemListElement?.length, 2);
+});
+
+test("JSON-LD cannot break out of its script element", () => {
+ const value = { headline: '</script><script>alert("injected")</script>' };
+ const serialized = serializeStructuredData(value);
+ assert.equal(serialized.includes("<"), false);
+ assert.deepEqual(JSON.parse(serialized), value);
+});
diff --git a/docs/lib/structuredData.ts b/docs/lib/structuredData.ts
index bfd3fe778a..92626bcf13 100644
--- a/docs/lib/structuredData.ts
+++ b/docs/lib/structuredData.ts
@@ -3,7 +3,7 @@ import type { DocsLang } from "./i18n";
const localizedDescription = {
en: DEFAULT_DESCRIPTION,
- cn: "90+ 种数据库,仅 25 MB。支持桌面端、Docker 自托管、AI 助手与 MCP Server。",
+ cn: "DBX 是免费开源的数据库管理工具,支持 MySQL、PostgreSQL、SQLite、Redis 等 90+ 种数据系统,提供 SQL 编辑、AI 助手与 Docker 自托管。",
} as const;
const localizedFeatureList = {
@@ -15,14 +15,7 @@ const localizedFeatureList = {
"MCP Server integration for AI coding agents",
"Schema browsing, schema diff, data editing, import, and export",
],
- cn: [
- "统一管理 90+ 种 SQL、NoSQL、向量、时序、嵌入式数据库与消息队列",
- "提供 Windows、macOS 与 Linux 桌面端",
- "支持 Docker 自托管与浏览器访问",
- "支持 AI 生成、解释、优化与修复 SQL",
- "通过 MCP Server 连接 AI 编程智能体",
- "提供结构浏览、结构对比、数据编辑、导入与导出",
- ],
+ cn: ["统一管理 90+ 种 SQL、NoSQL、向量、时序、嵌入式数据库与消息队列", "提供 Windows、macOS 与 Linux 桌面端", "支持 Docker 自托管与浏览器访问", "支持 AI 生成、解释、优化与修复 SQL", "通过 MCP Server 连接 AI 编程智能体", "提供结构浏览、结构对比、数据编辑、导入与导出"],
} as const;
export function buildSiteStructuredData() {
@@ -45,16 +38,44 @@ export function buildSiteStructuredData() {
url: SITE_URL,
description: DEFAULT_DESCRIPTION,
logo: `${SITE_URL}/logo.png`,
- sameAs: [
- "https://github.com/t8y2/dbx",
- "https://www.npmjs.com/package/@dbx-app/mcp-server",
- "https://cnb.cool/dbxio.com/dbx",
- "https://atomgit.com/t8y2/dbx",
- ],
+ sameAs: ["https://github.com/t8y2/dbx", "https://www.npmjs.com/package/@dbx-app/mcp-server", "https://cnb.cool/dbxio.com/dbx", "https://atomgit.com/t8y2/dbx"],
},
] as const;
}
+export function serializeStructuredData(value: unknown): string {
+ return JSON.stringify(value).replace(/</g, "\\u003c");
+}
+
+export function buildDocStructuredData(lang: DocsLang, title: string, description: string, path: string) {
+ const url = `${SITE_URL}${path}`;
+ const docsUrl = `${SITE_URL}/${lang}/docs/what-is-dbx`;
+ const labels = lang === "cn" ? ["首页", "文档"] : ["Home", "Documentation"];
+
+ return [
+ {
+ "@context": "https://schema.org",
+ "@type": "BreadcrumbList",
+ "@id": `${url}#breadcrumb`,
+ itemListElement: [{ "@type": "ListItem", position: 1, name: labels[0], item: `${SITE_URL}/${lang}` }, { "@type": "ListItem", position: 2, name: labels[1], item: docsUrl }, ...(url === docsUrl ? [] : [{ "@type": "ListItem", position: 3, name: title, item: url }])],
+ },
+ {
+ "@context": "https://schema.org",
+ "@type": "TechArticle",
+ "@id": `${url}#article`,
+ url,
+ mainEntityOfPage: url,
+ headline: title,
+ description,
+ inLanguage: getHtmlLang(lang),
+ isPartOf: { "@id": `${SITE_URL}/#website` },
+ about: { "@id": `${SITE_URL}/#software` },
+ author: { "@id": `${SITE_URL}/#organization` },
+ publisher: { "@id": `${SITE_URL}/#organization` },
+ },
+ ];
+}
+
export function buildSoftwareApplicationStructuredData(lang: DocsLang, version: string) {
const language = getHtmlLang(lang);
@@ -75,11 +96,7 @@ export function buildSoftwareApplicationStructuredData(lang: DocsLang, version:
downloadUrl: "https://github.com/t8y2/dbx/releases/latest",
releaseNotes: `${SITE_URL}/${lang}/changelog`,
license: "https://github.com/t8y2/dbx/blob/main/LICENSE",
- screenshot: [
- `${SITE_URL}/screenshot-dark.png`,
- `${SITE_URL}/screenshot-er.png`,
- `${SITE_URL}/screenshot-grid.png`,
- ],
+ screenshot: [`${SITE_URL}/screenshot-dark.png`, `${SITE_URL}/screenshot-er.png`, `${SITE_URL}/screenshot-grid.png`],
featureList: [...localizedFeatureList[lang]],
offers: {
"@type": "Offer",
@@ -89,9 +106,6 @@ export function buildSoftwareApplicationStructuredData(lang: DocsLang, version:
},
author: { "@id": `${SITE_URL}/#organization` },
publisher: { "@id": `${SITE_URL}/#organization` },
- sameAs: [
- "https://github.com/t8y2/dbx",
- "https://www.npmjs.com/package/@dbx-app/mcp-server",
- ],
+ sameAs: ["https://github.com/t8y2/dbx", "https://www.npmjs.com/package/@dbx-app/mcp-server"],
} as const;
}
diff --git a/docs/package.json b/docs/package.json
index 219b67bf4b..d55e72fdac 100644
--- a/docs/package.json
+++ b/docs/package.json
@@ -6,9 +6,11 @@
"dev": "next dev",
"preview": "node scripts/preview-server.mjs",
"content:check": "node scripts/verify-doc-content.mjs",
- "prebuild": "node scripts/verify-doc-content.mjs",
+ "seo:test": "node --test scripts/seo.test.mjs",
+ "seo:check": "node scripts/verify-seo.mjs",
+ "prebuild": "pnpm seo:test && node scripts/verify-doc-content.mjs",
"build": "next build",
- "postbuild": "node scripts/generate-sitemap.mjs && node scripts/verify-static-export.mjs",
+ "postbuild": "node scripts/generate-sitemap.mjs && node scripts/verify-static-export.mjs && node scripts/verify-seo.mjs",
"contributors:update": "node scripts/update-contributors.mjs",
"start": "next start",
"postinstall": "fumadocs-mdx"
diff --git a/docs/public/_headers b/docs/public/_headers
new file mode 100644
index 0000000000..b98951858d
--- /dev/null
+++ b/docs/public/_headers
@@ -0,0 +1,12 @@
+/en/markdown/*
+ Content-Type: text/markdown; charset=utf-8
+ X-Robots-Tag: noindex
+/cn/markdown/*
+ Content-Type: text/markdown; charset=utf-8
+ X-Robots-Tag: noindex
+/llms.txt
+ Content-Type: text/plain; charset=utf-8
+ X-Robots-Tag: noindex
+/llms-full.txt
+ Content-Type: text/plain; charset=utf-8
+ X-Robots-Tag: noindex
diff --git a/docs/public/_redirects b/docs/public/_redirects
new file mode 100644
index 0000000000..4aac09ebe2
--- /dev/null
+++ b/docs/public/_redirects
@@ -0,0 +1,5 @@
+/ /cn 301
+/en/docs /en/docs/what-is-dbx 301
+/en/docs/ /en/docs/what-is-dbx 301
+/cn/docs /cn/docs/what-is-dbx 301
+/cn/docs/ /cn/docs/what-is-dbx 301
diff --git a/docs/public/llms.txt b/docs/public/llms.txt
deleted file mode 100644
index e6e11824f9..0000000000
--- a/docs/public/llms.txt
+++ /dev/null
@@ -1,50 +0,0 @@
-# DBX
-
-> DBX is an open-source database workspace that manages 90+ databases in a roughly 25 MB desktop application. It also supports Docker self-hosting, an AI SQL assistant, a CLI, and an MCP Server for AI coding agents.
-
-Canonical website: https://dbxio.com
-Source repository: https://github.com/t8y2/dbx
-License: Apache-2.0
-
-## Product facts
-
-- Platforms: Windows, macOS (Apple Silicon and Intel), Linux, and Docker self-hosting.
-- Database coverage: 90+ SQL, NoSQL, vector, time-series, embedded databases, compatible engines, and message queues.
-- Representative databases: MySQL, PostgreSQL, SQLite, Redis, MongoDB, DuckDB, ClickHouse, SQL Server, Oracle, MariaDB, Doris, Dameng, GaussDB, Kafka, and RabbitMQ.
-- Main workflows: connection management, SQL editing, data browsing and editing, schema browsing, schema diff, import/export, SSH tunnels, and query history.
-- AI workflows: generate, explain, optimize, and repair SQL with user-configured model providers.
-- Agent integration: the DBX MCP Server exposes approved database connections to compatible AI coding agents.
-- Distribution: desktop releases, Docker deployment, npm packages for CLI and MCP Server, and offline JDBC driver downloads.
-
-## Install and deploy
-
-- Desktop releases: https://github.com/t8y2/dbx/releases/latest
-- Getting started: https://dbxio.com/en/docs/getting-started
-- Docker deployment: https://dbxio.com/en/docs/1panel
-- CLI: https://dbxio.com/en/docs/cli
-- MCP Server: https://dbxio.com/en/docs/mcp
-- Offline drivers: https://dbxio.com/en/drivers
-
-## Documentation
-
-- Product overview: https://dbxio.com/en/docs/what-is-dbx
-- Supported databases: https://dbxio.com/en/databases
-- Query editor: https://dbxio.com/en/docs/query-editor
-- Data grid: https://dbxio.com/en/docs/data-grid
-- Schema browser: https://dbxio.com/en/docs/schema-browser
-- Schema diff: https://dbxio.com/en/docs/schema-diff
-- AI assistant: https://dbxio.com/en/docs/ai-assistant
-- Web API: https://dbxio.com/en/docs/web-api
-- Changelog: https://dbxio.com/en/changelog
-- Community: https://dbxio.com/en/community
-
-## Chinese resources
-
-- 中文首页: https://dbxio.com/cn
-- 中文文档: https://dbxio.com/cn/docs/what-is-dbx
-- 中文数据库列表: https://dbxio.com/cn/databases
-- 中文更新日志: https://dbxio.com/cn/changelog
-
-## Attribution guidance
-
-Use DBX as the product name and link to https://dbxio.com or https://github.com/t8y2/dbx. Treat release versions, supported database counts, contributor counts, and download links as dynamic; verify them from the canonical website or repository before making time-sensitive claims.
diff --git a/docs/public/robots.txt b/docs/public/robots.txt
index 89add4345a..999be0fb96 100644
--- a/docs/public/robots.txt
+++ b/docs/public/robots.txt
@@ -1,7 +1,20 @@
User-agent: *
Allow: /
-# AI crawlers — explicitly allowed
+# Search and user-requested retrieval
+User-agent: OAI-SearchBot
+Allow: /
+
+User-agent: Claude-SearchBot
+Allow: /
+
+User-agent: Claude-User
+Allow: /
+
+User-agent: Perplexity-User
+Allow: /
+
+# Existing crawler and training permissions are preserved.
User-agent: GPTBot
Allow: /
diff --git a/docs/scripts/generate-sitemap.mjs b/docs/scripts/generate-sitemap.mjs
index 63b2aab0a0..3074a7a614 100644
--- a/docs/scripts/generate-sitemap.mjs
+++ b/docs/scripts/generate-sitemap.mjs
@@ -1,100 +1,8 @@
-import { readdirSync, writeFileSync } from "fs";
-import { resolve, relative } from "path";
-import { DEFAULT_LANGUAGE, LANGUAGES } from "./languages.mjs";
-
-const OUT_DIR = resolve(import.meta.dirname, "../out");
-const SITE_URL = "https://dbxio.com";
-const EXCLUDE = new Set(["index.html", "404.html", "_not-found.html"]);
-const EXCLUDE_PATHS = new Set([
- ...LANGUAGES.map((language) => `/${language}/issue`),
- // noindex shell served by the worker for plugin ids missing from the build snapshot.
- ...LANGUAGES.map((language) => `/${language}/plugins/detail`),
-]);
-// hreflang codes differ from the route segment for locales whose segment is not
-// already a language code.
-const HREFLANG = { en: "en", cn: "zh" };
-
-function* walkDir(dir) {
- const entries = readdirSync(dir, { withFileTypes: true });
- for (const entry of entries) {
- const fullPath = resolve(dir, entry.name);
- if (entry.isDirectory()) {
- yield* walkDir(fullPath);
- } else if (entry.isFile() && entry.name.endsWith(".html")) {
- yield fullPath;
- }
- }
-}
-
-function pathToUrl(filePath) {
- const rel = relative(OUT_DIR, filePath);
- return "/" + rel.replace(/\.html$/, "").replace(/\\/g, "/");
-}
-
-const htmlFiles = [...walkDir(OUT_DIR)].filter((f) => {
- const basename = f.split("/").pop() ?? "";
- return !EXCLUDE.has(basename) && !EXCLUDE_PATHS.has(pathToUrl(f));
-});
-
-function emptyLanguageMap() {
- return Object.fromEntries(LANGUAGES.map((language) => [language, null]));
-}
-
-const pagesByPath = new Map();
-
-for (const file of htmlFiles) {
- const url = pathToUrl(file);
- const match = url.match(new RegExp(`^/(${LANGUAGES.join("|")})(/.*)?$`));
- if (!match) {
- pagesByPath.set(url, emptyLanguageMap());
- continue;
- }
- const relativePath = match[2] || "/";
- if (!pagesByPath.has(relativePath)) {
- pagesByPath.set(relativePath, emptyLanguageMap());
- }
- const entry = pagesByPath.get(relativePath);
- entry[match[1]] = url;
- pagesByPath.set(relativePath, entry);
-}
-
-const urls = [];
-const seen = new Set();
-
-for (const [, langs] of pagesByPath) {
- const localizedPages = LANGUAGES.map((language) => langs[language]).filter(Boolean);
- if (localizedPages.length === 0) continue;
-
- const altLinks = LANGUAGES.filter((language) => langs[language]).map((language) => ({
- lang: HREFLANG[language] ?? language,
- href: `${SITE_URL}${langs[language]}`,
- }));
-
- if (altLinks.length > 1 && langs[DEFAULT_LANGUAGE]) {
- altLinks.push({ lang: "x-default", href: `${SITE_URL}${langs[DEFAULT_LANGUAGE]}` });
- }
-
- for (const localizedPage of localizedPages) {
- if (seen.has(localizedPage)) continue;
- seen.add(localizedPage);
- urls.push({ loc: `${SITE_URL}${localizedPage}`, altLinks });
- }
-}
-
-const sitemapXml = `<?xml version="1.0" encoding="UTF-8"?>
-<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"
- xmlns:xhtml="http://www.w3.org/1999/xhtml">
-${urls
- .map(
- (entry) =>
- ` <url>
- <loc>${entry.loc}</loc>
-${entry.altLinks.map((alt) => ` <xhtml:link rel="alternate" hreflang="${alt.lang}" href="${alt.href}" />`).join("\n")}
- </url>`,
- )
- .join("\n")}
-</urlset>
-`;
-
-writeFileSync(resolve(OUT_DIR, "sitemap.xml"), sitemapXml);
-console.log(`sitemap.xml generated with ${urls.length} URLs`);
+import { writeFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { generateSitemap, readHtmlPages } from "./seo.mjs";
+
+const outputDirectory = resolve(import.meta.dirname, "../out");
+const pages = await readHtmlPages(outputDirectory);
+await writeFile(resolve(outputDirectory, "sitemap.xml"), generateSitemap(pages));
+console.log(`sitemap.xml generated with ${pages.filter((page) => page.indexable).length} canonical URLs.`);
diff --git a/docs/scripts/seo.mjs b/docs/scripts/seo.mjs
new file mode 100644
index 0000000000..d158ecd2d5
--- /dev/null
+++ b/docs/scripts/seo.mjs
@@ -0,0 +1,123 @@
+import { readdir, readFile } from "node:fs/promises";
+import { join, relative } from "node:path";
+import { LANGUAGES } from "./languages.mjs";
+
+export const SITE_URL = "https://dbxio.com";
+
+export function decodeHtml(value) {
+ return value.replace(/&(?:amp|quot|apos|lt|gt|#39|#x[\da-f]+|#\d+);/gi, (entity) => {
+ const named = { "&amp;": "&", "&quot;": '"', "&apos;": "'", "&lt;": "<", "&gt;": ">", "&#39;": "'" };
+ const normalized = entity.toLowerCase();
+ if (named[normalized]) return named[normalized];
+ const codePoint = normalized.startsWith("&#x") ? parseInt(normalized.slice(3), 16) : parseInt(normalized.slice(2), 10);
+ return Number.isInteger(codePoint) && codePoint > 0 && codePoint <= 0x10ffff && !(codePoint >= 0xd800 && codePoint <= 0xdfff) ? String.fromCodePoint(codePoint) : "\uFFFD";
+ });
+}
+
+export function attributes(tag) {
+ return Object.fromEntries([...tag.matchAll(/([\w:-]+)\s*=\s*(?:"([^"]*)"|'([^']*)')/g)].map((match) => [match[1].toLowerCase(), decodeHtml(match[2] ?? match[3])]));
+}
+
+export function parseHtml(html) {
+ const head = html.match(/<head\b[^>]*>([\s\S]*?)<\/head>/i)?.[1] ?? "";
+ const metas = [...head.matchAll(/<meta\b[^>]*>/gi)].map((match) => attributes(match[0]));
+ const links = [...head.matchAll(/<link\b[^>]*>/gi)].map((match) => attributes(match[0]));
+ const namedMeta = (name) => metas.filter((meta) => meta.name === name || meta.property === name);
+ const robots = [...namedMeta("robots"), ...namedMeta("googlebot")].map((meta) => meta.content).join(",");
+ return {
+ title: decodeHtml(head.match(/<title>([\s\S]*?)<\/title>/i)?.[1] ?? ""),
+ description: namedMeta("description").map((meta) => meta.content),
+ canonicals: links.filter((link) => link.rel === "canonical").map((link) => link.href),
+ alternates: links.filter((link) => link.rel === "alternate" && link.hreflang),
+ markdown: links.find((link) => link.rel === "alternate" && link.type === "text/markdown")?.href,
+ indexable: !/\b(?:noindex|none)\b/i.test(robots),
+ openGraphUrl: namedMeta("og:url")[0]?.content,
+ image: namedMeta("og:image")[0]?.content,
+ imageAlt: namedMeta("og:image:alt")[0]?.content,
+ lastModified: namedMeta("article:modified_time")[0]?.content,
+ lang: attributes(html.match(/<html\b[^>]*>/i)?.[0] ?? "").lang,
+ headings: [...html.matchAll(/<h1\b/gi)].length,
+ main: /<main\b/i.test(html),
+ structuredData: [...html.matchAll(/<script\b[^>]*type=["']application\/ld\+json["'][^>]*>([\s\S]*?)<\/script>/gi)].map((match) => JSON.parse(match[1])),
+ hrefs: [...html.matchAll(/<a\b[^>]*>/gi)].map((match) => attributes(match[0]).href).filter(Boolean),
+ };
+}
+
+export async function readHtmlPages(directory) {
+ const pages = [];
+ async function walk(current) {
+ const entries = await readdir(current, { withFileTypes: true });
+ for (const entry of entries) {
+ const file = join(current, entry.name);
+ if (entry.isDirectory()) await walk(file);
+ else if (entry.name.endsWith(".html")) {
+ const path = `/${relative(directory, file)
+ .replace(/\\/g, "/")
+ .replace(/(?:\/index)?\.html$/, "")}`;
+ if (!LANGUAGES.some((lang) => path === `/${lang}` || path.startsWith(`/${lang}/`))) continue;
+ pages.push({ file, path, ...parseHtml(await readFile(file, "utf8")) });
+ }
+ }
+ }
+ await walk(directory);
+ return pages.sort((left, right) => left.path.localeCompare(right.path, "en"));
+}
+
+export function escapeXml(value) {
+ return value.replace(/[&<>"']/g, (character) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&apos;" })[character]);
+}
+
+export function generateSitemap(pages) {
+ const entries = pages
+ .filter((page) => page.indexable)
+ .map((page) => {
+ const canonical = `${SITE_URL}${page.path}`;
+ if (page.canonicals.length !== 1 || page.canonicals[0] !== canonical) {
+ throw new Error(`${page.path}: sitemap requires a single self-referencing canonical`);
+ }
+ const lastModified = page.lastModified && Number.isFinite(Date.parse(page.lastModified)) ? `\n <lastmod>${escapeXml(page.lastModified)}</lastmod>` : "";
+ return ` <url>\n <loc>${escapeXml(canonical)}</loc>${lastModified}\n${page.alternates.map((link) => ` <xhtml:link rel="alternate" hreflang="${escapeXml(link.hreflang)}" href="${escapeXml(link.href)}" />`).join("\n")}\n </url>`;
+ });
+ return `<?xml version="1.0" encoding="UTF-8"?>\n<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9" xmlns:xhtml="http://www.w3.org/1999/xhtml">\n${entries.join("\n")}\n</urlset>\n`;
+}
+
+export function auditPages(pages) {
+ const errors = [];
+ const pageMap = new Map(pages.map((page) => [`${SITE_URL}${page.path}`, page]));
+ const titles = new Set();
+ for (const page of pages) {
+ if (!page.indexable) continue;
+ const fail = (message) => errors.push(`${page.path}: ${message}`);
+ const canonical = `${SITE_URL}${page.path}`;
+ if (page.canonicals.length !== 1 || page.canonicals[0] !== canonical) fail("invalid canonical");
+ if (!page.title.trim()) fail("missing title");
+ const titleKey = `${page.lang}:${page.title}`;
+ if (titles.has(titleKey)) fail("duplicate title in the same language");
+ titles.add(titleKey);
+ if (page.description.length !== 1 || !page.description[0]?.trim()) fail("missing or duplicate description");
+ if (page.headings !== 1 || !page.main) fail("expected one H1 and a main landmark");
+ if (page.lang !== (page.path.startsWith("/cn") ? "zh-CN" : "en")) fail("incorrect HTML language");
+ if (page.openGraphUrl !== canonical || !page.image || !page.imageAlt) fail("incomplete Open Graph metadata");
+ for (const language of ["en", "zh-CN", "x-default"]) {
+ const alternates = page.alternates.filter((link) => link.hreflang === language);
+ if (alternates.length !== 1) {
+ fail(`expected one ${language} alternate`);
+ continue;
+ }
+ const target = pageMap.get(alternates[0].href);
+ if (!target?.indexable) fail(`${language} alternate is missing or noindex`);
+ else if (language !== "x-default" && target.lang !== language) fail(`${language} alternate has wrong language`);
+ else if (language === "x-default" && target.lang !== "en") fail("x-default must reference the English equivalent");
+ else if (!target.alternates.some((link) => link.href === canonical && link.hreflang === page.lang)) fail(`${language} alternate is not reciprocal`);
+ }
+ for (const schema of page.structuredData) {
+ if (schema["@type"] === "BreadcrumbList") {
+ for (const entry of schema.itemListElement) {
+ if (!pageMap.get(entry.item)?.indexable) fail(`breadcrumb points to a missing or noindex page: ${entry.item}`);
+ }
+ }
+ if (schema["@type"] === "TechArticle" && (schema.url !== canonical || schema.mainEntityOfPage !== canonical)) fail("article identity does not match canonical");
+ }
+ }
+ return errors;
+}
diff --git a/docs/scripts/seo.test.mjs b/docs/scripts/seo.test.mjs
new file mode 100644
index 0000000000..c428a7b794
--- /dev/null
+++ b/docs/scripts/seo.test.mjs
@@ -0,0 +1,103 @@
+import assert from "node:assert/strict";
+import { mkdtemp, mkdir, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { test } from "node:test";
+import { attributes, auditPages, decodeHtml, generateSitemap, parseHtml, readHtmlPages, SITE_URL } from "./seo.mjs";
+
+function fixture(lang, suffix = "/docs") {
+ const htmlLang = lang === "cn" ? "zh-CN" : "en";
+ const path = `/${lang}${suffix}`;
+ return {
+ path,
+ ...parseHtml(`<html lang="${htmlLang}"><head>
+ <title>${lang} Documentation</title><meta name="description" content="DBX &amp; databases">
+ <link rel="canonical" href="${SITE_URL}${path}">
+ <link rel="alternate" hreflang="en" href="${SITE_URL}/en${suffix}">
+ <link rel="alternate" hreflang="zh-CN" href="${SITE_URL}/cn${suffix}">
+ <link rel="alternate" hreflang="x-default" href="${SITE_URL}/en${suffix}">
+ <meta property="og:url" content="${SITE_URL}${path}">
+ <meta property="og:image" content="${SITE_URL}/logo.png"><meta property="og:image:alt" content="DBX">
+ </head><body><main><h1>Documentation</h1></main></body></html>`),
+ };
+}
+
+test("extracts real head tags, decodes entities, and supports quoted attributes", () => {
+ assert.deepEqual(attributes(`<link rel='canonical' href='https://example.com/?a=1&amp;b=2'>`), { rel: "canonical", href: "https://example.com/?a=1&b=2" });
+ assert.equal(decodeHtml("&#x4e2d;&#25991; &quot;DBX&quot;"), '中文 "DBX"');
+ assert.equal(decodeHtml("&AMP;&#X4E2D;&#99999999;"), "&中\uFFFD");
+ assert.deepEqual(fixture("en").description, ["DBX & databases"]);
+ assert.equal(parseHtml("<head><title>Real</title></head><body><title>Fake</title></body>").title, "Real");
+});
+
+test("accepts reciprocal, canonical, localized pages", () => {
+ assert.deepEqual(auditPages([fixture("en"), fixture("cn")]), []);
+});
+
+test("rejects nonexistent translation targets", () => {
+ assert.match(auditPages([fixture("en")]).join("\n"), /alternate is missing/);
+});
+
+test("rejects nonreciprocal translations", () => {
+ const chinese = fixture("cn");
+ chinese.alternates = chinese.alternates.filter((link) => link.hreflang !== "en");
+ assert.match(auditPages([fixture("en"), chinese]).join("\n"), /not reciprocal/);
+});
+
+test("rejects missing breadcrumb targets and mismatched article identity", () => {
+ const english = fixture("en");
+ english.structuredData = [
+ { "@type": "BreadcrumbList", itemListElement: [{ item: `${SITE_URL}/missing` }] },
+ { "@type": "TechArticle", url: `${SITE_URL}/wrong` },
+ ];
+ const errors = auditPages([english, fixture("cn")]).join("\n");
+ assert.match(errors, /breadcrumb points to a missing/);
+ assert.match(errors, /article identity/);
+});
+
+test("rejects duplicate canonicals and multiple H1s", () => {
+ const english = fixture("en");
+ english.canonicals.push(english.canonicals[0]);
+ english.headings = 2;
+ assert.match(auditPages([english, fixture("cn")]).join("\n"), /invalid canonical/);
+ assert.throws(() => generateSitemap([english]), /single self-referencing canonical/);
+});
+
+test("noindex pages are excluded from the sitemap, including future utility routes", () => {
+ const page = { path: "/en/private", ...parseHtml('<head><meta name="googlebot" content="noindex, follow"></head>') };
+ assert.equal(page.indexable, false);
+ assert.equal(parseHtml('<head><meta name="robots" content="none"></head>').indexable, false);
+ assert.doesNotMatch(generateSitemap([fixture("en"), page]), /private/);
+});
+
+test("sitemap uses HTML alternates and never invents lastmod", () => {
+ const english = fixture("en");
+ assert.doesNotMatch(generateSitemap([english]), /lastmod/);
+ english.lastModified = "2026-09-22T08:00:00.000Z";
+ const sitemap = generateSitemap([english]);
+ assert.match(sitemap, /hreflang="zh-CN"/);
+ assert.match(sitemap, /<lastmod>2026-09-22T08:00:00.000Z<\/lastmod>/);
+});
+
+test("sitemap XML escapes URLs", () => {
+ const page = fixture("en");
+ page.alternates[0].href = `${SITE_URL}/en?a=1&b=2`;
+ assert.match(generateSitemap([page]), /a=1&amp;b=2/);
+});
+
+test("reads nested index exports while excluding root redirects, 404, and text routes", async () => {
+ const directory = await mkdtemp(join(tmpdir(), "dbx-seo-"));
+ try {
+ await mkdir(join(directory, "en/docs"), { recursive: true });
+ await writeFile(join(directory, "en/docs/index.html"), '<html lang="en"><head></head></html>');
+ await writeFile(join(directory, "404.html"), "missing");
+ await writeFile(join(directory, "index.html"), "redirect");
+ await writeFile(join(directory, "en/llms.txt"), "# Text");
+ assert.deepEqual(
+ (await readHtmlPages(directory)).map((page) => page.path),
+ ["/en/docs"],
+ );
+ } finally {
+ await rm(directory, { recursive: true, force: true });
+ }
+});
diff --git a/docs/scripts/verify-seo.mjs b/docs/scripts/verify-seo.mjs
new file mode 100644
index 0000000000..c979482d0b
--- /dev/null
+++ b/docs/scripts/verify-seo.mjs
@@ -0,0 +1,44 @@
+import { readFile, stat } from "node:fs/promises";
+import { resolve } from "node:path";
+import { auditPages, generateSitemap, readHtmlPages, SITE_URL } from "./seo.mjs";
+
+const outputDirectory = resolve(import.meta.dirname, "../out");
+const pages = await readHtmlPages(outputDirectory);
+const errors = auditPages(pages);
+const index = await readFile(resolve(outputDirectory, "llms.txt"), "utf8");
+const fullText = await readFile(resolve(outputDirectory, "llms-full.txt"), "utf8");
+const sitemap = await readFile(resolve(outputDirectory, "sitemap.xml"), "utf8");
+if (sitemap !== generateSitemap(pages)) errors.push("sitemap differs from the canonical HTML metadata");
+
+for (const page of pages.filter((entry) => entry.indexable)) {
+ const image = new URL(page.image, SITE_URL);
+ if (image.origin === SITE_URL) {
+ try {
+ await stat(resolve(outputDirectory, `.${image.pathname}`));
+ } catch {
+ errors.push(`${page.path}: missing social image ${image.pathname}`);
+ }
+ }
+ if (!/^\/(en|cn)\/docs(?:\/|$)/.test(page.path)) continue;
+ const canonical = `${SITE_URL}${page.path}`;
+ if (!page.markdown || !page.markdown.startsWith(`${SITE_URL}/`)) {
+ errors.push(`${page.path}: missing Markdown alternate`);
+ continue;
+ }
+ const markdown = new URL(page.markdown).pathname;
+ try {
+ const content = await readFile(resolve(outputDirectory, `.${markdown}`), "utf8");
+ if (!content.includes(`Source: ${canonical}`) || !content.startsWith("# ")) errors.push(`${page.path}: invalid Markdown provenance`);
+ if (!index.includes(page.markdown) || !fullText.includes(`Source: ${canonical}\n`)) errors.push(`${page.path}: missing from LLM index or full text`);
+ } catch {
+ errors.push(`${page.path}: Markdown alternate does not exist at ${markdown}`);
+ }
+ for (const href of page.hrefs) {
+ const target = new URL(href, canonical);
+ if (target.origin !== SITE_URL || !/^\/(en|cn)\/docs(?:\/|$)/.test(target.pathname)) continue;
+ if (!pages.some((candidate) => candidate.path === target.pathname.replace(/\/+$/, ""))) errors.push(`${page.path}: broken documentation link ${href}`);
+ }
+}
+
+if (errors.length) throw new Error(`SEO verification failed:\n${errors.join("\n")}`);
+console.log(`SEO verified: ${pages.filter((page) => page.indexable).length} indexable pages, reciprocal hreflang, canonical sitemap, linked data, and documentation Markdown coverage.`);
diff --git a/docs/scripts/verify-static-export.mjs b/docs/scripts/verify-static-export.mjs
index a5a474b4f8..1c37f07497 100644
--- a/docs/scripts/verify-static-export.mjs
+++ b/docs/scripts/verify-static-export.mjs
@@ -46,7 +46,7 @@ const requiredContent = [
file: `${language}.html`,
includes: [`<html lang="${HTML_LANG[language] ?? language}"`, '"@type":"SoftwareApplication"'],
})),
- { file: "llms.txt", includes: ["90+ database", "25 MB", "Apache-2.0"] },
+ { file: "llms.txt", includes: ["90+ data systems", "25 MB", "Apache-2.0"] },
];
for (const requirement of requiredContent) {
diff --git a/docs/source.config.ts b/docs/source.config.ts
index 71c0f61467..8475bc78ad 100644
--- a/docs/source.config.ts
+++ b/docs/source.config.ts
@@ -2,6 +2,25 @@ import { defineDocs, defineConfig } from "fumadocs-mdx/config";
export const docs = defineDocs({
dir: "content/docs",
+ docs: {
+ postprocess: {
+ includeProcessedMarkdown: {
+ headingIds: false,
+ stringify(node, _parent, state, info) {
+ if (node.type !== "mdxJsxFlowElement") return;
+ if (!["Tabs", "Tab", "Cards", "Card", "Steps", "Step", "Accordions", "Accordion", "Callout"].includes(node.name ?? "")) return;
+ const attribute = (name: string) => {
+ const entry = node.attributes.find((item) => item.type === "mdxJsxAttribute" && item.name === name);
+ return entry && "value" in entry && typeof entry.value === "string" ? entry.value : undefined;
+ };
+ const title = attribute("title") ?? attribute("value");
+ const href = attribute("href");
+ const heading = title ? `### ${href ? `[${title}](${href})` : title}\n\n` : "";
+ return heading + state.containerFlow(node, info);
+ },
+ },
+ },
+ },
});
export default defineConfig({