tutorials/site/README.md
此代码来自构建时的仓库快照。修改源码后重新构建即可更新。
# 独立教程阅读站
内容源为上一层的 `tutorials/README.md` 及所有 `tutorials/NN-主题.md`（当前为第 01～32 章，其中第 32 章为待实施规划）；不维护第二份正文，不依赖业务应用、数据库、Redis 或登录。
在项目根目录执行：
```bash
pnpm install --frozen-lockfile
pnpm tutorials:dev
```
打开终端输出的 [阅读站](http://localhost:4173)。开发模式访问 HTML 时重新生成内容，修改 Markdown、CSS 或 JavaScript 后刷新即可。自定义端口：`TUTORIAL_PORT=4174 pnpm tutorials:dev`。
构建与检查：
```bash
pnpm tutorials:build
pnpm tutorials:preview
pnpm tutorials:test
```
构建结果在 `tutorials/site/dist/`，可交给任意静态 HTTP 服务托管，包含章节 HTML、样式、脚本、搜索索引、Markdown 副本和教程引用的源码快照。请通过 HTTP 预览；直接双击 HTML 的 `file://` 模式无法保证搜索索引加载。
## 交互
- 左侧章节导航，右侧本章标题目录（宽屏），滚动同步高亮；移动端用顶部目录按钮。
- 搜索全部章节的标题和正文，`⌘/Ctrl K` 打开，方向键选择，Enter 跳转，Esc 关闭。
- 代码块复制，扩展知识与参考答案折叠，上一章 / 下一章导航。
- 章节末尾手动标记完成，支持撤销。
- 自动记住章节与滚动位置，侧边栏可继续阅读；显式锚点优先，浏览器前进后退保留历史行为。
- 阅读设置支持系统 / 浅色 / 深色及三档字号；可单独重置学习进度。
- 设置和进度存于 localStorage，仅属于当前浏览器和站点地址，不同步到服务器；清除浏览器数据会丢失记录。存储不可用时仍可阅读。
## 维护
`build.mjs` 使用 marked 解析 Markdown，并在构建时生成搜索索引、标题锚点与源码页。新增 `NN-主题.md` 会自动进入导航、搜索和学习进度统计；章节顺序取文件名。每章在标题后用 `> 学习阶段：阶段名称` 声明分组，构建时读取该元信息生成阶段导航与章节标签，不重复展示在正文。未声明的章节归为“未分阶段”；`README.md` 为学习指南，不计入完成章节数量。已有进度按章节文件名保存，新增章节会增加总数，但保留之前的完成标记。
只打包正文明确引用、位于 `src/`、`prisma/`、`tests/` 及显式允许的部署配置、CI 与验收脚本的源码。真实 `.env`、认证密钥与业务数据不在允许范围。源码页是构建时快照，修改代码后需重新构建。
`preferences.js` 在样式加载前恢复外观；`app.js` 实现浏览器交互；`style.css` 提供响应式布局。新增 Markdown 语法时，应更新构建测试并进行浏览器验证。