内容编写指南
这份指南面向所有想为 DNUI Survival Guide 写点东西的同学。你只需要会 Markdown，照着下面的规范写，维护者就能快速 Review，你的内容也能更快上线。
贡献一篇文章的完整流程
选择栏目 → 创建 Markdown 文件 → 写 Frontmatter → 写正文
→ 登记侧边栏 → 本地检查 → 提交 Pull Request → Review → Merge → 自动上线只想改错字或补充几句话？不需要走完整流程，直接在目标页面底部点击「在 GitHub 上编辑此页」即可。基本协作流程见参与贡献。
第一步：选择栏目
站点内容按一级栏目存放在仓库根目录的同名文件夹中：
| 栏目 | 目录 | 适合的内容 |
|---|---|---|
| 新生指南 | freshman/ | 入学、选课、新生 FAQ |
| 校园生活 | campus/ | 食宿、出行、周边 |
| 学习指南 | study/ | 学习方法、绩点、资源 |
| 课程指南 | courses/ | 课程学习经验 |
| 计算机方向 | cs/ | 编程、技术路线、项目 |
| 竞赛 | competition/ | 各类竞赛经验 |
| 实习就业 | career/ | 实习、校招、面试 |
| 升学 | postgraduate/ | 考研、保研、留学 |
| 经验分享 | experience/ | 个人经验与规划 |
- 拿不准放哪里：先开一个 Issue 问一下，或在 PR 里说明。
- 想新增一个大栏目：请先开 Issue 讨论，避免目录结构频繁变动。
第二步：创建文件
在栏目目录下新建 Markdown 文件，命名规范：
- 小写英文、数字、连字符（
-），例如dorm-life.md、cet4-guide.md； - 不使用中文、空格、下划线；
- 文件名能看出主题，尽量简短。
文件路径决定文章网址：
campus/dorm-life.md → /campus/dorm-life第三步：编写 Frontmatter
每篇文章的开头必须有一段 YAML 信息头：
---
title: 宿舍生活指南
description: 校内宿舍的作息、物品准备与常见问题。
---title：文章标题，显示在浏览器标签、搜索结果和侧边栏中；description：一句话概括（建议 20~60 字），用于搜索摘要和 SEO。
NOTE
Frontmatter 里的 title 是给浏览器和搜索引擎看的；页面正文里还要再写一个一级标题（见下文），两者保持一致即可。
第四步：正文格式规范
标题层级
- 正文第一个标题用
#，与 Frontmatter 的title保持一致； - 之后按
##、###逐级递减，不要跳级（不要#之后直接###）； - 不要用标题语法给普通文字「加粗放大」。
# 宿舍生活指南
## 物品准备
### 床上用品
## 常见问题段落与排版
- 段落之间空一行；
- 中文与英文、数字之间建议加一个空格（如「DNUI 2025 级」「GPA 计算」）；
- 一句话能说清的事，不要拆成一堆小标题；
- 重点可以用
**加粗**，但一段里别超过一处。
列表
- 无序列表项
- 另一项
1. 有序列表第一项
2. 第二项并列内容用列表，有先后顺序的用数字列表；不要把整段话塞进列表项。
链接
- 站内链接：以
/开头、不带扩展名，指向栏目或文章，如[校园生活](/campus/)、[新生指南](/freshman/)；- 指向栏目首页时保留结尾的
/； - 构建时会自动校验站内链接，链接失效会导致构建失败；
- 指向栏目首页时保留结尾的
- 站外链接：使用完整
https://地址，并让链接文字有意义（不要只写「点这里」）。
图片
- 图片放在
public/images/<栏目名>/目录下，例如public/images/campus/dorm-1.jpg； - 用根路径引用：
； - 文件名使用小写英文和连字符；
- 单张图片建议小于 500KB，先压缩再上传；
- 截图必须先打码个人姓名、学号、手机号等敏感信息；
- 不要上传他人照片；尽量避免引用外部图床（容易失效）。
代码块
- 标注语言（如
```bash、```ts、```text）； - 只有命令、配置和代码才放进代码块，普通文字不要放进去。
表格
适合展示并列的对照信息：
| 学期 | 建议关注 |
| --- | --- |
| 大一 | 适应节奏、打好基础 |
| 大二 | 确定方向、参加竞赛 |提示框
使用 GitHub 风格的 alert 语法，在网站和 GitHub 上都会渲染成醒目的提示框：
> [!NOTE]
> 用于补充说明。
> [!TIP]
> 用于实用建议。
> [!WARNING]
> 用于提醒风险或易错点。实际效果：
TIP
善用提示框强调重要信息，但一篇文章建议不超过三个。
内容要求
格式之外，请遵守以下内容底线（详见仓库 CONTRIBUTING.md）：
- 真实可靠：不编造学校政策、收费、宿舍、考试、就业数据等信息；不确定的内容写明「待确认」并注明来源；没有可靠内容就先不写。
- 标注视角：经验类内容请说明背景（年级、专业方向等），它们代表作者个人观点，不代表学校或本项目立场。
- 保护隐私：不发布个人敏感信息（手机号、学号、成绩单等），截图先打码。
- 尊重版权：原创优先；转载必须获得授权并注明出处；引用官方信息请给出链接。
- 中立克制：不对教师、课程、企业进行打分或攻击性评价；不包含歧视、攻击性内容。
- 主题集中：一篇文章只写一个主题，建议 500~2000 字；内容太多就拆成几篇。
第五步：登记侧边栏
新文章要出现在对应栏目的侧边栏中，需要在 .vitepress/config/sidebar.ts 里加一行：
'/campus/': [
{
text: '校园生活',
items: [
{ text: '概览', link: '/campus/' },
{ text: '宿舍生活', link: '/campus/dorm-life' },
],
},
],link 不带扩展名、不带结尾 /（栏目首页除外）。忘了登记文章也能上线，只是不方便被找到，维护者 Review 时一般会提醒补上。
第六步：本地检查（可选但推荐）
本地运行（需要 Node.js 22+）：
npm install
npm run docs:dev # 打开 http://localhost:5173 实时预览
npm run docs:build # 构建校验（含站内死链检查）纯文字的小修改可以跳过；涉及新文件、链接、图片、侧边栏改动时，建议跑一遍 docs:build 确认通过——CI 也会在 PR 上执行同样的检查。
第七步：提交 Pull Request
git checkout -b docs/add-dorm-life
# 修改、保存文件后：
git add .
git commit -m "docs: add campus dorm life guide"
git push origin docs/add-dorm-life然后到 GitHub 上打开 Pull Request，按 PR 模板填写「修改内容 / 修改类型 / Checklist」。提交后：
- 等待 Build Check 变绿；红色 ❌ 表示构建失败，点进去看日志修复；
- 等待维护者 Review，可能提出修改建议，直接在同一分支继续提交即可；
- Merge 之后 Cloudflare Pages 自动部署，几分钟内网站更新。
文章模板
复制下面的模板，替换大括号里的内容即可开始写：
---
title: {文章标题}
description: {一句话概括，20~60 字}
---
# {文章标题}
开头用两三句话说明：这篇文章写给谁、解决什么问题。
## {第一个小节}
正文内容。并列的信息用列表，对照的信息用表格。
> [!TIP]
> 需要特别提醒的信息放在提示框里。
## {第二个小节}
## 常见问题
### {问题一}
### {问题二}
## 参考与致谢
- 内容如有参考来源，在这里列出链接；原创内容可删除本节。常见问题
Q：我只写了一半，可以先提交吗？ 可以。在 PR 描述里注明「草稿 / WIP」，或者使用 GitHub 的 Draft PR，维护者会先给意见再继续。
Q：我写的经验只代表我个人，会不会误导别人？ 写明你的背景和视角即可（如「2023 级软件工程，以下是我个人的做法」）。经验分享本来就是本站的重要内容。
Q：不确定某些信息准不准，还能写吗？ 能。把不确定的部分明确标出来（如「此条待确认，欢迎补充」），或在 PR 里说明。不要为了完整性把猜测写成事实。
Q：文章写多长合适？ 一个主题 500~2000 字通常够了。太长的话拆成「上/下」或多篇互相链接的文章。
Q：我想修改别人的文章，可以直接改吗？ 可以，这正是开源协作的方式。修改较大时建议先在 PR 里说明理由；修正错字、补充信息则直接提交即可。