Skip to content

CLAUDE.md

Latest commit

 

History

History
55 lines (37 loc) · 4.64 KB

CLAUDE.md

File metadata and controls

55 lines (37 loc) · 4.64 KB
Raw

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

这是什么

Code Course Atlas —— 一个静态课程门户:无后端、无 JS 打包,Cloudflare Pages 直接托管仓库根目录。根目录是门户首页(列出多个「代码阅读课程」),每个课程是一个自包含的静态子目录,以 -course-en / -course-zh 双语配对形式存在。

常用命令

  • npm start —— 门户静态预览(python3 -m http.server 4173,http://localhost:4173)。**只服务静态文件,不监听课程改动**。
  • npm run dev —— 开发课程内容用(scripts/dev.js):live-server + 自动监听所有含 build.sh 的课程目录,改 _base.html / modules/*.html / _footer.html 后自动重跑 build.sh 并刷新。端口可用 PORT=5173 npm run dev 覆盖。
  • (cd <course-dir> && bash build.sh) —— 手动重建单个课程的 index.html。
  • 无 lint / 无 test —— 这是纯静态站点,没有测试套件;改动靠浏览器肉眼验证。

架构:门户层 vs 课程层

项目是两个独立层,共用一套设计语言但各自自包含。

门户(根目录 index.html + portal.css + portal.js)

  • portal.js 是一个 IIFE,无框架,做三件事:
    1. i18n:copy = { zh, en } 字典,按 URL ?lang= → localStorage("atlas-language") → 默认 zh 的优先级选语言;通过 data-i18n / data-i18n-aria-label / data-i18n-alt 属性用 innerHTML 注入文案(文案可含 HTML,如 <br /><em>)。
    2. 渲染项目卡片:遍历顶部的 projects 数组,把每个课程渲染成 #project-list 里的一行;整行点击 / 回车进入当前语言的课程。
    3. stats 行自动计算:仓库数、总模块数(由各 project.modules 求和)都从 projects 数组算出 —— 加课程后 stats 自动更新,无需改 JS。
  • 加课程的唯一入口是 portal.js 顶部的 projects 数组。

课程(每个 *-course-{en,zh}/ 目录)

  • 「无构建步骤」只对门户成立。每个课程目录有 build.sh,但它不是打包,而是 HTML 片段拼接:cat _base.html modules/*.html _footer.html > index.html。
  • 文件分工:_base.html 是 shell(<head>、字体、主题色覆盖、顶部 <nav>、<main> 开头);modules/0N-*.html 是纯 <section class="module"> 片段(不含 html/head/body/style/script);_footer.html 闭合标签;styles.css 和 main.js 在运行时被 _base.html 引用。
  • index.html 是产物,不要手改。改了 _base.html / modules/ / _footer.html 后必须重跑 build.sh;但 styles.css 是运行时 link 的,只改 CSS 不需要 rebuild。

设计令牌

DESIGN.md 是设计系统的单一事实来源(颜色、圆角、间距、字号、阴影、组件)。

  • 所有颜色 / 圆角 / 间距 / 字号都引用 CSS 变量,不写裸值;阴影用暖调半透明黑,不用纯黑或硬偏移阴影。
  • 门户主色是朱红 vermillion #D94F30。每门课程可在自己的 _base.html 里只覆盖四个 --color-accent* 变量换主题色,其余令牌保持不变。
  • 课程的 styles.css 与门户 portal.css 是两套独立样式表,共享同一令牌哲学;同一课程的 -en 与 -zh 两个 styles.css 必须字节一致(改 en 后 cp 到 zh)。

添加一门新课程

不要从零手搭。仓库内置两个 skill(在 .claude/skills/),按顺序协作:

  1. codebase-to-course —— 从 GitHub 仓库读码、设计 4–6 个模块、生成单语言(英文)课程目录(styles.css / main.js / _base.html / modules/ 一整套;styles.css 和 main.js 从其 references/ 原样复制,不要重新生成)。
  2. atlas-add-course —— 在上一步输出基础上做成 Atlas 双语配对:复制出 -zh、加门户回链 ← Code Course Atlas 与语言切换、翻译中文、在 portal.js 的 projects 数组注册、更新 README.md、build & verify。

翻译铁律:代码神圣,散文流动 —— 所有 HTML 标签 / class / id / data-* 键 / 代码块原样保留,只翻译人类可读文字;技术术语(BM25、retrieval-augmented 等)保留英文,只译其定义。各阶段的确切片段、双语校验脚本、流程见 skill 的 SKILL.md 与 references/。

红线

  • 课程 index.html 是 build.sh 的产物,别手改。
  • nav-dots 数量必须和 modules/ 数量一致。
  • 翻译时别破坏属性里的引号 —— data-definition="…" 内多一个 " 会静默破坏 tooltip。
  • 中文课程 _base.html 的字体栈必须含 PingFang SC / Microsoft YaHei 回落。
  • -en / -zh 的 styles.css 必须保持一致,避免双语视觉漂移。