infra aligned with tamcpp#13
Merged
Merged
Conversation
dev 配置 (config/index.ts) 与生产分卷构建 (build.ts 两段生成器) 原本三处各写一份 base/markdown 插件/head/themeConfig，改一处漏两处（mermaid 曾因此翻车）。抽 shared.ts 导出 sharedBase/sharedMarkdown/sharedThemeBase 三处统一 import；nav/sidebar 不抽（分卷构建不带）。pnpm build --force 全量 10 卷重建通过，输出 994 文件不变。
deploy 补 frozen-lockfile + build cache (site/.vitepress/.build-cache) + NODE_OPTIONS 大内存上限防 OOM；新增 build-check.yml 在 PR 合入 main 前先跑构建；新增 lint.yml 跑 markdownlint（存量约 122 处历史违规，暂 continue-on-error 只报告，清完转强制）。
markdownlint 规则照抄 tamcpp（关 MD013/MD041 适配中文 frontmatter 首行）；pre-commit 挂 markdownlint+clang-format(复用 .clang-format)+check-added-large-files(守 5.5G qt_src)+基础 hooks；package.json 加 check:links/hooks:install 脚本入口，version 0.0.1→0.2.0 对齐 git tag。
存量 122 处违规全部修复：12 个代码块补语言标记（.rep 用 cpp，公式/输出/目录树用 text），2 处 C++/HTML 写在校对正文里未加反引号的包进反引号修 MD042/MD045，其余靠 markdownlint --fix 补围空行。markdownlint 316 文件 0 error；pre-commit 钩子另修了专家层 2 篇的尾随空格/末尾换行。lint.yml 去掉 continue-on-error 转强制。pnpm build 验证通过。
原开篇 5 段第一人称叙事（'嘿！这里是…我们会吐槽叹气熬夜调试'）故事性太强，换成一句严肃的 > 引用定位：聚焦 C++/QtWidgets + 三层递进 + 实例库 + 学→做闭合。
去掉'准备好了吗？开始你的 Qt 之旅吧'的口语 CTA，换成直接指向教程索引/更新日志/Issue 的导航语。
CONTRIBUTING 落 AwesomeQt 五段结构 + 五件套示例规范 + pre-commit 用法 + PR 清单；AGENTS.md 是 vendor-neutral 的 AI 助手贡献入口（定位'用 AI 助手参与读这里'，不含 AI 开发叙事），金科玉律含专家层文件:行号证据/踩坑写后果/文档禁完整代码交 examples/链接真实标 Qt 版本，专家层口径 2/102。4 个 Issue 模板（勘误/示例构建/站点/内容提案）+ config.yml（删 Discussions 链，S7）+ 2 个 PR 模板（删翻译/Godbolt，加实例库与源码引用项）。README 贡献段补链 CONTRIBUTING/Issue/AGENTS。
check_links.py 加 --internal-only 开关（跳过外链，CI 只查内链避免限流误报；本地 57 内链全过）。新增 content-quality.yml 在 PR 改动教程时跑内链检查。新增 verify_source_refs.py：解析专家文章源码表建 basename→qt_src 路径映射，核对正文 basename:行号 引用真实存在/非空行/不越界（qt_src 不在时自动跳过 exit 0）；接进 pre-commit（本地有 qt_src 才核对，CI 跳过）。本地 4 篇专家文章引用全部核对通过。
build_examples.py：发现 examples/ 叶子工程（自洽独立可编）+ widget/app/model/industrial 库根（root-owns-config），排除 S3 砍掉的 8 模块示例，并行+ccache+Ninja，共 256 编译单元。本地验证 beginner/01-qtbase 16 叶子并行 24.7s 全过、widget 根 6.2s 过。build-examples.yml：PR/push 触发，apt 装 Qt6 全模块 + ccache 缓存。.gitignore 加 _build_ci/。
VitePress 的 public 目录是 <srcDir>/public（即 tutorial/public），不是 site/.vitepress/public——之前 head 引用 favicon 但文件不在正确位置，每页 404。把 tutorial/Awesome-Embedded.ico 放到 tutorial/public/favicon.ico（dev/build:single 原生识别）；多卷构建里根构建把 tutorial/public 复制进 rootSrcDir/public，让 favicon 随根产物进 dist 全站可访问。sidebar 排除 public 目录。--force 重建验证 dist/favicon.ico 存在（995 文件）。OG/分享卡片本次不做。
多卷构建下 VitePress 内置 sitemap 会按卷碎片，改为构建完扫 dist 全部 .html 自己生成一份完整的 sitemap.xml（cleanUrls：index.html→目录、foo.html→foo，排除 404）。robots.txt 放 tutorial/public 指向 sitemap。验证 dist/sitemap.xml 314 URL + robots.txt。
…test v1.17.0） 原先钉在各自 main 分支头的随机 commit（git describe 无 tag），现在钉到正式 release tag——已知好版本，不再跟踪移动的 main，供应链可复现性更清晰。
分三档声明：示例与实例库代码 MIT（根 LICENSE）、教程文档 CC BY-SA 4.0（教学内容常见选择，可改 CC BY 4.0 或全 MIT）、专家层引用的 Qt 源码片段属教学评注遵循 The Qt Company LGPL/商用许可。README 加「许可」段链 NOTICE。补齐旗舰仓都没做的法律底线。
全部经 shared.ts 单一真相源接入：①code-fold-plugin（>30行代码块构建期包 details，双 span summary + CSS :has()，阈值 30 不误折可读中等块，整段包不破坏复制按钮兄弟链，mermaid/code-group 跳过）；②FontSizeSwitcher.vue（顶部 5 档 zoom 缩放，localStorage 持久化，head 内联脚本防首屏闪烁，默认 normal）；③kbd-plugin（html_inline 版，避 C++/i++）；④build-info.ts（footer 注入 git describe+sha+提交日期）。custom.css 追加三段 CSS。pnpm build --force 验证：243 页含折叠、footer 显示版本、字号脚本注入、build SUCCESS。
home-hero-after 槽位挂 HomeCarousel.vue：4 张幻灯片（StatusLED / toggle-switch / 教程 / 专家层），自动轮播 5s + 左右箭头 + 圆点指示器，鼠标悬停暂停。图从 /Tutorial_AwesomeQt/carousel/<name>.png 读（放 tutorial/public/carousel/）；图还没提供时 <img> @error 切品牌渐变占位（不显示破图）。用户照好图丢进 tutorial/public/carousel/ 即自动替换，无需改代码。
status-led/toggle-switch 两张控件演示改 .gif（动图展示控件实际运行效果，比静态截图更能体现实例库价值）；tutorial/expert 两张页面截图保持 .png（静态内容无需动画，体积小）。用户照此命名提供素材即可。
控件 demo 用动图 WebP（status-led 619KB / toggle-switch 476KB，由源 mp4 经 ffmpeg libwebp -loop 0 转码，fps=8/scale=560/q45）；教程页/专家页用静态 WebP（tutorial 34KB / expert 23KB，由 PNG 经 cwebp -q82 缩到 960 宽）。4 张共 ~1.2MB，全过 1.5MB 守卫。HomeCarousel 4 路径改 .webp。pnpm build 验证 dist/carousel/ 4 张齐、bundle 引用正确、轮播出真图。
…meCarousel 作者指出轮播应等比迁移 tamcpp 而非自造——tamcpp 有 ScreenshotCarousel.vue（3D coverflow：中间放大/两侧 rotateY 倾斜/点击跳转/5s 自动/圆点进度条/reduced-motion+移动端适配），放在 home-features-before 槽（features 上方）。照搬其 coverflow JS 逻辑与 CSS，适配 AwesomeQt：图改走 public 目录 + withBase（不用 tamcpp 的相对 import）、单语 zh 去 isEn、4 个 slide（StatusLED/toggle-switch 动图 + 教程/专家页）。删除之前自造的 HomeCarousel.vue。theme/index.ts 槽位 home-hero-after → home-features-before 对齐 tamcpp。pnpm build 验证通过。
Ubuntu 24.04 apt 缺 qt6-svgwidgets-dev / qt6-mqtt-dev / qt6-core5compat-dev / qt6-statemachine-dev 等addon 包，apt 装不全。改用 jurplel/install-qt-action@v4 从 Qt 官方镜像装 Qt 6.9.1 + 示例用到的全部非 S3 addon 模块（charts/multimedia/svg/serialport/serialbus/websockets/3d/quick3d/shadertools/connectivity/mqtt/pdf/5compat/scxml/httpserver/declarative），cache:true 跨 run 缓存。apt 只留构建工具 cmake/ninja/ccache+GL。install-qt-action 设 CMAKE_PREFIX_PATH，build_examples.py 的 cmake 自动找到 Qt。
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
No description provided.