一份来自 teapot1de 的开发手记¶
大家好，我是 teapot1de。欢迎你，未来的开发者！🎉
这份文档记录了我在初期搭建和精炼 CS for NCU 项目时的一些思考、遇到的问题以及最终的解决方案。
在开始前，我必须坦白一件事：我并没有系统地学习过前端开发。
所以，在搭建这个项目的过程中，我遇到了不少现在看来可能很初级的问题，并很大程度上依赖了 AI (主要是 Gemini 2.5) 来辅助探索和决策。
我把这份手记公开，一方面是希望能为后来的开发者提供一些“前车之鉴”，更重要的是，我热切地期盼有真正的前端大佬能帮忙斧正其中的不足之处。这里的许多实现方式都带有我这个“新手”的浓厚个人印记，它们可能不是最优解，甚至可能有些笨拙。
一、项目初期的架构思考¶
1. CSS 架构：从混乱到有序，再到精简¶
最开始，我把所有的自定义样式都堆在了单一的 extra.css 文件里。很快我就发现，这简直是一场灾难。
我的决策：在 Gemini 的建议下，我设计了一套模块化 CSS 架构。一开始我分得很细，甚至有 02-components.css 和 99-fixes.css，但后来发现对于我们这个项目来说，这有点“过度设计”了，没什么大用处。于是我把它精简成了现在的样子：
点击查看我当前的模块化设计
我将 docs/css/ 目录下的文件进行了如下拆分，并通过 extra.css 的 @import 顺序控制加载：
| 文件名 | 核心职责 | 我的考量 |
|---|---|---|
00-variables.css |
设计变量 | 把所有颜色、字体都放这里，实现一键换肤。 |
01-layout.css |
布局样式 | 隔离结构性样式，免得和组件样式打架。 |
03-admonitions.css |
提示框样式 | 提示框的定制化太深了，必须单独拿出来。 |
💡 小技巧：我选择用数字前缀（00-, 01-...）来强制规定文件的加载顺序，这样看起来一目了然。
2. 协作的基石：《写作规范》的诞生¶
随着项目内容增加，我意识到如果没有统一的规范，协作起来会非常痛苦。而且像 Linux 201 那样的大项目就有相关的设计。
一份协作“契约”
于是，我们共同撰写并最终确立了《写作规范》。它不仅是规则的集合，更是我们协作的“契约”，统一了从标点、空格到高级 Markdown 特性的所有用法。
二、折腾 UI 的那些事¶
1. 追求极致：平滑圆角 (Squircle) 的探索¶
我一直很喜欢苹果那种平滑的圆角。为了实现它，我折腾了好一阵子。
最终方案：clip-path + 内联 SVG <clipPath>。
点击查看我的技术选型过程
- 尝试一：
border-radius-> 效果太生硬，放弃。 - 探索阶段：我一直在寻找更好的方法，最后在某个技术博客上找到了使用 SVG
clip-path实现平滑圆角的完美方案。 - 最终实现：我在
overrides/main.html中定义了一个全局的 SVG<clipPath>，然后在 CSS 里通过clip-path: url(#squircle);来引用它。效果似乎还不错，但是其实我也看不太出来。
2. 赋予灵魂：项目专属的提示框视觉语言¶
我觉得传统的 info, warning 图标太单调了，想给项目来点特别的。于是，我设计了一套全新的、具有独特视觉风格的提示框。
我自定义的意象系统
这些是我们精心设计过的、具有独特视觉风格的提示框。
类型 (!!! <type>) |
图标意象 | 核心用途 |
|---|---|---|
danger |
龙 🐉 | 严重警告：用于描述不可逆的、有破坏性的操作或重大风险。 |
alert |
克苏鲁 🐙 | 潜在陷阱：用于提醒用户注意可能导致非预期结果或错误的细节。 |
declaration |
号角 🎺 | 重要宣告：用于发布官方定义、规则、原则或重要声明。 |
example |
钥匙 🔑 | 最佳实践：提供一个清晰、可参考的正面例子或操作指引。 |
reminder |
感叹号 ❗ | 友好提醒：用于强调关键点、备忘录或需要记住的重要信息。 |
story |
书本 📖 | 背景故事：用于讲述一段个人经历、项目历史或补充性的背景信息。 |
quote |
引号 💬 | 引用观点：用于直接引用他人的话、书籍或文章中的段落。 |
author |
羽毛笔 ✍️ | 作者补充：用于作者发表一些题外话、个人见解或元评论。 |
三、踩过的坑与学到的教训¶
案例一：Tags 插件的“官方文档陷阱”¶
问题：配置 tags 插件时，标签能显示但就是点不了。
最终结论：在老老实实去看了最新的官方文档后，我才发现插件的工作模式早就变了。旧教程依赖 tags_file 配置，而新模式需要在 Markdown 文件里手动加一行 <!-@- material/tags -->。
我学到的教训
开源工具迭代太快了，遇到问题，第一时间去看最新的官方文档，比依赖旧经验和教程靠谱得多。并且上面<!-@- material/tags -->中的 @ 是多余的，我添加这个是为了避免渲染错误。
案例二：CSS“幽灵颜色”的侦探笔记¶
问题：这个问题快把我逼疯了。我明明自定义了主题颜色，但某个链接的背景，顽固地显示一个我从未定义过的蓝色。
最终结论：在我百思不得其解时，是 Gemini 告诉我，可以用浏览器开发者工具的 Inspect（检查） 功能，然后在 Styles（样式） 面板里查看究竟是哪条 CSS 规则在生效。通过这个方法，我才定位到，这是因为 Material 主题使用了我没定义的衍生 CSS 变量（比如带 --dark 后缀的变量），导致它回退到了默认样式。
点击展开我的故障排查复盘指南
一个前端新手的样式故障排查指南¶
第 1 步：基础检查（先别怀疑人生）
- 强制清除缓存：Ctrl+Shift+R ，万事先刷新。
- 检查配置文件：看看
mkdocs.yml里的路径、primary: custom这些有没有写错。
第 2 步：使用 Gemini 教我的“杀手锏” (F12)
- 精确定位：在页面上右键点击出问题的元素，选 “检查” (Inspect)。
- 分析样式：在右侧的 “样式” (Styles) 面板里，找到最终生效的那条规则（就是没被划掉的那个）。
第 3 步：对症下药
情况 A：样式被更高优先级的规则覆盖了
- 怎么办？：在我的
extra.css里，写一条比它优先级更高的规则怼回去。
情况 B：用了我没定义的衍生变量（这次就是这个坑）
- 怎么办？：在我的
extra.css里，把那个带后缀的衍生变量也给定义了，不给它回退到默认值的机会。
写在最后：期待你的加入¶
正如开头所说，这份手记里的许多实现方式，都带有我这个“前端新手”的浓厚个人印记。它们可能不是最优解，甚至可能有些笨拙。
如果你对前端开发有更深的理解，发现了任何可以改进的地方——无论是 CSS 架构、一个变量的命名，还是某段代码的实现——请不要犹豫，立刻提出 Issue 或 Pull Request！
你的每一次斧正，都是在让这个项目变得更加专业和强大。
谢谢你！