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

This commit is contained in:
t8y2 committed 2026-09-22 18:10:07 +08:00
1 parent 25a36deec9
commit 8ffdbb2950
23 files changed
+563 -244

No files matched your search

+12 -35
View File
@@ -11,7 +11,10 @@ import { ImageZoom } from "fumadocs-ui/components/image-zoom";
import { Accordion, Accordions } from "fumadocs-ui/components/accordion"; import { Accordion, Accordions } from "fumadocs-ui/components/accordion";
import type { MDXContent } from "mdx/types"; import type { MDXContent } from "mdx/types";
import type { TOCItemType } from "fumadocs-core/toc"; 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> { export async function generateMetadata({ params }: { params: Promise<{ lang: string; slug?: string[] }> }): Promise<Metadata> {
const { lang, slug } = await params; 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; const description = (page.data.description as string) || undefined;
return buildMetadata({ return buildMetadata({
title, title: `${title} · ${lang === "cn" ? "使用文档" : "Documentation"}`,
description: description ?? "", description: description ?? "",
path: slug ? `/${lang}/docs/${slug.join("/")}` : `/${lang}/docs`, path: slug?.length ? `/${lang}/docs/${slug.join("/")}` : `/${lang}/docs`,
lang, lang,
ogType: "article", 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 title = page.data.title as string;
const description = (page.data.description as string) || ""; const description = (page.data.description as string) || "";
const docPath = slug ? `/${lang}/docs/${slug.join("/")}` : `/${lang}/docs`; const docPath = slug?.length ? `/${lang}/docs/${slug.join("/")}` : `/${lang}/docs`;
const structuredData = buildDocStructuredData(resolveLang(lang), title, description, docPath);
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,
},
};
return ( return (
<main className="contents"> <main className="contents">
<DocsPage toc={toc}> <DocsPage toc={toc}>
<script type="application/ld+json" dangerouslySetInnerHTML={{ __html: JSON.stringify(breadcrumbJsonLd) }} /> {structuredData.map((entry) => (
<script type="application/ld+json" dangerouslySetInnerHTML={{ __html: JSON.stringify(articleJsonLd) }} /> <script key={entry["@id"]} type="application/ld+json" dangerouslySetInnerHTML={{ __html: serializeStructuredData(entry) }} />
))}
<DocsTitle>{title}</DocsTitle> <DocsTitle>{title}</DocsTitle>
<DocsBody> <DocsBody>
<MDX components={mdxComponents} /> <MDX components={mdxComponents} />
+3 -4
View File
@@ -3,7 +3,7 @@ import type { ReactNode } from "react";
import type { Metadata, Viewport } from "next"; import type { Metadata, Viewport } from "next";
import { RouteProgress } from "@/components/RouteProgress"; import { RouteProgress } from "@/components/RouteProgress";
import { buildMetadata, DEFAULT_DESCRIPTION, getHtmlLang, SITE_NAME, SITE_URL } from "@/lib/metadata"; 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"; import { i18n, resolveLang } from "@/lib/i18n";
const LOCALE_MAP: Record<string, { locale: string; title: string; description: string }> = { 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: { cn: {
locale: "zh_CN", locale: "zh_CN",
title: "DBX - 25MB,管理90+种数据库", 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", shortcut: "/favicon-64.png",
apple: "/logo.png", apple: "/logo.png",
}, },
robots: { index: true, follow: true },
openGraph: { ...pageMetadata.openGraph, locale: meta.locale }, 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" data-domains="dbxio.com,www.dbxio.com"
/> />
{siteStructuredData.map((structuredData) => ( {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> </head>
<body className="flex min-h-screen flex-col"> <body className="flex min-h-screen flex-col">
@@ -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("/"),
}));
}
+4 -4
View File
@@ -17,7 +17,7 @@ import { contributorsFromActivity } from "@/lib/contributors";
import { getAppVersion } from "@/lib/appVersion"; import { getAppVersion } from "@/lib/appVersion";
import { fetchLatestReleaseInfo } from "@/lib/latestRelease"; import { fetchLatestReleaseInfo } from "@/lib/latestRelease";
import { buildMetadata, getHtmlLang } from "@/lib/metadata"; 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 { ArrowRight, Bot, Database, FileCode, GitCompare, Network, Search, Shield, Table, Terminal, Zap } from "lucide-react";
import { resolveLang, type DocsLang } from "@/lib/i18n"; import { resolveLang, type DocsLang } from "@/lib/i18n";
@@ -448,11 +448,11 @@ const i18nText = {
const landingMeta = { const landingMeta = {
en: { en: {
title: "DBX - 25 MB to manage 90+ databases!", 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: { cn: {
title: "DBX - 25MB,管理90+种数据库!", 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 ( return (
<main className="landing" lang={getHtmlLang(l)}> <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 /> <Starfield />
{/* Nav */} {/* Nav */}
+10
View File
@@ -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" } });
}
+8
View File
@@ -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" } });
}
+29
View File
@@ -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");
});
+40
View File
@@ -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"
);
}
+28
View File
@@ -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]);
});
+19 -21
View File
@@ -2,8 +2,8 @@ import type { Metadata } from "next";
export const SITE_URL = "https://dbxio.com"; export const SITE_URL = "https://dbxio.com";
export const SITE_NAME = "DBX"; 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_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 = "/logo.png"; export const DEFAULT_OG_IMAGE = "https://dl.dbxio.com/assets/readme-hero-20260820.png";
const LOCALE_MAP: Record<string, string> = { const LOCALE_MAP: Record<string, string> = {
en: "en_US", en: "en_US",
@@ -20,7 +20,7 @@ export function getHtmlLang(lang: string): string {
} }
function swapLang(path: string, to: string): string { function swapLang(path: string, to: string): string {
return path.replace(/^\/(en|cn)/, `/${to}`); return path.replace(/^\/(en|cn)(?=\/|$)/, `/${to}`);
} }
interface BuildMetadataParams { interface BuildMetadataParams {
@@ -31,24 +31,15 @@ interface BuildMetadataParams {
ogType?: "website" | "article"; ogType?: "website" | "article";
images?: string[]; images?: string[];
lastModified?: Date; lastModified?: Date;
markdownPath?: string;
} }
export function buildMetadata({ export function buildMetadata({ title, description, path, lang, ogType = "website", images, lastModified, markdownPath }: BuildMetadataParams): Metadata {
title, const normalizedPath = path.split(/[?#]/)[0].replace(/\/+$/, "") || "/";
description, const canonical = `${SITE_URL}${normalizedPath}`;
path,
lang,
ogType = "website",
images,
lastModified,
}: BuildMetadataParams): Metadata {
const canonical = `${SITE_URL}${path}`;
const locale = LOCALE_MAP[lang] ?? "en_US"; const locale = LOCALE_MAP[lang] ?? "en_US";
const ogImages = images?.map((url) => ({ const defaultImage = { url: DEFAULT_OG_IMAGE, width: 1792, height: 896 };
url, const ogImages = images?.map((url) => (url === DEFAULT_OG_IMAGE ? defaultImage : { url })) ?? [defaultImage];
width: url === DEFAULT_OG_IMAGE ? 512 : 1200,
height: url === DEFAULT_OG_IMAGE ? 512 : 630,
})) ?? [{ url: DEFAULT_OG_IMAGE, width: 512, height: 512 }];
const base: Metadata = { const base: Metadata = {
title, title,
@@ -56,10 +47,16 @@ export function buildMetadata({
alternates: { alternates: {
canonical, canonical,
languages: { languages: {
en: `${SITE_URL}${swapLang(path, "en")}`, en: `${SITE_URL}${swapLang(normalizedPath, "en")}`,
zh: `${SITE_URL}${swapLang(path, "cn")}`, "zh-CN": `${SITE_URL}${swapLang(normalizedPath, "cn")}`,
"x-default": `${SITE_URL}${swapLang(path, "en")}`, "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: { openGraph: {
title, title,
@@ -68,6 +65,7 @@ export function buildMetadata({
siteName: SITE_NAME, siteName: SITE_NAME,
type: ogType, type: ogType,
locale, locale,
alternateLocale: Object.values(LOCALE_MAP).filter((alternate) => alternate !== locale),
images: ogImages, images: ogImages,
}, },
twitter: { twitter: {
+19 -3
View File
@@ -1,7 +1,7 @@
import assert from "node:assert/strict"; import assert from "node:assert/strict";
import { test } from "vitest"; 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", () => { test("site structured data does not advertise a nonexistent search route", () => {
const [website, organization] = buildSiteStructuredData(); const [website, organization] = buildSiteStructuredData();
@@ -18,8 +18,24 @@ test("software structured data stays localized and versioned", () => {
assert.equal(english.applicationCategory, "DeveloperApplication"); assert.equal(english.applicationCategory, "DeveloperApplication");
assert.equal(english.softwareVersion, "0.5.71"); assert.equal(english.softwareVersion, "0.5.71");
assert.equal(english.inLanguage, "en"); 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.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"); 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);
});
+38 -24
View File
@@ -3,7 +3,7 @@ import type { DocsLang } from "./i18n";
const localizedDescription = { const localizedDescription = {
en: DEFAULT_DESCRIPTION, en: DEFAULT_DESCRIPTION,
cn: "90+ 种数据库,仅 25 MB。支持桌面端、Docker 自托管、AI 助手与 MCP Server。", cn: "DBX 是免费开源的数据库管理工具,支持 MySQL、PostgreSQL、SQLite、Redis 等 90+ 种数据系统,提供 SQL 编辑、AI 助手与 Docker 自托管。",
} as const; } as const;
const localizedFeatureList = { const localizedFeatureList = {
@@ -15,14 +15,7 @@ const localizedFeatureList = {
"MCP Server integration for AI coding agents", "MCP Server integration for AI coding agents",
"Schema browsing, schema diff, data editing, import, and export", "Schema browsing, schema diff, data editing, import, and export",
], ],
cn: [ cn: ["统一管理 90+ 种 SQL、NoSQL、向量、时序、嵌入式数据库与消息队列", "提供 Windows、macOS 与 Linux 桌面端", "支持 Docker 自托管与浏览器访问", "支持 AI 生成、解释、优化与修复 SQL", "通过 MCP Server 连接 AI 编程智能体", "提供结构浏览、结构对比、数据编辑、导入与导出"],
"统一管理 90+ 种 SQL、NoSQL、向量、时序、嵌入式数据库与消息队列",
"提供 Windows、macOS 与 Linux 桌面端",
"支持 Docker 自托管与浏览器访问",
"支持 AI 生成、解释、优化与修复 SQL",
"通过 MCP Server 连接 AI 编程智能体",
"提供结构浏览、结构对比、数据编辑、导入与导出",
],
} as const; } as const;
export function buildSiteStructuredData() { export function buildSiteStructuredData() {
@@ -45,16 +38,44 @@ export function buildSiteStructuredData() {
url: SITE_URL, url: SITE_URL,
description: DEFAULT_DESCRIPTION, description: DEFAULT_DESCRIPTION,
logo: `${SITE_URL}/logo.png`, logo: `${SITE_URL}/logo.png`,
sameAs: [ 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"],
"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; ] 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) { export function buildSoftwareApplicationStructuredData(lang: DocsLang, version: string) {
const language = getHtmlLang(lang); const language = getHtmlLang(lang);
@@ -75,11 +96,7 @@ export function buildSoftwareApplicationStructuredData(lang: DocsLang, version:
downloadUrl: "https://github.com/t8y2/dbx/releases/latest", downloadUrl: "https://github.com/t8y2/dbx/releases/latest",
releaseNotes: `${SITE_URL}/${lang}/changelog`, releaseNotes: `${SITE_URL}/${lang}/changelog`,
license: "https://github.com/t8y2/dbx/blob/main/LICENSE", license: "https://github.com/t8y2/dbx/blob/main/LICENSE",
screenshot: [ screenshot: [`${SITE_URL}/screenshot-dark.png`, `${SITE_URL}/screenshot-er.png`, `${SITE_URL}/screenshot-grid.png`],
`${SITE_URL}/screenshot-dark.png`,
`${SITE_URL}/screenshot-er.png`,
`${SITE_URL}/screenshot-grid.png`,
],
featureList: [...localizedFeatureList[lang]], featureList: [...localizedFeatureList[lang]],
offers: { offers: {
"@type": "Offer", "@type": "Offer",
@@ -89,9 +106,6 @@ export function buildSoftwareApplicationStructuredData(lang: DocsLang, version:
}, },
author: { "@id": `${SITE_URL}/#organization` }, author: { "@id": `${SITE_URL}/#organization` },
publisher: { "@id": `${SITE_URL}/#organization` }, publisher: { "@id": `${SITE_URL}/#organization` },
sameAs: [ sameAs: ["https://github.com/t8y2/dbx", "https://www.npmjs.com/package/@dbx-app/mcp-server"],
"https://github.com/t8y2/dbx",
"https://www.npmjs.com/package/@dbx-app/mcp-server",
],
} as const; } as const;
} }
+4 -2
View File
@@ -6,9 +6,11 @@
"dev": "next dev", "dev": "next dev",
"preview": "node scripts/preview-server.mjs", "preview": "node scripts/preview-server.mjs",
"content:check": "node scripts/verify-doc-content.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", "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", "contributors:update": "node scripts/update-contributors.mjs",
"start": "next start", "start": "next start",
"postinstall": "fumadocs-mdx" "postinstall": "fumadocs-mdx"
+12
View File
@@ -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
+5
View File
@@ -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
-50
View File
@@ -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.
+14 -1
View File
@@ -1,7 +1,20 @@
User-agent: * User-agent: *
Allow: / 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 User-agent: GPTBot
Allow: / Allow: /
+7 -99
View File
@@ -1,100 +1,8 @@
import { readdirSync, writeFileSync } from "fs"; import { writeFile } from "node:fs/promises";
import { resolve, relative } from "path"; import { resolve } from "node:path";
import { DEFAULT_LANGUAGE, LANGUAGES } from "./languages.mjs"; import { generateSitemap, readHtmlPages } from "./seo.mjs";
const OUT_DIR = resolve(import.meta.dirname, "../out"); const outputDirectory = resolve(import.meta.dirname, "../out");
const SITE_URL = "https://dbxio.com"; const pages = await readHtmlPages(outputDirectory);
const EXCLUDE = new Set(["index.html", "404.html", "_not-found.html"]); await writeFile(resolve(outputDirectory, "sitemap.xml"), generateSitemap(pages));
const EXCLUDE_PATHS = new Set([ console.log(`sitemap.xml generated with ${pages.filter((page) => page.indexable).length} canonical URLs.`);
...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`);
+123
View File
@@ -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;
}
+103
View File
@@ -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 });
}
});
+44
View File
@@ -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.`);
+1 -1
View File
@@ -46,7 +46,7 @@ const requiredContent = [
file: `${language}.html`, file: `${language}.html`,
includes: [`<html lang="${HTML_LANG[language] ?? language}"`, '"@type":"SoftwareApplication"'], 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) { for (const requirement of requiredContent) {
+19
View File
@@ -2,6 +2,25 @@ import { defineDocs, defineConfig } from "fumadocs-mdx/config";
export const docs = defineDocs({ export const docs = defineDocs({
dir: "content/docs", 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({ export default defineConfig({