diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f0a159671..fa313668a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,15 +1,17 @@ # 贡献指南 -感谢你对现代 C++ 教程的关注！我们欢迎任何形式的贡献，包括但不限于：修正错别字、改进代码示例、完善现有内容、添加新章节等。 +嘿！感谢您原因看看这一页！如果您发现了问题，却还在犹豫要不要自己手改。。。不必犹豫！我们欢迎您的到来！！！我们欢迎任何形式的贡献，包括但不限于：修正错别字、改进代码示例、完善现有内容、添加新章节等。 ## 快速开始 -1. Fork 本仓库 -2. 创建你的特性分支 (`git switch -c feature/amazing-feature`) -3. 安装 pre-commit 提交前检查 (`pnpm hooks:install` 或 `scripts/setup_precommit.sh`) -4. 提交更改 (`git commit -m '添加某功能'`) +说的道理，您可以这样开始！ + +1. 点点 Github 仓库的 Fork，把他克隆下来， +2. 强烈建议创建属于您的分支，您会Git的话，就请`git switch -c feature/amazing-feature` +3. 我们建议您安装 pre-commit 提交前检查 (`pnpm hooks:install` 或 `scripts/setup_precommit.sh`)，因为这样的话，您可以在提交之前，就抓到触发CI构建前的一些问题——除非CI通过，否则我们不会审查您的PR~。 +4. 提交您的更改：提交更改 (`git commit -m '我做了超级牛逼的工作'`) 5. 推送到分支 (`git push origin feature/amazing-feature`) -6. 创建 Pull Request +6. 您的fork仓库，会出现Contribute to...，是的，贡献到我们的main分支上！创建您的PR，然后静候我们的审查！ ## 提交前自动化 @@ -69,20 +71,20 @@ pre-commit 会在运行检查前临时隔离未暂存改动，避免把未准备 ### Frontmatter 元数据 -每篇文章必须包含以下元数据： - -| 字段 | 必填 | 说明 | -|------|------|------| -| `title` | 是 | 文章标题 | -| `description` | 是 | 一句话描述文章内容 | -| `chapter` | 是 | 所属章节 | -| `order` | 是 | 在章节中的顺序 | -| `tags` | 是 | 标签列表 | -| `difficulty` | 否 | 难度：beginner / intermediate / advanced | -| `reading_time_minutes` | 否 | 预计阅读时间（分钟） | -| `prerequisites` | 否 | 前置知识 | -| `related` | 否 | 相关文章 | -| `cpp_standard` | 否 | 涉及的 C++ 标准（如 [11, 14, 17, 20]） | +每篇文章必须包含以下元数据，这样的话，方便我们根据标签找内容（这个特性正在持续开发！但是我们CI检查会见检查的！） + +| 字段 | 必填 | 说明 | +| ---------------------- | ---- | ---------------------------------------- | +| `title` | 是 | 文章标题 | +| `description` | 是 | 一句话描述文章内容 | +| `chapter` | 是 | 所属章节 | +| `order` | 是 | 在章节中的顺序 | +| `tags` | 是 | 标签列表 | +| `difficulty` | 否 | 难度：beginner / intermediate / advanced | +| `reading_time_minutes` | 否 | 预计阅读时间（分钟） | +| `prerequisites` | 否 | 前置知识 | +| `related` | 否 | 相关文章 | +| `cpp_standard` | 否 | 涉及的 C++ 标准（如 [11, 14, 17, 20]） | ### 目录组织 @@ -100,17 +102,11 @@ documents/vol2-modern-features/ # 卷二目录 ### 写作风格 -1. **语言**：使用清晰、简洁的中文 -2. **术语**：首次出现的技术术语应附英文原文 -3. **代码注释**：使用中文注释 -4. **标题层级**：不超过 4 级（`####`） -5. **篇幅**：每篇文章控制在 1500-3000 字 - -> 完整的写作人格、语气规则、文章骨架与代码风格见 [`.claude/style/writing-style.md`](.claude/style/writing-style.md)(项目作者的真实写作声音,贡献时尽量贴合)。 +完整的写作人格、语气规则、文章骨架与代码风格见 [`.claude/style/writing-style.md`](.claude/style/writing-style.md)(建议！当然如果您是投稿随意！毕竟这个文章是您的！但是通用教程还请保持文风的一致性！)。 ## 自定义 Vue 组件 -文档站注册了若干自定义 Vue 组件，可在 Markdown 中直接使用。 +文档站注册了若干自定义 Vue 组件，可在 Markdown 中直接使用。关于这个，您可以摇一摇您的Agent，或者是自行看看site/.vitepress/theme/components/下的所有 Vue 组件。 ### 导航组件（全站通用） @@ -123,11 +119,11 @@ documents/vol2-modern-features/ # 卷二目录 ``` -| 组件 | Prop | 类型 | 说明 | -|------|------|------|------| -| `ChapterNav` | `variant` | `'main'` \| `'sub'` | 布局样式，sub 用于子目录，默认 main | -| `ChapterLink` | `num` | string \| number | 章节编号（仅 main 变体显示） | -| `ChapterLink` | `href` | string | 链接路径，**不要**以 `.md` 结尾 | +| 组件 | Prop | 类型 | 说明 | +| ------------- | --------- | ------------------- | ----------------------------------- | +| `ChapterNav` | `variant` | `'main'` \| `'sub'` | 布局样式，sub 用于子目录，默认 main | +| `ChapterLink` | `num` | string \| number | 章节编号（仅 main 变体显示） | +| `ChapterLink` | `href` | string | 链接路径，**不要**以 `.md` 结尾 | ### 参考文献组件（全站通用） @@ -155,18 +151,18 @@ documents/vol2-modern-features/ # 卷二目录 ``` -| 组件 | Prop | 类型 | 说明 | -|------|------|------|------| -| `RefLink` | `id` | number \| string | 引用编号，与 ReferenceItem 的 id 对应 | -| `RefLink` | `preview` | string | 鼠标悬停时的预览文字 | -| `ReferenceCard` | `title` | string | 卡片标题，默认"参考文献" | -| `ReferenceItem` | `id` | number \| string | 引用编号，页内锚点 | -| `ReferenceItem` | `author` | string | 作者 | -| `ReferenceItem` | `title` | string | 文献标题（必填） | -| `ReferenceItem` | `publisher` | string | 出版者 | -| `ReferenceItem` | `year` | number \| string | 年份 | -| `ReferenceItem` | `chapter` | string | 章节或备注信息 | -| `ReferenceItem` | `url` | string | 外部链接 | +| 组件 | Prop | 类型 | 说明 | +| --------------- | ----------- | ---------------- | ------------------------------------- | +| `RefLink` | `id` | number \| string | 引用编号，与 ReferenceItem 的 id 对应 | +| `RefLink` | `preview` | string | 鼠标悬停时的预览文字 | +| `ReferenceCard` | `title` | string | 卡片标题，默认"参考文献" | +| `ReferenceItem` | `id` | number \| string | 引用编号，页内锚点 | +| `ReferenceItem` | `author` | string | 作者 | +| `ReferenceItem` | `title` | string | 文献标题（必填） | +| `ReferenceItem` | `publisher` | string | 出版者 | +| `ReferenceItem` | `year` | number \| string | 年份 | +| `ReferenceItem` | `chapter` | string | 章节或备注信息 | +| `ReferenceItem` | `url` | string | 外部链接 | ### 演讲信息卡片（卷十专用） @@ -183,15 +179,15 @@ documents/vol2-modern-features/ # 卷二目录 /> ``` -| Prop | 类型 | 说明 | -|------|------|------| -| `talkTitle` | string | 演讲标题（必填） | -| `speaker` | string | 演讲者（必填） | -| `conference` | string | 会议标识（必填）：`cppcon` \| `cppnow` \| `meetingpp` \| `course` \| `blog` | -| `year` | number \| string | 年份（必填） | -| `videoBilibili` | string | Bilibili 视频链接 | -| `videoYoutube` | string | YouTube 视频链接 | -| `slidesUrl` | string | 幻灯片链接 | +| Prop | 类型 | 说明 | +| --------------- | ---------------- | --------------------------------------------------------------------------- | +| `talkTitle` | string | 演讲标题（必填） | +| `speaker` | string | 演讲者（必填） | +| `conference` | string | 会议标识（必填）：`cppcon` \| `cppnow` \| `meetingpp` \| `course` \| `blog` | +| `year` | number \| string | 年份（必填） | +| `videoBilibili` | string | Bilibili 视频链接 | +| `videoYoutube` | string | YouTube 视频链接 | +| `slidesUrl` | string | 幻灯片链接 | 组件源码位于 `site/.vitepress/theme/components/`。 @@ -199,8 +195,8 @@ documents/vol2-modern-features/ # 卷二目录 ### C++ 代码风格 -1. 使用现代 C++ 风格（C++11 及以上） -2. 优先使用 `auto`、范围 for 循环等现代特性 +1. 除非咱们真的在讲C++98，我们建议您使用现代 C++ 风格（C++11 及以上） +2. 优先使用 `auto`、范围 for 循环等现代特性，这很重要，ModernCPP还是Modern一些~ 3. 标注适用的 C++ 标准 4. 代码示例使用 CMake 构建，确保可独立编译 @@ -254,22 +250,10 @@ documents/community/incoming/ 1. 初步通过基础检查后，文章进入 `documents/community/incoming/`，可在文档站展示，并可被 TAMCPP 周报引用。 2. 经过社区讨论、语法修订和技术审阅后，文章可移动到 `documents/community/articles/` 长期收录。 -3. 如果文章非常适合主线教程，维护者可进一步整理进对应卷或章节。 +3. 如果文章非常适合主线教程，我们会进一步整理进对应卷或章节。 社区初刊不代表最终定稿，但上线前仍需满足基本要求：内容可以正常渲染、没有明显技术硬伤、来源和引用清楚、作者同意公开展示。 -## 发布前检查清单 - -提交 PR 前，请确认： - -- [ ] Frontmatter 元数据完整 -- [ ] 代码示例可编译 -- [ ] 无错别字 -- [ ] 内部链接有效 -- [ ] 标签使用规范 -- [ ] 遵循文章模板结构 -- [ ] 更新了卷首页索引（如适用） - ## 本地预览 在提交前，建议本地预览文档： @@ -290,9 +274,9 @@ pnpm dev ## 代码审查流程 -1. 所有 PR 需要至少一位维护者审核 +1. 所有 PR 需要至少一位维护者审核（目前是笔者QAQ） 2. CI 检查必须通过（markdown lint、链接检查） -3. 审核通过后，维护者将合并代码 +3. 恭喜，您的审查通过咯！欢迎加入我们！ ## 社区协作规则 @@ -353,14 +337,14 @@ QA 不替代正文，只负责解答常见分叉问题和高频误区。 我们同样重视非代码形式的贡献！以下贡献方式均会被记录在 [CONTRIBUTORS.md](./CONTRIBUTORS.md) 中： -| 贡献类型 | 说明 | 如何参与 | -|---------|------|---------| -| 界面设计 | 文档站 UI/UX 优化 | 通过 Issue 提交设计方案 | -| 插画配图 | 教程插图、架构图 | 通过 Issue 或邮件提交 | +| 贡献类型 | 说明 | 如何参与 | +| -------- | -------------------- | --------------------------------- | +| 界面设计 | 文档站 UI/UX 优化 | 通过 Issue 提交设计方案 | +| 插画配图 | 教程插图、架构图 | 通过 Issue 或邮件提交 | | 问题反馈 | 发现错误或不准确之处 | 提交 Issue 或通过微信/QQ/邮件反馈 | | 内容建议 | 新主题建议、改进意见 | 提交 Issue 或通过微信/QQ/邮件反馈 | -| 内容审阅 | 技术校对、审阅 | 通过 Issue 或邮件参与 | -| 翻译 | 英文翻译 | 通过 PR 提交 | +| 内容审阅 | 技术校对、审阅 | 通过 Issue 或邮件参与 | +| 翻译 | 英文翻译 | 通过 PR 提交 | ### 匿名贡献 @@ -383,16 +367,16 @@ QA 不替代正文，只负责解答常见分叉问题和高频误区。 ## 行为准则 -- 尊重所有贡献者 -- 建设性的反馈和讨论 -- 专注于对项目最有利的事情 +- 还尊重所有贡献者，各位都是用爱发电，我们不会考虑展开任何收费形式。“这个时代的知识应当是免费的” +- 还请建设性的反馈和讨论，我们欢迎吐槽（类似你这是不是AI写的哇？我们甚至都欢迎，说明文章质量告警，我们要加班处理了！但是攻击性的话语还请收一下，公共场合，不必骂街~） +- 专注于对项目最有利的事情（各位对事不对人） -## 获取帮助 +## 坏了，你没有解答我的问题 -如有问题，请： +Sir! This Way! - 提交 [GitHub Issue](https://github.com/Awesome-Embedded-Learning-Studio/Tutorial_AwesomeModernCPP/issues) -- 发送邮件至：725610365@qq.com +- 直接对着这个邮箱塞邮件：725610365@qq.com --- diff --git a/README.en.md b/README.en.md index ed9e6e9e4..096406cf2 100644 --- a/README.en.md +++ b/README.en.md @@ -40,15 +40,15 @@ - + - - + + - +

🔧 From syntax to silicon

Go beyond desktop C++ — hands-on STM32F1 embedded: register access, interrupt safety, zero-overhead abstraction, cross-compilation & linker scripts.

⚡ Real, runnable examples

CMake projects validated in CI — not unbuildable snippets stranded in articles.

🧪 Crash Lab

Deliberately broken crash.cpp, the repaired fixed.cpp, and a step-by-step debugging trail — watch it crash, then corner the culprit.

📚 One complete path

10 volumes, 430+ articles — fundamentals → modern features → standard library → advanced → concurrency → performance → engineering → domains.

🚀 C++23 current

Covers and practices concepts, coroutines, ranges and more — not stuck at C++11.

💻 No board? Blink it anyway

Renode is the main verification environment: one command runs your first firmware on a virtual Blue Pill, register sampling proving the LED really blinks.

📇 C++ feature reference cards

One card per feature, C++98 through C++23 — grab the syntax you forgot without digging back through a whole chapter.

🔍 Read real code, real talks

Vol.9 studies Chromium (e.g. OnceCallback); Vol.10 is reading notes on CppCon and other talks.

🌐 Engineered + bilingual

VitePress (search / dark mode / GitHub Pages auto-deploy) + Chinese main line + English translation + C++98→23 reference cards.

🌐 Engineered + bilingual

VitePress (search / dark mode / GitHub Pages auto-deploy) + Chinese main line + English translation.
@@ -94,23 +94,23 @@ The visual roadmap (ten-volume content map + learning paths by background) is in ### Volume overview -Core volumes are complete, advanced ones are still being filled in — progress in the open (counts are a snapshot and change as content grows): - -| Volume | Topic | Articles | Maturity | -|--------|-------|:--------:|----------| -| Vol 1 | Fundamentals (incl. C crash-course) | 87 | ✅ Complete | -| Vol 2 | Modern features (RAII / smart pointers / move / lambda) | 44 | ✅ Complete | -| Vol 3 | Standard library in depth | 40 | ✅ Complete | -| Vol 4 | Advanced (concepts / coroutines / templates / design patterns) | 29 | 🔨 In progress | -| Vol 5 | Concurrency | 44 | ✅ Complete | -| Vol 6 | Performance | 38 | ✅ Complete | -| Vol 7 | Engineering (CMake / toolchain / debugging) | 8 | 🔨 In progress | -| Vol 8 | Domains (embedded / networking / GUI / storage) | 75 | ✅ Complete | -| Vol 9 | Open-source code study (Chromium etc.) | 55 | 📚 Ongoing | -| Vol 10 | Talk & course notes (CppCon etc.) | 17 | 📚 Ongoing | - -> Plus "Compilation & Linking" (11) and C++ feature reference cards (46). Most core volumes are complete; the rest are being filled in. - +Core volumes are complete, advanced ones are still being filled in — progress in the open: + +| Volume | Topic | Maturity | +|--------|-------|----------| +| Vol 1 | Fundamentals (incl. C crash-course) | ✅ Complete | +| Vol 2 | Modern features (RAII / smart pointers / move / lambda) | ✅ Complete | +| Vol 3 | Standard library in depth | ✅ Complete | +| Vol 4 | Advanced (concepts / coroutines / templates / design patterns) | 🔨 In progress | +| Vol 5 | Concurrency | ✅ Complete | +| Vol 6 | Performance | ✅ Complete | +| Vol 7 | Engineering (CMake / toolchain / debugging) | 🔨 In progress | +| Vol 8 | Domains (embedded / TinyML / networking) | 🔨 In progress | +| Vol 9 | Open-source code study (Chromium etc.) | 📚 Ongoing | +| Vol 10 | Talk & course notes (CppCon etc.) | 📚 Ongoing | + +> Plus Getting Started, the "Compilation & Linking" series, Crash Lab, community articles, and C++ feature reference cards. +> > 📋 For volume content and progress see the [project roadmap](todo/000-project-roadmap.md); for release history see [changelogs/](changelogs/). ## Local Development and Checks diff --git a/README.md b/README.md index 781064bbb..9e0724346 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ [English](README.en.md) | 中文 -> 一套面向工程实践的现代 C++ 系统教程：从 C/C++ 基础、现代语言特性，到并发、性能、工程化、嵌入式实战与开源项目研读。 +> 一个持续建设的，面向工程实践的现代 C++ 系统教程：从 C/C++ 基础、到现代C++语言特性，再到标准库、并发、性能、工程化、领域应用与开源项目研读。持续的进步中！ > 试一试点一下下面的图片？

@@ -23,11 +23,11 @@ ![English Coverage](https://img.shields.io/badge/en_coverage-97%25-green.svg) 578/593 docs translated -## 这是什么项目 +## 嘿！这是什么？ -

一套系统化的现代 C++ 教程——从语法到芯片，把现代 C++ 写进桌面、STM32 嵌入式与工业级开源项目。

+

这是一套正在持续进步的，系统化的现代 C++ 教程——从语法到芯片，把现代 C++ 写进桌面、STM32 嵌入式与工业级开源项目。

-10 卷、430+ 篇，从 C/C++ 基础一路讲到并发、性能、工程与领域实战；每个关键概念都配可在 CI 中编译验证的 CMake 示例，不是文章里跑不起来的孤立片段。 +10 卷、从 C/C++ 基础一路讲到并发、性能、工程与领域实战，我们尝试将每一个概念转化为具体的代码，丢到CI机器验证（孩子们真没出错）

articles @@ -36,22 +36,26 @@ examples

-**适合谁？** 正在系统学 C/C++ · 有 C 或嵌入式经验 · 已会 C++ 想补齐工程能力 +## 谁可以来？ + +正在打算系统的学 C/C++ 的 bro 们 · 有 C 或嵌入式经验的 bro 们 · 已会 C++ 想补齐工程能力的 bro 们 + +**适合谁？** ## 特色亮点 - + - - + + - +

🔧 从语法到芯片

深入 STM32F1 嵌入式——寄存器访问、中断安全、零开销抽象、交叉编译与链接脚本，打通裸机。

⚡ 克隆即跑的真示例

代码以 CMake 工程组织、CI 构建验证，不是文章里跑不起来的伪代码片段。

🧪 崩溃实验室

故意写崩的代码、修好的版本、一步步排查的实录——空指针、释放后使用，先崩给您看，再带您破案。

📚 一条完整路径

10 卷 430+ 篇，基础→现代特性→标准库→高级→并发→性能→工程→领域，层层递进、不碎片。

🚀 紧跟 C++23

讲解并实践 concepts、协程、ranges 等新特性，不停在 C++11。

💻 不买板子，先点灯

嵌入式线以 Renode 模拟器为主验证环境：一条命令让固件在虚拟 Blue Pill 上跑起来，寄存器采样证明 LED 真的在闪。

📇 C++ 特性参考卡

C++98→23 一特性一卡，忘了语法随手查，不用翻回整章教程。

🔍 读真源码 · 读真会议

卷九研读 Chromium（如 OnceCallback），卷十是 CppCon 等会议演讲的读书笔记。

🌐 工程化 + 双语

VitePress（搜索 / 暗色 / GitHub Pages 自动部署）+ 中文主线 + 英文翻译 + C++98→23 特性参考卡。

🌐 工程化 + 双语

VitePress（搜索 / 暗色 / GitHub Pages 自动部署）+ 中文主线 + 英文翻译。
@@ -60,9 +64,6 @@ 最快的方式是直接阅读在线文档： - [在线文档站](https://awesome-embedded-learning-studio.github.io/Tutorial_AwesomeModernCPP/) -- [C++ 特性参考卡](https://awesome-embedded-learning-studio.github.io/Tutorial_AwesomeModernCPP/cpp-reference/) -- [嵌入式开发专题](https://awesome-embedded-learning-studio.github.io/Tutorial_AwesomeModernCPP/vol8-domains/embedded/) -- [社区文章](https://awesome-embedded-learning-studio.github.io/Tutorial_AwesomeModernCPP/community/) 本地预览文档站： @@ -73,11 +74,13 @@ cd Tutorial_AwesomeModernCPP pnpm install pnpm dev # 访问 http://localhost:5173/Tutorial_AwesomeModernCPP/ +# 如果你是在WSL中，可能需要pnpm dev --host！ ``` 生产构建与预览： ```bash +# 如果您的CPU核心大于4，我们推介加速构建，默认的构建脚本是为CI服务的，Github分配的机器有点小qaq BUILD_CONCURRENCY=8 pnpm build pnpm preview # 访问 http://localhost:4173/Tutorial_AwesomeModernCPP/ @@ -97,23 +100,23 @@ cmake -S code/examples/chapter05/06_array_vs_stdarray -B build && cmake --build ### 各卷一览 -主线卷已成型，进阶卷持续补充——不藏进度（篇数为快照，随更新变化）： - -| 卷 | 主题 | 篇数 | 成熟度 | -|----|------|:----:|--------| -| 卷一 | 基础入门（含 C 速通） | 87 | ✅ 成型 | -| 卷二 | 现代特性（RAII / 智能指针 / 移动 / lambda） | 44 | ✅ 成型 | -| 卷三 | 标准库深入 | 40 | ✅ 成型 | -| 卷四 | 高级主题（concepts / 协程 / 模板 / 设计模式） | 29 | 🔨 在建 | -| 卷五 | 并发编程 | 44 | ✅ 成型 | -| 卷六 | 性能优化 | 38 | ✅ 成型 | -| 卷七 | 工程实践（CMake / 工具链 / 调试） | 8 | 🔨 在建 | -| 卷八 | 领域应用（嵌入式 / GUI / 存储等） | 75 | ✅ 成型 | -| 卷九 | 开源项目研读（Chromium 等） | 55 | 📚 持续更新 | -| 卷十 | 课程与演讲笔记（CppCon 等） | 17 | 📚 持续更新 | - -> 另含「编译与链接」11 篇、C++ 特性参考卡 46 张。主线已成型的卷占多数，其余在持续补充。 - +主线卷已成型，进阶卷持续补充——不藏进度： + +| 卷 | 主题 | 成熟度 | +| ---- | --------------------------------------------- | ---------- | +| 卷一 | 基础入门（含 C 速通） | ✅ 成型 | +| 卷二 | 现代特性（RAII / 智能指针 / 移动 / lambda） | ✅ 成型 | +| 卷三 | 标准库深入 | ✅ 成型 | +| 卷四 | 高级主题（concepts / 协程 / 模板 / 设计模式） | 🔨 在建 | +| 卷五 | 并发编程 | ✅ 成型 | +| 卷六 | 性能优化 | ✅ 成型 | +| 卷七 | 工程实践（CMake / 工具链 / 调试） | 🔨 在建 | +| 卷八 | 领域应用（嵌入式 / TinyML / 网络等） | 🔨 在建 | +| 卷九 | 开源项目研读（Chromium 等） | 📚 持续更新 | +| 卷十 | 课程与演讲笔记（CppCon 等） | 📚 持续更新 | + +> 另含新手起步、「编译与链接」专题、崩溃实验室、社区文章与 C++ 特性参考卡。 +> > 📋 各卷内容与进度见 [项目总路线图](todo/000-project-roadmap.md)，版本变更见 [changelogs/](changelogs/)。 ## 本地开发与质量检查 @@ -121,20 +124,20 @@ cmake -S code/examples/chapter05/06_array_vs_stdarray -B build && cmake --build
常用命令 -| 命令 / 脚本 | 功能 | -|-------------|------| -| `pnpm dev` | 启动 VitePress 开发服务器，支持热更新 | -| `pnpm build` | 生产构建，按分卷并行构建并合并搜索索引 | -| `pnpm build:single` | 使用 VitePress 单体构建 | -| `pnpm check:links` | 检查 Markdown 与组件内部链接有效性 | -| `pnpm preview` | 预览生产构建结果 | -| `pnpm hooks:install` / `scripts/setup_precommit.sh` | 安装 pre-commit 提交前检查 | -| `pnpm coverage` | 查看英文翻译覆盖率 | -| `pnpm coverage:update` | 更新 `README.md` 中的英文翻译覆盖率徽章 | -| `.venv/bin/python scripts/validate_frontmatter.py` | 验证文章 frontmatter | -| `.venv/bin/python scripts/check_quality.py documents/` | 内容质量检查 | -| `.venv/bin/python scripts/build_examples.py --host` | 编译主机侧 CMake 示例 | -| `.venv/bin/python scripts/build_examples.py --stm32` | 编译 STM32 示例工程 | +| 命令 / 脚本 | 功能 | +| ------------------------------------------------------ | -------------------------------------------------------------------------------- | +| `pnpm dev` | 启动 VitePress 开发服务器，支持热更新（PS：WSL看不到的朋友记得加一个--host穿透） | +| `pnpm build` | 生产构建，按分卷并行构建并合并搜索索引 | +| `pnpm build:single` | 使用 VitePress 单体构建 | +| `pnpm check:links` | 检查 Markdown 与组件内部链接有效性 | +| `pnpm preview` | 预览生产构建结果 | +| `pnpm hooks:install` / `scripts/setup_precommit.sh` | 安装 pre-commit 提交前检查 | +| `pnpm coverage` | 查看英文翻译覆盖率 | +| `pnpm coverage:update` | 更新 `README.md` 中的英文翻译覆盖率徽章 | +| `.venv/bin/python scripts/validate_frontmatter.py` | 验证文章 frontmatter | +| `.venv/bin/python scripts/check_quality.py documents/` | 内容质量检查 | +| `.venv/bin/python scripts/build_examples.py --host` | 编译主机侧 CMake 示例 | +| `.venv/bin/python scripts/build_examples.py --stm32` | 编译 STM32 示例工程 |
@@ -155,25 +158,16 @@ cmake -S code/examples/chapter05/06_array_vs_stdarray -B build && cmake --build 完整变更记录见 [changelogs/](changelogs/)。 -**分支说明** - -| 分支 | 用途 | 状态 | -|------|------|------| -| `main` | 主开发分支 | Active | -| `archive/legacy_20260415` | 重构前存档 | Read-only | - -## 用 AI Agent 辅助（可选） +## 如果你是维新派。。。可以使用 AI Agent 辅助！ -本项目对 AI coding agent 开箱即用，也欢迎用 agent 辅助学习与贡献： +本项目对 AI coding agent 开箱即用，也欢迎用 Agent 辅助学习与贡献！ - 🤖 [AGENTS.md](./AGENTS.md) —— 跨 agent 通用入口（Claude Code / Cursor / Copilot / Codex 等都读它） - 📚 [用 agent 辅助 C++ 学习](./.github/learning-with-agents.md) + [C++ 常见误解 FAQ](./.github/faq.md) - ✍️ Claude 专属资产（写作风格 / 审查命令 / hooks）见 [CLAUDE.md](./CLAUDE.md) -> 不用 agent？忽略这些文件即可，主线教程与示例不依赖它们。 - ## 贡献 欢迎修正文档、改进示例、补充章节、校对翻译、提交问题、提出内容建议，或向 [社区文章](https://awesome-embedded-learning-studio.github.io/Tutorial_AwesomeModernCPP/community/) 投稿。请先阅读 [CONTRIBUTING.md](./CONTRIBUTING.md)。 @@ -184,13 +178,13 @@ cmake -S code/examples/chapter05/06_array_vs_stdarray -B build && cmake --build ## 贡献者 -感谢所有为本项目做出贡献的人！详见 [CONTRIBUTORS.md](./CONTRIBUTORS.md)。 +这里感谢所有为本项目做出贡献的人！详见 [CONTRIBUTORS.md](./CONTRIBUTORS.md)。 > 贡献方式不限于代码，包括界面设计、插画、问题反馈、内容建议等。详见 [CONTRIBUTING.md](./CONTRIBUTING.md)。 ## 致谢 -本项目参考了以下优秀资源： +这个项目极大的受到下面这些项目和网站的启发，致敬前辈！ - [modern-cpp-tutorial](https://github.com/changkun/modern-cpp-tutorial) - [CPlusPlusThings](https://github.com/Light-City/CPlusPlusThings) @@ -199,7 +193,7 @@ cmake -S code/examples/chapter05/06_array_vs_stdarray -B build && cmake --build ## 许可证与联系方式 -- **许可证**：[MIT License](./LICENSE) -- **Issues**：[提交问题](https://github.com/Awesome-Embedded-Learning-Studio/Tutorial_AwesomeModernCPP/issues) +- **许可证**：[MIT License](./LICENSE)，随便改，fork，分发 +- **Issues**：[提交问题](https://github.com/Awesome-Embedded-Learning-Studio/Tutorial_AwesomeModernCPP/issues)，遇到任何疑问，或者发现代码存在显著问题，随意提，第一时间响应。 - **Email**：<725610365@qq.com> -- **组织**：[Awesome-Embedded-Learning-Studio](https://github.com/Awesome-Embedded-Learning-Studio) +- **组织**：隶属于[Awesome-Embedded-Learning-Studio](https://github.com/Awesome-Embedded-Learning-Studio) diff --git a/documents/en/index.md b/documents/en/index.md index aa3f0e89a..3eb552838 100644 --- a/documents/en/index.md +++ b/documents/en/index.md @@ -9,6 +9,9 @@ hero: tagline: "More than a syntax cheat-sheet — a complete path from fundamentals to engineering practice." actions: - theme: brand + text: Start from Zero + link: /en/getting-started/ + - theme: alt text: Start Learning link: /en/vol1-fundamentals/ - theme: alt @@ -22,6 +25,12 @@ hero: link: https://github.com/Awesome-Embedded-Learning-Studio/Tutorial_AwesomeModernCPP features: + - title: "Getting Started" + details: "Never written code before? Install a toolchain, get your first C++ program running, and teach vscode to understand it — six hands-on articles, mouse-first with commands tucked into fold-out boxes." + icon: '' + link: /en/getting-started/ + linkText: Start Reading + - title: "Vol.1 · Fundamentals" details: "Learn C++ fundamentals systematically from scratch. Suitable for absolute beginners." icon: '' @@ -65,7 +74,7 @@ features: linkText: Start Reading - title: "Vol.8 · Domain Applications" - details: "Practical applications of modern C++ across domains: embedded systems, networking, GUI, and data storage." + details: "Practical applications of modern C++ across domains: embedded systems, TinyML inference, networking, and C++ deep dives." icon: '' link: /en/vol8-domains/ linkText: Start Reading @@ -95,7 +104,7 @@ features: linkText: Enter the Lab - title: "Capstone Projects" - details: "Hands-on projects: hand-written STL components, a mini HTTP server, a GUI framework, an embedded OS, and more." + details: "Tie the volumes together into full projects: a coroutine echo server, a mini runtime, and an INI parser are ready to build on; hand-written STL components and a mini HTTP server are on the roadmap." icon: '' link: /en/projects/ linkText: Start Reading diff --git a/documents/images/screenshots/.gitkeep b/documents/images/screenshots/.gitkeep deleted file mode 100644 index 329765f0f..000000000 --- a/documents/images/screenshots/.gitkeep +++ /dev/null @@ -1,4 +0,0 @@ -# Screenshot assets for the home-page carousel. -# Drop captures here with the agreed names: 01-home, 02-article-code, 03-embedded, -# 04-cpp-reference, 05-roadmap, 06-dark-search (+ optional 07-cppcon-notes, 08-english). -# Delete this file once real images exist. diff --git a/documents/images/screenshots/01-home.png b/documents/images/screenshots/01-home.png index 4718b1a53..d8cded351 100644 Binary files a/documents/images/screenshots/01-home.png and b/documents/images/screenshots/01-home.png differ diff --git a/documents/index.md b/documents/index.md index b8f1183af..934f768ce 100644 --- a/documents/index.md +++ b/documents/index.md @@ -1,24 +1,24 @@ --- layout: home -title: "欢迎来到现代 C++ 教程" -description: "系统化的现代 C++ 教程 — 从基础入门到领域实战" +title: "欢迎来到现代C++的世界！" +description: "一个正在努力进步的，系统化的现代 C++ 教程" hero: name: "现代 C++ 教程" text: "Modern C++ Tutorial" - tagline: "不止于语法速查 —— 从基础到工程实战的一条完整现代 C++ 路径" + tagline: "不只是语法 —— 挑战走出从基础，到工程阅读，再到领域实战的一条完整现代 C++ 路径" actions: - theme: brand - text: 零基础起步 + text: 新手来这里！ link: /getting-started/ - theme: alt - text: 直接学语法 + text: C++语法第一关，启动！ link: /vol1-fundamentals/ - theme: alt - text: 查看路线图 + text: 我们的路由图！ link: /roadmap/ - theme: alt - text: GitHub + text: 点我去GitHub！ link: https://github.com/Awesome-Embedded-Learning-Studio/Tutorial_AwesomeModernCPP features: @@ -71,7 +71,7 @@ features: linkText: 开始阅读 - title: "卷八 · 领域应用" - details: "现代 C++ 在各领域的实战应用：嵌入式、网络编程、GUI、数据存储。" + details: "现代 C++ 在各领域的实战应用：嵌入式、TinyML 推理、网络编程、C++ 深度专题。" icon: '' link: /vol8-domains/ linkText: 开始阅读 @@ -101,7 +101,7 @@ features: linkText: 进入实验室 - title: "贯穿式实战项目" - details: "手写 STL 组件、迷你 HTTP 服务器、GUI 框架、嵌入式 OS 等综合项目。" + details: "把各卷知识串成完整项目：协程服务器、迷你运行时、INI 解析器已就绪，手写 STL、迷你 HTTP 服务器在规划中。" icon: '' link: /projects/ linkText: 开始阅读 diff --git a/package.json b/package.json index 1b9e621ff..5d38afac7 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "tamcpp-exp-vitepress", - "version": "0.0.1", + "version": "0.10.0", "private": true, "type": "module", "packageManager": "pnpm@11.18.0", diff --git a/site/.vitepress/theme/components/HomeFeatureGrid.vue b/site/.vitepress/theme/components/HomeFeatureGrid.vue new file mode 100644 index 000000000..733e4886f --- /dev/null +++ b/site/.vitepress/theme/components/HomeFeatureGrid.vue @@ -0,0 +1,184 @@ + + + + + diff --git a/site/.vitepress/theme/components/HomePathExplorer.vue b/site/.vitepress/theme/components/HomePathExplorer.vue new file mode 100644 index 000000000..2d03a517b --- /dev/null +++ b/site/.vitepress/theme/components/HomePathExplorer.vue @@ -0,0 +1,301 @@ + + + + + diff --git a/site/.vitepress/theme/components/HomePathGraph.vue b/site/.vitepress/theme/components/HomePathGraph.vue new file mode 100644 index 000000000..9f46caf6b --- /dev/null +++ b/site/.vitepress/theme/components/HomePathGraph.vue @@ -0,0 +1,751 @@ + + + + + diff --git a/site/.vitepress/theme/components/HomeRoadmap.vue b/site/.vitepress/theme/components/HomeRoadmap.vue deleted file mode 100644 index 18e3bdf0c..000000000 --- a/site/.vitepress/theme/components/HomeRoadmap.vue +++ /dev/null @@ -1,245 +0,0 @@ - - - - - diff --git a/site/.vitepress/theme/components/ProofStrip.vue b/site/.vitepress/theme/components/ProofStrip.vue index b07096583..c03334de7 100644 --- a/site/.vitepress/theme/components/ProofStrip.vue +++ b/site/.vitepress/theme/components/ProofStrip.vue @@ -7,8 +7,8 @@ const isEn = computed(() => lang.value.startsWith('en')) const items = computed(() => isEn.value - ? ['350+ articles', 'C++11–23', 'Compilable CMake examples', 'STM32 embedded', 'Bilingual'] - : ['350+ 篇', 'C++11–23', '可编译 CMake 示例', 'STM32 嵌入式实战', '中英双语'], + ? ['10 volumes', 'C++11–23', 'Compilable CMake examples', 'STM32 embedded', 'Bilingual'] + : ['10 卷', 'C++11–23', '可编译 CMake 示例', 'STM32 嵌入式实战', '中英双语'], ) diff --git a/site/.vitepress/theme/custom.css b/site/.vitepress/theme/custom.css index def79df0c..8bb8ea595 100644 --- a/site/.vitepress/theme/custom.css +++ b/site/.vitepress/theme/custom.css @@ -1163,6 +1163,111 @@ html.dark .online-compiler-demo__source-highlight .shiki span { color: var(--vp-c-text-2) !important; } +/* ── Hero 按钮区:1 主 CTA + 图标化 ghost 快捷入口 ────────── + 设计意图:hero 只需要回答一个问题——新人从哪进。首行让 brand 主按钮独占 + (自然宽度,不拉伸),尾部一枚箭头指路;其余入口降级为第二行的 ghost 描边按钮, + 前置身份图标(书/地图/GitHub mark)区分去处,hover 才浮出钢蓝软底。 + 全部走自然宽度:胶囊天生按内容收缩,强行等宽会在短文字两侧留出空洞; + ghost 形态下 flex-wrap 换到哪行都成立,不再有"应该等宽却参差"的预期。 + 图标用 mask + background: currentColor,颜色随文字走(平时深灰、hover 钢蓝), + 与 feature 卡 rail/icon 同一套视觉语言。按钮文案一个字符不动。 + 类名加倍(.actions.actions/.action.action)抬高特异性,稳压 VitePress scoped + 的 [data-v] 同分规则,不赌样式注入顺序(同上文 .VPSidebar.VPSidebar 先例)。 */ +.VPHero .actions.actions { + display: flex; + flex-wrap: wrap; + align-items: center; + column-gap: 10px; + row-gap: 12px; + margin: 0; /* 抵消默认 -6px,间距统一交给 gap */ +} + +.VPHero .actions .action.action { + padding: 0; /* 抵消默认 6px(原与负 margin 配对) */ + min-width: 0; +} + +/* 主按钮独占首行:包裹层占满整行,按钮本身保持自然宽度,次按钮整体换行 */ +.VPHero .actions .action:first-child { + flex-basis: 100%; +} + +/* 主按钮尾部箭头(hover 前探,呼应 feature 卡 link-text-icon 的位移手法) */ +.VPHero .actions .action:first-child .VPButton::after { + content: ''; + display: inline-block; + width: 14px; + height: 14px; + margin-left: 8px; + vertical-align: -1.5px; + background-color: currentColor; + -webkit-mask: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='black' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpath d='M5 12h14M12 5l7 7-7 7'/%3E%3C/svg%3E") no-repeat center / contain; + mask: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='black' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpath d='M5 12h14M12 5l7 7-7 7'/%3E%3C/svg%3E") no-repeat center / contain; + transition: transform 0.25s ease; +} + +.VPHero .actions .action:first-child .VPButton:hover::after { + transform: translateX(3px); +} + +/* 次按钮 ghost 化:透明底 + 描边,把实底让给主按钮 */ +.VPHero .actions .action:not(:first-child) .VPButton.alt { + background-color: transparent; + border-color: var(--vp-c-border); + color: var(--vp-c-text-1); +} + +.VPHero .actions .action:not(:first-child) .VPButton.alt:hover { + border-color: var(--vp-c-brand-1); + color: var(--vp-c-brand-1); + background-color: var(--vp-c-brand-soft); +} + +.VPHero .actions .action:not(:first-child) .VPButton.alt:active { + border-color: var(--vp-c-brand-2); + color: var(--vp-c-brand-2); + background-color: var(--vp-c-brand-soft-2); +} + +/* 次按钮前置图标:形状装在 CSS 变量里,按位置分配(书/地图/GitHub)。 + mask 只取 alpha,颜色交给 currentColor → 跟文字一起变钢蓝。 */ +.VPHero .actions .action:not(:first-child) .VPButton::before { + content: ''; + display: inline-block; + width: 15px; + height: 15px; + margin-right: 7px; + vertical-align: -2px; + background-color: currentColor; + -webkit-mask: var(--hero-action-icon) no-repeat center / contain; + mask: var(--hero-action-icon) no-repeat center / contain; + flex-shrink: 0; +} + +.VPHero .actions .action:nth-child(2) { + --hero-action-icon: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='black' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpath d='M4 19.5v-15A2.5 2.5 0 0 1 6.5 2H20v20H6.5a2.5 2.5 0 0 1 0-5H20'/%3E%3C/svg%3E"); +} + +.VPHero .actions .action:nth-child(3) { + --hero-action-icon: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='black' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpath d='M3 6l6-3 6 3 6-3v15l-6 3-6-3-6 3z'/%3E%3Cpath d='M9 3v15M15 6v15'/%3E%3C/svg%3E"); +} + +.VPHero .actions .action:nth-child(4), +.VPHero .actions .action:nth-child(5) { + --hero-action-icon: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='black'%3E%3Cpath d='M12 .297c-6.63 0-12 5.373-12 12 0 5.303 3.438 9.8 8.205 11.385.6.113.82-.258.82-.577 0-.285-.01-1.04-.015-2.04-3.338.724-4.042-1.61-4.042-1.61C4.422 18.07 3.633 17.7 3.633 17.7c-1.087-.744.084-.729.084-.729 1.205.084 1.838 1.236 1.838 1.236 1.07 1.835 2.809 1.305 3.495.998.108-.776.417-1.305.76-1.605-2.665-.3-5.466-1.332-5.466-5.93 0-1.31.465-2.38 1.235-3.22-.135-.303-.54-1.523.105-3.176 0 0 1.005-.322 3.3 1.23.96-.267 1.98-.399 3-.405 1.02.006 2.04.138 3 .405 2.28-1.552 3.285-1.23 3.285-1.23.645 1.653.24 2.873.12 3.176.765.84 1.23 1.91 1.23 3.22 0 4.61-2.805 5.625-5.475 5.92.42.36.81 1.096.81 2.22 0 1.606-.015 2.896-.015 3.286 0 .315.21.69.825.57C20.565 22.092 24 17.592 24 12.297c0-6.627-5.373-12-12-12'/%3E%3C/svg%3E"); +} + +/* 未来按钮再多:第 6 个起没配图标,藏掉 ::before 占位,免得空 15px */ +.VPHero .actions .action:nth-child(n+6) .VPButton::before { + display: none; +} + +@media (prefers-reduced-motion: reduce) { + .VPHero .actions .action:first-child .VPButton::after { + transition: none; + } +} + /* ── Hero Image Slot: content card (HomeHeroVisual terminal) ── VitePress sizes .image-container as a fixed 320/392px square and gives .image large negative margins — both meant for a small decorative image with a @@ -1314,6 +1419,14 @@ html.dark .online-compiler-demo__source-highlight .shiki span { /* ── Features Grid ───────────────────────────────────────────── */ +/* VitePress 默认渲染的首页卡网格整体隐藏：16 卡已由 HomePathExplorer 的 + 「全部内容」视图(HomeFeatureGrid,读同一份 frontmatter)接管。 + .VPHomeFeatures 只在 layout: home 渲染(全仓仅中英两个首页),不影响其他页面; + 隐藏副本仍留在 DOM 中(SEO 无损),但移出 tab 序,交互归自渲染副本。 */ +.VPHomeFeatures { + display: none; +} + .VPFeatures { padding-top: 16px; padding-bottom: 48px; diff --git a/site/.vitepress/theme/home-path-data.ts b/site/.vitepress/theme/home-path-data.ts new file mode 100644 index 000000000..119d4f8ee --- /dev/null +++ b/site/.vitepress/theme/home-path-data.ts @@ -0,0 +1,128 @@ +/** + * 首页「学习路径图」种子数据（HomePathGraph.vue 消费）。 + * + * 语义来源：documents/roadmap/index.md 的三条学习路径（A 零基础 / B 有 C 经验 / C 已会 C++） + * 与 README 各卷一览的成熟度；节点 = 首页 features 的 16 项（卷级粒度，点击直达对应卷首页）。 + * 种子坐标是模块常量、SSG 直出；客户端拖拽后的布局存 localStorage（key 带 HOME_GRAPH_REVISION， + * 节点增删后递增版本号，旧布局自动失效回落种子）。 + * EN 链接 = CN href 统一加 /en 前缀，由组件补全（cleanUrls 开启，两套目录同构）。 + */ + +export type PathNodeKind = 'root' | 'proj' | 'sup' +export type PathEdgeKind = 'solid' | 'dash' | 'dot' +export type PathSide = 'top' | 'right' | 'bottom' | 'left' +export type PathRouteCoord = number | 'from' | 'to' +/** done=已成型 doing=在建/持续更新（镜像 README 各卷一览的两类成熟度） */ +export type PathStatus = 'done' | 'doing' +/** 配色三档，镜像 custom.css 首页卡片 rail 的 tier 分层（core=钢蓝 / eng=绿 / domain=紫） */ +export type PathTier = 'core' | 'eng' | 'domain' + +export interface Bi { + cn: string + en: string +} + +export interface PathNode { + /** 节点短 id（边的 from/to 用它） */ + id: string + name: Bi + sub: Bi + /** 种子坐标（中心点）与尺寸 */ + x: number + y: number + w: number + h: number + kind: PathNodeKind + status: PathStatus + tier: PathTier + /** CN 形态站内路径；EN 由组件补 '/en' 前缀后 withBase */ + href: string + /** 左上角标 */ + badge: string +} + +export interface PathEdge { + from: string + to: string + /** solid = 建议主线路径；dash = 按需选修；dot = 支撑/索引（不进悬停高亮链） */ + kind: PathEdgeKind + /** + * 默认布局的布线提示。from/to 选节点锚点，via 把边送入层间或外围的固定轨道； + * 坐标写 'from'/'to' 时跟随对应锚点，因此节点拖动后首尾段仍保持正交。 + */ + route?: { + from: PathSide + to: PathSide + via?: Array<{ x: PathRouteCoord; y: PathRouteCoord }> + } +} + +export interface PathBand { + label: Bi + top: number + bottom: number +} + +/** 画布尺寸（SVG viewBox） */ +export const VB_W = 1330 +export const VB_H = 856 + +/** localStorage 布局 key 版本：节点增删/坐标或默认布线大改时 +1 */ +export const HOME_GRAPH_REVISION = 2 + +export const HOME_PATH_BANDS: PathBand[] = [ + { label: { cn: 'B0 · 起点', en: 'B0 · Start' }, top: 16, bottom: 104 }, + { label: { cn: 'B1 · 基础与现代', en: 'B1 · Fundamentals & Modern' }, top: 138, bottom: 248 }, + { label: { cn: 'B2 · 标准库与高级', en: 'B2 · Stdlib & Advanced' }, top: 282, bottom: 392 }, + { label: { cn: 'B3 · 并发 · 性能 · 工程', en: 'B3 · Concurrency · Perf · Eng' }, top: 426, bottom: 546 }, + { label: { cn: 'B4 · 领域实战与深化', en: 'B4 · Domains & Deep Dive' }, top: 580, bottom: 700 }, + { label: { cn: 'B5 · 社区与索引', en: 'B5 · Community & Index' }, top: 734, bottom: 834 }, +] + +export const HOME_PATH_NODES: PathNode[] = [ + { id: 'gs', name: { cn: '新手起步', en: 'Getting Started' }, sub: { cn: '装环境 · 跑通第一课', en: 'Setup · first lesson' }, x: 665, y: 60, w: 180, h: 66, kind: 'root', status: 'done', tier: 'core', href: '/getting-started/', badge: 'GS' }, + { id: 'v1', name: { cn: '卷一 · 基础', en: 'Vol.1 Fundamentals' }, sub: { cn: '类型 · OOP · 模板', en: 'Types · OOP · templates' }, x: 340, y: 193, w: 160, h: 58, kind: 'proj', status: 'done', tier: 'core', href: '/vol1-fundamentals/', badge: 'V1' }, + { id: 'v2', name: { cn: '卷二 · 现代', en: 'Vol.2 Modern' }, sub: { cn: '移动 · 智能指针 · lambda', en: 'Move · smart ptr · lambda' }, x: 650, y: 193, w: 160, h: 58, kind: 'proj', status: 'done', tier: 'core', href: '/vol2-modern-features/', badge: 'V2' }, + { id: 'comp', name: { cn: '编译与链接', en: 'Compile & Link' }, sub: { cn: '编译 · 链接 · 符号', en: 'Build · link · symbols' }, x: 980, y: 193, w: 140, h: 46, kind: 'sup', status: 'done', tier: 'domain', href: '/compilation/', badge: 'CMP' }, + { id: 'v3', name: { cn: '卷三 · 标准库', en: 'Vol.3 Stdlib' }, sub: { cn: '容器 · 迭代器 · 算法', en: 'Containers · algorithms' }, x: 440, y: 337, w: 160, h: 58, kind: 'proj', status: 'done', tier: 'core', href: '/vol3-standard-library/', badge: 'V3' }, + { id: 'v4', name: { cn: '卷四 · 高级', en: 'Vol.4 Advanced' }, sub: { cn: 'concepts · 协程 · ranges', en: 'Concepts · coroutines' }, x: 820, y: 337, w: 160, h: 58, kind: 'proj', status: 'doing', tier: 'core', href: '/vol4-advanced/', badge: 'V4' }, + { id: 'v5', name: { cn: '卷五 · 并发', en: 'Vol.5 Concurrency' }, sub: { cn: '线程 · 原子 · 协程异步', en: 'Threads · atomics' }, x: 260, y: 486, w: 160, h: 58, kind: 'proj', status: 'done', tier: 'eng', href: '/vol5-concurrency/', badge: 'V5' }, + { id: 'v6', name: { cn: '卷六 · 性能', en: 'Vol.6 Performance' }, sub: { cn: '缓存 · SIMD · 基准', en: 'Cache · SIMD · benches' }, x: 540, y: 486, w: 160, h: 58, kind: 'proj', status: 'done', tier: 'eng', href: '/vol6-performance/', badge: 'V6' }, + { id: 'v7', name: { cn: '卷七 · 工程', en: 'Vol.7 Engineering' }, sub: { cn: 'CMake · 工具链 · 调试', en: 'CMake · toolchain · debug' }, x: 820, y: 486, w: 160, h: 58, kind: 'proj', status: 'doing', tier: 'eng', href: '/vol7-engineering/', badge: 'V7' }, + { id: 'crash', name: { cn: '崩溃实验室', en: 'Crash Lab' }, sub: { cn: '真崩溃排查', en: 'Real crash forensics' }, x: 1090, y: 486, w: 140, h: 46, kind: 'sup', status: 'doing', tier: 'domain', href: '/crash-lab/', badge: 'LAB' }, + { id: 'v8', name: { cn: '卷八 · 领域', en: 'Vol.8 Domains' }, sub: { cn: '嵌入式 · TinyML · 网络', en: 'Embedded · TinyML · net' }, x: 340, y: 640, w: 160, h: 58, kind: 'proj', status: 'doing', tier: 'domain', href: '/vol8-domains/', badge: 'V8' }, + { id: 'v9', name: { cn: '卷九 · 开源研读', en: 'Vol.9 Source Study' }, sub: { cn: 'Chromium 源码', en: 'Chromium internals' }, x: 620, y: 640, w: 160, h: 58, kind: 'proj', status: 'doing', tier: 'domain', href: '/vol9-open-source-project-learn/', badge: 'V9' }, + { id: 'v10', name: { cn: '卷十 · 演讲笔记', en: 'Vol.10 Talk Notes' }, sub: { cn: 'CppCon 二创', en: 'CppCon notes' }, x: 890, y: 640, w: 160, h: 58, kind: 'proj', status: 'doing', tier: 'domain', href: '/vol10-open-lecture-notes/', badge: 'V10' }, + { id: 'proj', name: { cn: '贯穿式项目', en: 'Capstone Projects' }, sub: { cn: '协程服务器 · INI 解析器', en: 'Coroutine server · INI' }, x: 1130, y: 640, w: 160, h: 58, kind: 'proj', status: 'doing', tier: 'domain', href: '/projects/', badge: 'PRJ' }, + { id: 'community', name: { cn: '社区文章', en: 'Community' }, sub: { cn: '来稿与收录', en: 'Submissions' }, x: 430, y: 784, w: 140, h: 46, kind: 'sup', status: 'doing', tier: 'domain', href: '/community/', badge: 'COM' }, + { id: 'tags', name: { cn: '标签索引', en: 'Tags' }, sub: { cn: '按主题检索', en: 'Browse by topic' }, x: 700, y: 784, w: 140, h: 46, kind: 'sup', status: 'doing', tier: 'domain', href: '/tags/', badge: 'IDX' }, +] + +export const HOME_PATH_EDGES: PathEdge[] = [ + // 主线：新手 → 基础 → 现代 → 标准库 → 高级 → 并发 → 性能 → 工程 → 领域 → 开源研读 + { from: 'gs', to: 'v1', kind: 'solid', route: { from: 'bottom', to: 'top', via: [{ x: 'from', y: 121 }, { x: 'to', y: 121 }] } }, + { from: 'v1', to: 'v2', kind: 'solid', route: { from: 'right', to: 'left' } }, + { from: 'v2', to: 'v3', kind: 'solid', route: { from: 'bottom', to: 'top', via: [{ x: 'from', y: 265 }, { x: 'to', y: 265 }] } }, + { from: 'v3', to: 'v4', kind: 'solid', route: { from: 'right', to: 'left' } }, + { from: 'v4', to: 'v5', kind: 'solid', route: { from: 'bottom', to: 'top', via: [{ x: 'from', y: 409 }, { x: 'to', y: 409 }] } }, + { from: 'v5', to: 'v6', kind: 'solid', route: { from: 'right', to: 'left' } }, + { from: 'v6', to: 'v7', kind: 'solid', route: { from: 'right', to: 'left' } }, + { from: 'v7', to: 'v8', kind: 'solid', route: { from: 'bottom', to: 'top', via: [{ x: 'from', y: 563 }, { x: 'to', y: 563 }] } }, + { from: 'v8', to: 'v9', kind: 'solid', route: { from: 'right', to: 'left' } }, + { from: 'comp', to: 'v7', kind: 'solid', route: { from: 'bottom', to: 'top', via: [{ x: 'from', y: 409 }, { x: 'to', y: 409 }] } }, + // 项目线绕左侧进入 B4/B5 间轨道，避免横穿卷七 → 卷八的主线。 + { from: 'v5', to: 'proj', kind: 'solid', route: { from: 'left', to: 'bottom', via: [{ x: 150, y: 'from' }, { x: 150, y: 710 }, { x: 'to', y: 710 }] } }, + // 按需选修（对应 roadmap 页路径 B/C：有 C 底子可跳读、按目标选题） + { from: 'gs', to: 'v2', kind: 'dash', route: { from: 'bottom', to: 'top', via: [{ x: 'from', y: 129 }, { x: 'to', y: 129 }] } }, + { from: 'v2', to: 'v5', kind: 'dash', route: { from: 'bottom', to: 'top', via: [{ x: 'from', y: 257 }, { x: 230, y: 257 }, { x: 230, y: 409 }, { x: 'to', y: 409 }] } }, + { from: 'v2', to: 'v4', kind: 'dash', route: { from: 'bottom', to: 'top', via: [{ x: 'from', y: 273 }, { x: 'to', y: 273 }] } }, + { from: 'v2', to: 'comp', kind: 'dash', route: { from: 'right', to: 'left' } }, + // 同层隔点连接走节点下方，不能再从卷九节点背后穿过。 + { from: 'v8', to: 'v10', kind: 'dash', route: { from: 'bottom', to: 'bottom', via: [{ x: 'from', y: 692 }, { x: 'to', y: 692 }] } }, + // 支撑/索引：不进悬停高亮链 + { from: 'v2', to: 'crash', kind: 'dot', route: { from: 'right', to: 'top', via: [{ x: 750, y: 'from' }, { x: 750, y: 128 }, { x: 'to', y: 128 }] } }, + { from: 'v7', to: 'crash', kind: 'dot', route: { from: 'right', to: 'left' } }, + // 两条索引线分别使用左右外围轨道，避免贯穿中心节点。 + { from: 'gs', to: 'tags', kind: 'dot', route: { from: 'left', to: 'bottom', via: [{ x: 110, y: 'from' }, { x: 110, y: 820 }, { x: 'to', y: 820 }] } }, + { from: 'proj', to: 'community', kind: 'dot', route: { from: 'right', to: 'top', via: [{ x: 1240, y: 'from' }, { x: 1240, y: 726 }, { x: 'to', y: 726 }] } }, +] diff --git a/site/.vitepress/theme/index.ts b/site/.vitepress/theme/index.ts index e00b0d4b9..e24a694a2 100644 --- a/site/.vitepress/theme/index.ts +++ b/site/.vitepress/theme/index.ts @@ -13,7 +13,7 @@ import ReferenceItem from './components/ReferenceItem.vue' import OnlineCompilerDemo from './components/OnlineCompilerDemo.vue' import HomeHeroVisual from './components/HomeHeroVisual.vue' import ProofStrip from './components/ProofStrip.vue' -import HomeRoadmap from './components/HomeRoadmap.vue' +import HomePathExplorer from './components/HomePathExplorer.vue' import FontSizeSwitcher from './components/FontSizeSwitcher.vue' import ResizableSidebar from './components/ResizableSidebar.vue' import { setupMermaid } from './mermaid-client' @@ -32,7 +32,7 @@ export default { 'home-hero-after': () => h('div', { class: 'proof-on-desktop' }, [h(ProofStrip)]), 'home-features-before': () => h('div', { class: 'home-pre-features' }, [h(ScreenshotCarousel), h(HomeTipBanner)]), - 'home-features-after': () => h(HomeRoadmap), + 'home-features-after': () => h(HomePathExplorer), 'nav-bar-content-after': () => h(FontSizeSwitcher), 'nav-screen-content-after': () => h(FontSizeSwitcher), })