Skip to content

refactor(docs): cpp_backend 目录树规范化 — 下划线/大驼峰 → kebab-case#309

Closed
longsizhuo wants to merge 1 commit intomainfrom
feat/docs-filename-kebab-case
Closed

refactor(docs): cpp_backend 目录树规范化 — 下划线/大驼峰 → kebab-case#309
longsizhuo wants to merge 1 commit intomainfrom
feat/docs-filename-kebab-case

Conversation

@longsizhuo
Copy link
Copy Markdown
Member

背景

全站文档命名约定是 kebab-case,但 cpp_backend 整棵子树残留早期混用风格:

当前 规范化后
cpp_backend/ cpp-backend/
Handwritten_pool_components/ handwritten-pool-components/
easy_compile/ easy-compile/
1_Handwritten_threadpool.md 1-handwritten-threadpool.md
2_Handwritten_mempool1.md 2-handwritten-mempool1.md
1_cpp_libs.md / 2_base_gcc.md / 3_Make.md / 4_CMake.md / 5_vcpkg.md kebab 化
mempool_simple.mdx mempool-simple.mdx

保留数字前缀以维持 sidebar 阅读顺序(Fumadocs 按字母序排,去数字会打乱 1→5 教学顺序)。

变更

  • 3 个目录 rename
  • 8 份原文 + 7 份 .en.md 翻译 = 17 个文件 git mv
  • next.config.mjs 新增 async redirects()8 条 301 映射
  • statusCode: 301(不是默认 permanent:true 的 308),Next.js 源码 allowedStatusCodes = {301,302,303,307,308} 合法

docId 守恒校验(✅ 全 8 个 docId 原样保留)

mempool-simple.mdx             → q8290wmhyofuiskzn1ph63ta
1-handwritten-threadpool.md    → mnjkrtrs7xk3fq538eqreuge
2-handwritten-mempool1.md      → xgxqqvglxyauoeh8eye7lzu6
1-cpp-libs.md                  → totx4pej5lhyt1nl4anwhakj
2-base-gcc.md                  → kyu85av71b4n07hbdycbhvj9
3-make.md                      → g6wucmr69lamd9xyxm7uunnd
4-cmake.md                     → xk44lx4q1gpcm1uqk8nnbg7q
5-vcpkg.md                     → gtqamuq3tftmvzstbunkgbo5

(.en.md 翻译版 docId 与原文一致,验证通过)

Reviewer subagent 发现 + 处理

误报 1:指 statusCode: 301 不是 Next.js 合法 API。
→ 经查 node_modules/next/dist/lib/redirect-status.jsallowedStatusCodes = new Set([301,302,303,307,308])statusCode 合法;statusCodepermanent 互斥,本 PR 只用前者合规。

非阻塞 1generated/doc-contributors.json / site-leaderboard.json 里有 stale path。
→ 这两个文件不应该手动改sync-uuid.yml workflow 在本 PR 合 main 后会自动跑 backfill + generate-leaderboard + commit 回 main(格式 chore(docs): sync doc metadata)。这是我们 JSON-as-source-of-truth 架构的设计点,本 PR 保持 CI 自动更新。

采纳:注释里 "HTTP/1.0 Moved Permanently" 措辞不严谨(301 在 HTTP/1.0 时代引入但不叫 HTTP/1.0 状态码),已改。

合并顺序

#307 / #308 完全独立(改不同目录,不同 URL)。谁先合都行。

测试计划

  • git rename detection 100% (17 个文件全部 R)
  • docId 守恒(8 个 docId 对照通过)
  • pnpm typecheck 通过
  • node eval redirects() 返回 8 条全 statusCode:301
  • 合 main 后 sync-uuid workflow 跑过,doc_paths 新路径加入并集,贡献者数不变
  • Vercel preview 实测老 URL → 301 → 新 URL(8 条)
  • multilingual 验证:preview 下 zh / en locale 看 cpp-backend 页面渲染

后续工作

  • Leetcode 系列 {题号}.中文题名_translated.md 的规范化(50+ 文件)——涉及 pinyin 路由映射,需要另外规划
  • ai/ 下的其他下划线目录(如 Introduction-of-Multi-agents-system/ 本身是 kebab 但内部文件用下划线)
  • CommunityShare/ 内部结构的进一步分类

背景:Involution Hell 文档站全站命名约定是 kebab-case,但 cpp_backend 整棵
子树残留早期混用风格:
- 下划线目录:cpp_backend / easy_compile
- 大驼峰目录:Handwritten_pool_components
- 下划线 + 大驼峰文件名:1_Handwritten_threadpool.md / 3_Make.md 等

批量规范化成 kebab-case,保留数字前缀以维持 sidebar 阅读顺序
(Fumadocs 按文件名字母序排 sidebar,去掉前缀会打乱 1→5 的教学顺序)。

变更:
- 3 个目录 rename
- 8 份原文 + 7 份 .en.md 翻译 = 17 个文件 git mv
- next.config.mjs 新增 async redirects(),8 条老 URL → 新 canonical 301 映射
  使用 statusCode:301(不是 permanent:true 的 308),两者 SEO 等价,选 301
  因识别最稳、和 PR 描述口径一致。Next.js 源码 allowedStatusCodes 里合法。

验证:
- git status 显示全部 R (rename),相似度 100%
- docId 守恒:grep "^docId:" 对照 8 个 docId 全部原样保留
- pnpm typecheck 通过
- node 实测 next.config.mjs 的 redirects() 返回 8 条全 statusCode:301

合并顺序:和 PR #307 / #308 独立,互不冲突(改动在完全不同的目录)。

流程:
1. 建分支 feat/docs-filename-kebab-case
2. mkdir 新目录 + git mv 17 个文件
3. rmdir 旧空目录
4. 加 301 redirects
5. reviewer subagent 审稿:误报 1(statusCode 实测 OK)+ 非阻塞 1
   (generated/ JSON 由 sync-uuid CI 自动 regen,不应手动改)
6. 采纳 reviewer 关于注释措辞的建议,修掉 "HTTP/1.0" 这个不准的词
Copilot AI review requested due to automatic review settings April 18, 2026 08:36
@vercel
Copy link
Copy Markdown

vercel Bot commented Apr 18, 2026

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)
involutionhell-github-io Ready Ready Preview, Comment Apr 18, 2026 8:48am
website-preview Ready Ready Preview, Comment Apr 18, 2026 8:48am

Copy link
Copy Markdown
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

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

Pull request overview

This PR normalizes the cpp_backend docs subtree naming to kebab-case (directories + filenames) while preserving ordering via numeric prefixes, and adds server-side redirects so existing indexed/bookmarked URLs keep working.

Changes:

  • Renamed cpp_backend subtree directories/files to kebab-case while keeping numeric prefixes for sidebar order.
  • Added 8 explicit 301 redirects in next.config.mjs mapping old doc routes to new canonical routes.
  • Moved/added the corresponding .en.* translated doc files alongside the renamed originals (docId preserved per description).

Reviewed changes

Copilot reviewed 1 out of 17 changed files in this pull request and generated no comments.

Show a summary per file
File Description
next.config.mjs Adds redirects() with 8 explicit 301 mappings for the renamed docs routes.
app/docs/computer-science/cpp-backend/mempool-simple.mdx Doc moved to kebab-case path/slug.
app/docs/computer-science/cpp-backend/mempool-simple.en.mdx English translation moved to kebab-case path/slug.
app/docs/computer-science/cpp-backend/handwritten-pool-components/1-handwritten-threadpool.md Doc moved to kebab-case directory + filename.
app/docs/computer-science/cpp-backend/handwritten-pool-components/1-handwritten-threadpool.en.md English translation moved to kebab-case directory + filename.
app/docs/computer-science/cpp-backend/handwritten-pool-components/2-handwritten-mempool1.md Doc moved to kebab-case directory + filename.
app/docs/computer-science/cpp-backend/handwritten-pool-components/2-handwritten-mempool1.en.md English translation moved to kebab-case directory + filename.
app/docs/computer-science/cpp-backend/easy-compile/1-cpp-libs.md Doc moved to kebab-case directory + filename.
app/docs/computer-science/cpp-backend/easy-compile/1-cpp-libs.en.md English translation moved to kebab-case directory + filename.
app/docs/computer-science/cpp-backend/easy-compile/2-base-gcc.md Doc moved to kebab-case directory + filename.
app/docs/computer-science/cpp-backend/easy-compile/2-base-gcc.en.md English translation moved to kebab-case directory + filename.
app/docs/computer-science/cpp-backend/easy-compile/3-make.md Doc moved to kebab-case directory + filename.
app/docs/computer-science/cpp-backend/easy-compile/3-make.en.md English translation moved to kebab-case directory + filename.
app/docs/computer-science/cpp-backend/easy-compile/4-cmake.md Doc moved to kebab-case directory + filename.
app/docs/computer-science/cpp-backend/easy-compile/4-cmake.en.md English translation moved to kebab-case directory + filename.
app/docs/computer-science/cpp-backend/easy-compile/5-vcpkg.md Doc moved to kebab-case directory + filename.
app/docs/computer-science/cpp-backend/easy-compile/5-vcpkg.en.md English translation moved to kebab-case directory + filename.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

@longsizhuo
Copy link
Copy Markdown
Member Author

已合并到 #307 (commit dd7bf83),改按 owner 要求三组 docs 整理放一个 PR 里方便 contributors review。

@longsizhuo longsizhuo closed this Apr 18, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants