update(docs): improve SEO and GEO for docs

.github/workflows/build-docs.yml

@@ -15,7 +15,8 @@ jobs:
   deploy:
     runs-on: ubuntu-latest
     environment: production
-
+    permissions:
+      contents: read
     steps:
       - name: Checkout
         uses: actions/checkout@v4
@@ -30,6 +31,8 @@ jobs:
 
       - name: Build docs app
         run: bun run build --filter=docs
+        env:
+          NEXT_PUBLIC_SITE_URL: https://docs.projectcvsa.com
 
       - name: Verify build output
         run: |
@@ -44,3 +47,4 @@ jobs:
           apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
           accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
           command: pages deploy apps/docs/out --project-name="cvsa-docs"
+

.trae/rules/git-commit-message.md

@@ -1,6 +1,7 @@
 ---
 alwaysApply: true
 scene: git_message
+language: en_US
 ---
 
 ### 基本格式
@@ -10,9 +11,9 @@ scene: git_message
 ```text
 <类型>(<作用域>): <描述>
 
-[正文]
+[正文(英文描述)]
 
-[脚注]
+[脚注(英文描述)]
 ```
 
 -   **类型**：必填，表示本次提交的类别（见下文“类型列表”）。

apps/docs/app/(docs)/[lang]/[[...slug]]/page.tsx

@@ -5,9 +5,11 @@ import { getMDXComponents } from "@/components/mdx";
 import type { Metadata } from "next";
 import { createRelativeLink } from "fumadocs-ui/mdx";
 import { gitConfig } from "@/lib/layout.shared";
-import { MarkdownCopyButton, ViewOptionsPopover } from "@/components/page-actions";
+import { MarkdownCopyButton, ViewOptionsPopover } from "@/components/PageActions";
 import { buttonVariants } from "fumadocs-ui/components/ui/button";
 import { t } from "@/lib/i18n";
+import { siteUrl } from "@/lib/env";
+import { ogImageUrl, OG_IMAGE_SIZE } from "@/lib/metadata";
 
 export async function generateStaticParams() {
 	const pages = source.getPages();
@@ -79,19 +81,45 @@ export async function generateMetadata({
 }): Promise<Metadata> {
 	const { slug, lang } = await params;
 	const page = source.getPage(slug, lang);
-	const baseUrl = "https://docs.projectcvsa.com";
 	if (!page) notFound();
 	const cleanSlug = slug ? slug : [];
 	const currentPage = cleanSlug.join("/");
+	const pagePath = currentPage ? `/${currentPage}` : "";
+
+	const url = `${siteUrl}/${lang}${pagePath}`;
+	const ogImage = ogImageUrl();
 	return {
 		title: page.data.title,
 		description: page.data.description,
 		alternates: {
+			canonical: url,
 			languages: {
-				zh: `${baseUrl}/zh/${currentPage}`,
-				en: `${baseUrl}/en/${currentPage}`,
-				"x-default": `${baseUrl}/en/${currentPage}`,
+				zh: `${siteUrl}/zh${pagePath}`,
+				en: `${siteUrl}/en${pagePath}`,
+				"x-default": `${siteUrl}/en${pagePath}`,
 			},
 		},
+		openGraph: {
+			title: page.data.title,
+			description: page.data.description,
+			url,
+			siteName: t("siteName", lang),
+			locale: lang === "zh" ? "zh_CN" : "en_US",
+			type: "article",
+			images: [
+				{
+					url: ogImage,
+					width: OG_IMAGE_SIZE,
+					height: OG_IMAGE_SIZE,
+					alt: page.data.title,
+				},
+			],
+		},
+		// twitter: {
+		// 	card: "summary_large_image",
+		// 	title: page.data.title,
+		// 	description: page.data.description,
+		// 	images: [ogImage],
+		// },
 	};
 }

apps/docs/app/(landing)/layout.tsx

@@ -1,15 +1,53 @@
 import "./global.css";
 import { Funnel_Sans } from "next/font/google";
-import { UpdateLanguage } from "@/components/update-language";
+import { UpdateLanguage } from "@/components/UpdateLanguage";
+import type { Metadata } from "next";
+import { siteUrl } from "@/lib/env";
+import { t } from "@/lib/i18n";
+import { SITE_TITLE, SITE_DESCRIPTION, ogImageUrl, OG_IMAGE_SIZE } from "@/lib/metadata";
 
 const inter = Funnel_Sans({
 	subsets: ["latin"],
 });
 
+export const metadata: Metadata = {
+	title: SITE_TITLE,
+	description: SITE_DESCRIPTION,
+	alternates: {
+		canonical: siteUrl,
+		languages: {
+			en: `${siteUrl}/en`,
+			zh: `${siteUrl}/zh`,
+			"x-default": `${siteUrl}/en`,
+		},
+	},
+	openGraph: {
+		title: SITE_TITLE,
+		description: SITE_DESCRIPTION,
+		url: siteUrl,
+		siteName: t("siteName", "en"),
+		locale: "en_US",
+		type: "website",
+		images: [
+			{
+				url: ogImageUrl(),
+				width: OG_IMAGE_SIZE,
+				height: OG_IMAGE_SIZE,
+				alt: SITE_TITLE,
+			},
+		],
+	},
+	// twitter: {
+	// 	card: "summary_large_image",
+	// 	title: SITE_TITLE,
+	// 	description: SITE_DESCRIPTION,
+	// 	images: [ogImageUrl()],
+	// },
+};
+
 export default function Layout({ children }: { children: React.ReactNode }) {
 	return (
 		<html lang="en" className={inter.className} suppressHydrationWarning>
-			<title>Project CVSA | Archive for a Better Future</title>
 			<body className="relative min-w-screen min-h-screen flex flex-col justify-center overflow-hidden dark:bg-black">
 				<UpdateLanguage />
 				{children}

apps/docs/app/(landing)/old/page.tsx

@@ -1,4 +1,4 @@
-import { HeroLinks } from "@/components/links";
+import { HeroLinks } from "@/components/Links";
 import { LogoEnglish } from "@/components/icon/LogoEnglish";
 
 export default function Page() {

apps/docs/app/(landing)/page.tsx

@@ -1,6 +1,6 @@
 "use client";
 
-import { HeroLinks } from "@/components/links";
+import { HeroLinks } from "@/components/Links";
 import { LogoEnglish } from "@/components/icon/LogoEnglish";
 import { DigitGrid } from "./DigitGrid";
 import { Description } from "./Description";

apps/docs/app/llms-full.txt/route.ts

@@ -1,10 +1,69 @@
 import { getLLMText, source } from "@/lib/source";
+import { siteUrl } from "@/lib/env";
+import { t } from "@/lib/i18n";
 
 export const revalidate = false;
 
+const HEADER = `# Project CVSA | 中V档案馆 — Full Documentation
+
+> Project CVSA (中V档案馆) is an archive program that collects and preserves
+> information about the Chinese singing voice synthesis community. This file
+> contains the full markdown content of every documentation page on this site,
+> concatenated for easy ingestion by LLMs and other automated tools.
+
+## How to use this file
+
+- The content is grouped by language, then by page.
+- Each page is preceded by a level-2 heading with its title and URL.
+- Pages within a language are separated by \`---\` dividers.
+- Prefer citing the canonical page URL (linked in each section heading) over
+  copying text from this file, so links stay current.
+
+## Project links
+
+- Project home: ${siteUrl}
+- English docs: ${siteUrl}/en
+- 中文文档: ${siteUrl}/zh
+- Index of all pages: ${siteUrl}/llms.txt
+- Markdown source of any single page: append \`/raw/<lang>/<page>.mdx\` to the site URL
+- Sitemap: ${siteUrl}/sitemap.xml
+
+---
+
+`;
+
+const SECTION_DIVIDER = "\n\n---\n\n";
+
 export async function GET() {
-	const scan = source.getPages().map(getLLMText);
-	const scanned = await Promise.all(scan);
+	const pages = source.getPages();
+	const sections: string[] = [];
+
+	for (const lang of ["en", "zh"] as const) {
+		const langPages = pages.filter((p) => p.locale === lang);
+		if (langPages.length === 0) continue;
+
+		const contents = await Promise.all(langPages.map(getLLMText));
+
+		const blocks = langPages.map((page, i) => {
+			const slug = page.slugs.join("/");
+			const url = slug
+				? `${siteUrl}/${lang}/${slug}`
+				: `${siteUrl}/${lang}`;
+			const title = page.data.title ?? slug;
+			return `## [${title}](${url})\n\n${contents[i]}`;
+		});
+
+		sections.push(
+			`# ${t("siteName", lang)} — ${lang.toUpperCase()}\n\n${blocks.join(SECTION_DIVIDER)}`,
+		);
+	}
+
+	const body = `${HEADER}${sections.join(SECTION_DIVIDER)}`;
 
-	return new Response(scanned.join("\n\n"));
+	return new Response(body, {
+		headers: {
+			"Content-Type": "text/plain; charset=utf-8",
+			"Cache-Control": "public, max-age=3600",
+		},
+	});
 }

apps/docs/app/llms.txt/route.ts

@@ -1,8 +1,41 @@
 import { source } from "@/lib/source";
 import { llms } from "fumadocs-core/source";
+import { siteUrl } from "@/lib/env";
 
 export const revalidate = false;
 
+const HEADER = `# Project CVSA | 中V档案馆
+
+> Project CVSA (中V档案馆) is an archive program that collects and preserves
+> information about the Chinese singing voice synthesis community. This site
+> documents the project's mission, data model, architecture, and contribution
+> guidelines for both English and Chinese readers.
+
+This file is an LLM-friendly index of every documentation page on this site.
+Each entry links to a page and summarizes what it covers.
+
+- Project home: ${siteUrl}
+- English docs: ${siteUrl}/en
+- 中文文档: ${siteUrl}/zh
+- Full content of all pages: ${siteUrl}/llms-full.txt
+- Markdown source of any page: append \`/raw/<lang>/<page>.mdx\` to the site URL
+- Sitemap: ${siteUrl}/sitemap.xml
+
+For each page, prefer the canonical URL that matches the reader's language.
+When in doubt, link to the English version.
+
+---
+
+`;
+
 export function GET() {
-	return new Response(llms(source).index());
+	const index = llms(source).index();
+	const body = `${HEADER}${index}`;
+
+	return new Response(body, {
+		headers: {
+			"Content-Type": "text/plain; charset=utf-8",
+			"Cache-Control": "public, max-age=3600",
+		},
+	});
 }

apps/docs/app/not-found.tsx

@@ -1,17 +1,50 @@
 import "./global.css";
 import { Inter } from "next/font/google";
-import { UpdateLanguage } from "@/components/update-language";
+import { UpdateLanguage } from "@/components/UpdateLanguage";
+import type { Metadata } from "next";
+import { SITE_TITLE_404, SITE_DESCRIPTION_404, ogImageUrl, OG_IMAGE_SIZE } from "@/lib/metadata";
 
 const inter = Inter({
 	subsets: ["latin"],
 });
 
+export const metadata: Metadata = {
+	title: `${SITE_TITLE_404}`,
+	description: SITE_DESCRIPTION_404,
+	robots: { index: false, follow: false },
+	openGraph: {
+		title: `${SITE_TITLE_404}`,
+		description: SITE_DESCRIPTION_404,
+		images: [
+			{
+				url: ogImageUrl(),
+				width: OG_IMAGE_SIZE,
+				height: OG_IMAGE_SIZE,
+				alt: SITE_TITLE_404,
+			},
+		],
+	},
+	// twitter: {
+	// 	card: "summary_large_image",
+	// 	title: `Not Found - ${SITE_TITLE_404}`,
+	// 	description: SITE_DESCRIPTION_404,
+	// 	images: [ogImageUrl()],
+	// },
+};
+
 export default function NotFound() {
 	return (
 		<html lang="en" className={inter.className}>
-			<body className="flex flex-col min-h-screen">
+			<body className="flex flex-col min-h-screen items-center justify-center gap-4">
 				<UpdateLanguage />
-				<h1>Not Found</h1>
+				<h1 className="text-4xl font-bold">404</h1>
+				<p className="text-fd-muted-foreground">Page not found</p>
+				<a
+					href="/en"
+					className="text-fd-primary underline underline-offset-4 hover:text-fd-primary/80"
+				>
+					Go to homepage
+				</a>
 			</body>
 		</html>
 	);

apps/docs/app/robots.ts

@@ -0,0 +1,12 @@
+import type { MetadataRoute } from "next";
+import { siteUrl } from "@/lib/env";
+
+export default function robots(): MetadataRoute.Robots {
+	return {
+		rules: {
+			userAgent: "*",
+			allow: "/",
+		},
+		sitemap: `${siteUrl}/sitemap.xml`,
+	};
+}

apps/docs/app/sitemap.ts

@@ -0,0 +1,28 @@
+import type { MetadataRoute } from "next";
+import { source } from "@/lib/source";
+import { siteUrl } from "@/lib/env";
+
+export default function sitemap(): MetadataRoute.Sitemap {
+	const pages = source.getPages();
+
+	const docPages = pages.map((page) => {
+		const slug = page.slugs.join("/");
+		const url = `${siteUrl}/${page.locale}${slug ? `/${slug}` : ""}`;
+
+		return {
+			url,
+			// lastModified: new Date(),
+			changeFrequency: "weekly" as const,
+			priority: page.slugs.length === 0 ? 0.8 : 0.6,
+		};
+	});
+
+	const landingPage: MetadataRoute.Sitemap[number] = {
+		url: siteUrl,
+		// lastModified: new Date(),
+		changeFrequency: "monthly",
+		priority: 1.0,
+	};
+
+	return [landingPage, ...docPages];
+}