Skip to content

docs: add og:title and fix punctuation in docs #58

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
Aibeto wants to merge 12 commits into from
Closed

docs: add og:title and fix punctuation in docs #58

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
6767191
docs(guide): update developer setup guide with redis and env notes
Aibeto May 16, 2026
1310a6f
docs: add og metadata and fix punctuation in docs
Aibeto May 16, 2026
ba6bb44
docs(guide): update env configuration instructions
Aibeto May 16, 2026
95ef7a6
docs: fix 404 page and update dev guide wording
Aibeto May 16, 2026
a4fc078
docs(website): add robots, manifest and sitemap for docs site
Aibeto May 16, 2026
3f745f7
feat(docs): add SEO optimization across landing and docs pages
Aibeto May 16, 2026
7eb098b
docs(git-commit): add git commit message specification document
Aibeto May 16, 2026
3a20d1a
Merge branch 'chore/aibeto-main-git_message' into update/aibeto-docs
Aibeto May 16, 2026
c4f9019
chore: commit message rules for TRAE (#59)
Aibeto May 16, 2026
7b27604
Merge remote-tracking branch 'origin/update/aibeto-docs' into update/…
Aibeto May 16, 2026
1bca05c
docs(website): update landing page metadata and remove hardcoded title
Aibeto May 16, 2026
765b4aa
docs(commit-rule): update git commit message specification
Aibeto May 16, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 35 additions & 0 deletions .trae/rules/git-commit-message.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
---
alwaysApply: true
scene: git_message
---
### 基本格式

每条提交信息应遵循以下结构（只允许使用英文）：

```text
<类型（英文）>(<作用域>): <描述（英文）>

[正文(英文)]

[脚注(英文)]
```
Comment on lines +9 to +15

@coderabbitai coderabbitai Bot May 16, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Template placeholders should use English to match the requirement.

The template on line 11 uses Chinese placeholders (<类型>(<作用域>): <描述>), but line 8 requires all commit messages to be in English. This inconsistency could confuse developers about what language to use.

Consider updating the template to use English placeholders for clarity:

 ```text
-<类型>(<作用域>): <描述>
+<type>(<scope>): <description>
 
-[正文(英文描述)]
+[body]
 
-[脚注(英文描述)]
+[footer]

The "(英文描述)" annotations on lines 13 and 15 would also become unnecessary with this change.

<details>
<summary>🤖 Prompt for AI Agents</summary>

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @.trae/rules/git-commit-message.md around lines 10 - 16, Update the commit
message template placeholders from Chinese to English: replace occurrences of
"<类型>(<作用域>): <描述>" with "(): ", change "[正文(英文描述)]"
to "[body]" and "[脚注(英文描述)]" to "[footer]", and remove the "(英文描述)" annotations
so the template uses consistent English placeholders (look for the template
block containing those placeholder tokens).


</details>

<!-- fingerprinting:phantom:triton:puma -->

<!-- This is an auto-generated comment by CodeRabbit -->


- **类型**：必填，表示本次提交的类别（见下文“类型列表”）。
- **作用域**：可选，用括号包裹，指明本次提交影响的代码范围（如模块名、组件名等）。
- **描述**：必填，是对变更的简短说明，使用祈使句、现在时态，首字母小写，末尾不加句号。
- **正文**：可选，对变更动机及与之前行为的对比进行详细说明。
- **脚注**：可选，主要用于关联 Issue 或标记破坏性变更（BREAKING CHANGE）。

### 允许的类型列表

- `feat`：新增功能。
- `fix`：修复 bug。
- `update`: 对代码内容做出调整，而原先的代码不视为 bug（如修改前端按钮的文案）
- `docs`：仅修改文档。
- `style`：修改代码格式（不影响代码运行的变动，如空格、分号缺失等）。
- `refactor`：重构代码（既不是新增功能，也不是修改 bug 的代码变动）。
- `perf`：优化性能。
- `test`：增加测试或修改现有测试。
- `ci`：修改 CI 配置文件或脚本（例如：Travis, Circle, BrowserStack, SauceLabs）。
- `chore`：其他不修改源代码或测试文件的更改。
- `revert`：撤销之前的提交。
15 changes: 15 additions & 0 deletions apps/docs/app/(docs)/[lang]/[[...slug]]/page.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -83,15 +83,30 @@ export async function generateMetadata({
if (!page) notFound();
const cleanSlug = slug ? slug : [];
const currentPage = cleanSlug.join("/");
const url = `${baseUrl}/${lang}/${currentPage}`;
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}`,
Comment on lines +86 to 95

@coderabbitai coderabbitai Bot May 16, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Normalize root-page canonical/alternate URLs.

At Line 86, when slug is empty, URLs become .../en/ and .../zh/. Keeping root docs URLs normalized (no extra trailing segment) avoids inconsistent canonical signals.

Suggested fix 
-	const currentPage = cleanSlug.join("/");
-	const url = `${baseUrl}/${lang}/${currentPage}`;
+	const currentPage = cleanSlug.join("/");
+	const slugPath = currentPage ? `/${currentPage}` : "";
+	const url = `${baseUrl}/${lang}${slugPath}`;
 	return {
@@
 		alternates: {
 			canonical: url,
 			languages: {
-				zh: `${baseUrl}/zh/${currentPage}`,
-				en: `${baseUrl}/en/${currentPage}`,
-				"x-default": `${baseUrl}/en/${currentPage}`,
+				zh: `${baseUrl}/zh${slugPath}`,
+				en: `${baseUrl}/en${slugPath}`,
+				"x-default": `${baseUrl}/en${slugPath}`,
 			},
 		},
🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@apps/docs/app/`(docs)/[lang]/[[...slug]]/page.tsx around lines 86 - 95, The
canonical/alternate URL construction uses url =
`${baseUrl}/${lang}/${currentPage}` and yields an extra trailing segment when
currentPage is empty; change the URL assembly to omit the "/{currentPage}"
portion for root pages (e.g., compute a normalized segment like currentPage ?
`/${currentPage}` : '' and use `${baseUrl}/${lang}${normalizedSegment}`) and
apply the same normalization for alternates.languages entries so root docs use
`${baseUrl}/en` and `${baseUrl}/zh` (no extra trailing segment).

},
},
openGraph: {
title: page.data.title,
description: page.data.description,
url,
siteName: "Project CVSA",
locale: lang === "zh" ? "zh_CN" : "en_US",
type: "article",
},
twitter: {
card: "summary_large_image",
title: page.data.title,
description: page.data.description,
},
};
}
33 changes: 32 additions & 1 deletion apps/docs/app/(landing)/layout.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,15 +1,46 @@
import "./global.css";
import { Funnel_Sans } from "next/font/google";
import { UpdateLanguage } from "@/components/update-language";
import type { Metadata } from "next";

const inter = Funnel_Sans({
subsets: ["latin"],
});

const baseUrl = "https://docs.projectcvsa.com";

export const metadata: Metadata = {
title: "Project CVSA | Archive for a Better Future",
description:
"Project CVSA is an archive program aiming to collect and preserve all information about the Chinese singing voice synthesis community.",
alternates: {
canonical: baseUrl,
languages: {
en: `${baseUrl}/en`,
zh: `${baseUrl}/zh`,
"x-default": `${baseUrl}/en`,
},
},
openGraph: {
title: "Project CVSA | Archive for a Better Future",
description:
"Project CVSA is an archive program aiming to collect and preserve all information about the Chinese singing voice synthesis community.",
url: baseUrl,
siteName: "Project CVSA",
locale: "en_US",
type: "website",
},
twitter: {
card: "summary_large_image",
title: "Project CVSA | Archive for a Better Future",
description:
"Project CVSA is an archive program aiming to collect and preserve all information about the Chinese singing voice synthesis community.",
},
};

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}
Expand Down
18 changes: 16 additions & 2 deletions apps/docs/app/not-found.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,17 +1,31 @@
import "./global.css";
import { Inter } from "next/font/google";
import { UpdateLanguage } from "@/components/update-language";
import type { Metadata } from "next";

const inter = Inter({
subsets: ["latin"],
});

export const metadata: Metadata = {
title: "Not Found - Project CVSA",
description: "The page you are looking for does not exist.",
robots: { index: false, follow: false },
};

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>
);
Expand Down
126 changes: 126 additions & 0 deletions apps/docs/app/sitemap.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,126 @@
import type { MetadataRoute } from 'next'

export default function sitemap(): MetadataRoute.Sitemap {
return [
{
url: 'https://docs.projectcvsa.com/',
lastModified: new Date(),
changeFrequency: 'weekly',
priority: 1,
},
{
url: 'https://docs.projectcvsa.com/en',
lastModified: new Date(),
changeFrequency: 'weekly',
priority: 0.8,
},
{
url: 'https://docs.projectcvsa.com/zh',
lastModified: new Date(),
changeFrequency: 'weekly',
priority: 0.9,
},
{
url: 'https://docs.projectcvsa.com/zh/scope-of-inclusion',
lastModified: new Date(),
changeFrequency: 'weekly',
priority: 0.5,
},
{
url: 'https://docs.projectcvsa.com/zh/internal',
lastModified: new Date(),
changeFrequency: 'weekly',
priority: 0.5,
},
{
url: 'https://docs.projectcvsa.com/zh/internal/developers/guide',
lastModified: new Date(),
changeFrequency: 'weekly',
priority: 0.4,
},
{
url: 'https://docs.projectcvsa.com/zh/internal/developers/architecture',
lastModified: new Date(),
changeFrequency: 'weekly',
priority: 0.4,
},
{
url: 'https://docs.projectcvsa.com/zh/internal/developers/hld',
lastModified: new Date(),
changeFrequency: 'weekly',
priority: 0.33,
},
{
url: 'https://docs.projectcvsa.com/zh/internal/developers/style-guide',
lastModified: new Date(),
changeFrequency: 'weekly',
priority: 0.33,
},
{
url: 'https://docs.projectcvsa.com/zh/internal/developers/workflow',
lastModified: new Date(),
changeFrequency: 'weekly',
priority: 0.33,
},
{
url: 'https://docs.projectcvsa.com/zh/internal/developers/crawler/overview',
lastModified: new Date(),
changeFrequency: 'weekly',
priority: 0.26,
},
{
url: 'https://docs.projectcvsa.com/zh/internal/legacy/architecture-overview',
lastModified: new Date(),
changeFrequency: 'weekly',
priority: 0.3,
},
{
url: 'https://docs.projectcvsa.com/zh/internal/legacy/crawling-lifecycle',
lastModified: new Date(),
changeFrequency: 'weekly',
priority: 0.2,
},
{
url: 'https://docs.projectcvsa.com/zh/internal/legacy/video-discovery-pipeline',
lastModified: new Date(),
changeFrequency: 'weekly',
priority: 0.2,
},
{
url: 'https://docs.projectcvsa.com/zh/internal/legacy/song-collection-pipeline',
lastModified: new Date(),
changeFrequency: 'weekly',
priority: 0.2,
},
{
url: 'https://docs.projectcvsa.com/zh/internal/legacy/snapshot-scheduling',
lastModified: new Date(),
changeFrequency: 'weekly',
priority: 0.2,
},
{
url: 'https://docs.projectcvsa.com/zh/internal/legacy/snapshot-execution',
lastModified: new Date(),
changeFrequency: 'weekly',
priority: 0.2,
},
{
url: 'https://docs.projectcvsa.com/zh/internal/legacy/message-queue-reference',
lastModified: new Date(),
changeFrequency: 'weekly',
priority: 0.2,
},
{
url: 'https://docs.projectcvsa.com/zh/internal/legacy/database-schema-reference',
lastModified: new Date(),
changeFrequency: 'weekly',
priority: 0.2,
},
{
url: 'https://docs.projectcvsa.com/zh/internal/legacy/network-proxy-architecture',
lastModified: new Date(),
changeFrequency: 'weekly',
priority: 0.2,
},
]
}
1 change: 1 addition & 0 deletions apps/docs/content/internal/developers/architecture.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
---
title: 项目架构
description: 了解档案馆的项目组织架构。
og:title: Project CVSA 项目架构
---

## 目录结构
Expand Down
3 changes: 2 additions & 1 deletion apps/docs/content/internal/developers/crawler/meta.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
{
"title": "爬虫架构"
"title": "爬虫架构",
"og:title": "Project CVSA 爬虫架构"
}
1 change: 1 addition & 0 deletions apps/docs/content/internal/developers/crawler/overview.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
---
title: 新爬虫架构概览
description: CVSA 2.0 爬虫系统的总体设计、核心设计目标与节点角色定义
og:title: 新爬虫架构概览

@coderabbitai coderabbitai Bot May 16, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Align og:title with the new global prefix convention.

Line 4 uses 新爬虫架构概览, while other updated pages use Project CVSA .... This creates inconsistent social preview titles.

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@apps/docs/content/internal/developers/crawler/overview.md` at line 4, Update
the social preview meta so it follows the new global prefix convention: replace
the existing line "og:title: 新爬虫架构概览" with the prefixed title used across pages
(e.g. "og:title: Project CVSA - 新爬虫架构概览") so the og:title meta matches other
updated pages; modify the "og:title" line in this document accordingly.

---

## 设计目标
Expand Down
16 changes: 13 additions & 3 deletions apps/docs/content/internal/developers/guide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
---
title: 开发者指南
description: 了解如何参与档案馆的开发工作。
og:title: Project CVSA 开发开发者指南

@coderabbitai coderabbitai Bot May 16, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Fix duplicated wording in og:title.

Line 4 currently has Project CVSA 开发开发者指南; 开发 is duplicated and will surface in social previews.

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@apps/docs/content/internal/developers/guide.md` at line 4, The og:title meta
value currently contains a duplicated word ("开发") — update the og:title entry
(the "og:title" meta line) to remove the extra "开发" so it reads "Project CVSA
开发者指南" instead of "Project CVSA 开发开发者指南".

---

## 准备环境
Expand Down Expand Up @@ -43,23 +44,32 @@ cp apps/backend/.env.example apps/backend/.env
cp apps/backend/.env.example apps/backend/.env.test
```

为了避免开发和测试环境冲突，你需要将所有 `.env.test` 中的 `DATABASE_URL` 修改为用于测试的数据库。例如：
为了避免开发和测试环境冲突，你需要将所有 `.env.test` 中的 `DATABASE_URL`、`MEILI_API_URL` 和 `REDIS_URL` 修改为用于测试的地址。例如：
```bash
# 在 .env 中
DATABASE_URL=postgres://cvsa:password@localhost:5432/cvsa
MEILI_API_URL=http://localhost:7700
REDIS_URL=redis://localhost:6379
# 在 .env.test 中
DATABASE_URL=postgres://cvsa:password@localhost:5432/cvsa_test
MEILI_API_URL=http://localhost:7700
REDIS_URL=redis://localhost:6379
```

如果`.env`和`.env.test`中缺少`REDIS_URL`可以手动添加（通常只需要在`/packages/core/`中的`.env`和`.env.test`添加）。不要修改`.ts`文件中的默认值。
`MEILI_MASTER_KEY`、`cvsa`和`password`如需修改需要和`.env.docker`文件中的值一致。

## 启动外部服务

你需要准备一个 PostgreSQL 18 以及 MeiliSearch 1.40 实例来辅助开发和调试。推荐使用 Docker，因为它易于管理和隔离。
确保你安装了 [Docker Compose](https://docs.docker.com/compose/install/)，之后便可以在根路径下通过 compose 拉起这两个容器。
你需要准备一个 PostgreSQL 18 、Redis 7 以及 MeiliSearch 1.40 实例来辅助开发和调试。推荐使用 Docker，因为它易于管理和隔离。
确保你安装了 [Docker Compose](https://docs.docker.com/compose/install/)，之后便可以在根路径下通过 compose 拉起这三个容器。

```bash
docker compose up -d
```

如果 Docker 服务不在本机，可能需要使用`docker-compose-remote.yml`来启动服务。需要将`.env.docker`一起复制到远端配置目录。

## 初始化项目

在开始开发前，需要安装依赖并运行初始化脚本。
Expand Down
3 changes: 2 additions & 1 deletion apps/docs/content/internal/developers/meta.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
{
"title": "开发文档"
"title": "开发文档",
"og:title": "Project CVSA 开发文档"
}
1 change: 1 addition & 0 deletions apps/docs/content/internal/developers/style-guide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
---
title: 代码风格指南
description: 档案馆项目的代码风格、架构决策及类型安全规范。
og:title: Project CVSA 代码风格指南
---

## TypeScript 代码规范
Expand Down
1 change: 1 addition & 0 deletions apps/docs/content/internal/developers/workflow.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
---
title: 流程规范
description: 了解档案馆的开发工作流和相关规范。
og:title: Project CVSA 流程规范
---

## 分支命名
Expand Down
3 changes: 2 additions & 1 deletion apps/docs/content/internal/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
---
title: 成员指南
description: 档案馆成员的内部协作指南
description: 档案馆成员的内部协作指南。
og:title: Project CVSA 内部成员协作指南
---

欢迎加入中 V 档案馆！本指南旨在帮助新成员快速了解项目运作模式、协作规范及工具使用方法。
Expand Down
3 changes: 2 additions & 1 deletion apps/docs/content/internal/legacy/architecture-overview.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
---
title: 系统架构概览
description: 爬虫系统的整体架构、核心组件与数据流向
description: 爬虫系统的整体架构、核心组件与数据流向。
og:title: Project CVSA 系统架构概览
---

CVSA 的爬虫系统是一个基于 BullMQ 消息队列的数据采集系统，用于持续追踪 Bilibili 视频的播放数据。
Expand Down
3 changes: 2 additions & 1 deletion apps/docs/content/internal/legacy/crawling-lifecycle.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
---
title: 一次完整爬取的生命周期
description: 从视频发现到成就追踪的全流程示例，展示爬虫系统如何处理一个新视频的完整生命周期
description: 从视频发现到成就追踪的全流程示例，展示爬虫系统如何处理一个新视频的完整生命周期。
og:title: 一次完整爬取的生命周期

@coderabbitai coderabbitai Bot May 16, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Unify og:title format with the rest of docs metadata.

Line 4 uses a different pattern from the standardized Project CVSA … format used in this PR cohort. Please align it to keep social preview titles consistent.

Suggested fix 
-og:title: 一次完整爬取的生命周期
+og:title: Project CVSA 一次完整爬取的生命周期
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
og:title: 一次完整爬取的生命周期
og:title: Project CVSA 一次完整爬取的生命周期
🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@apps/docs/content/internal/legacy/crawling-lifecycle.md` at line 4, Update
the og:title metadata value to match the standardized "Project CVSA …" pattern
by replacing the current line `og:title: 一次完整爬取的生命周期` with the unified format
(for example `og:title: Project CVSA — 一次完整爬取的生命周期`), editing the `og:title`
metadata entry in the markdown header so social preview titles are consistent.

---

以一个**新发现的B站视频**（aid=12345）为例，展示从发现到持续追踪的完整流程。
Expand Down
3 changes: 2 additions & 1 deletion apps/docs/content/internal/legacy/database-schema-reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
---
title: 核心数据表
description: 爬虫系统关键数据表的结构与用途
description: 爬虫系统关键数据表的结构与用途。
og:title: Project CVSA 核心数据表
---

## snapshot_schedule
Expand Down
Loading