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 { 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 (
- ' }; + 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(/ 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"; +import { writeFile } from "node:fs/promises"; +import { resolve } from "node:path"; +import { generateSitemap, readHtmlPages } from "./seo.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 = ` - -${urls - .map( - (entry) => - ` - ${entry.loc} -${entry.altLinks.map((alt) => ` `).join("\n")} - `, - ) - .join("\n")} - -`; - -writeFileSync(resolve(OUT_DIR, "sitemap.xml"), sitemapXml); -console.log(`sitemap.xml generated with ${urls.length} URLs`); +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 = { "&": "&", """: '"', "'": "'", "<": "<", ">": ">", "'": "'" }; + 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(/]*>([\s\S]*?)<\/head>/i)?.[1] ?? ""; + const metas = [...head.matchAll(/]*>/gi)].map((match) => attributes(match[0])); + const links = [...head.matchAll(/]*>/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(/([\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) => ({ "&": "&", "<": "<", ">": ">", '"': """, "'": "'" })[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 + + + + + + +

Documentation

`), + }; +} + +test("extracts real head tags, decodes entities, and supports quoted attributes", () => { + assert.deepEqual(attributes(``), { rel: "canonical", href: "https://example.com/?a=1&b=2" }); + assert.equal(decodeHtml("中文 "DBX""), '中文 "DBX"'); + assert.equal(decodeHtml("&中�"), "&中\uFFFD"); + assert.deepEqual(fixture("en").description, ["DBX & databases"]); + assert.equal(parseHtml("RealFake").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('') }; + assert.equal(page.indexable, false); + assert.equal(parseHtml('').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, /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&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"), ''); + 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: [` { + 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({