Skip to content

Commit 5cc4081

Browse files
todaymvptodaymvp
committed
更新README：2026-06-23 15:16
1 parent 1d4926c commit 5cc4081

1 file changed

Lines changed: 80 additions & 36 deletions

File tree

‎README.md‎

Lines changed: 80 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,18 @@
1-
# 花江安全 - 社团官网
1+
# 花江安全 (HJSec) - 社团官网
22

33
> 桂林电子科技大学计算机与信息安全学院大学生科技协会 · 安全部
4-
> 官网地址：https://hjsec.github.io
4+
> 🌐 官网地址：https://hjsec.github.io
5+
> 📅 项目创建：2026.06.18 · 文档整理：2026.06.23
56
67
---
78

89
## 项目简介
910

10-
本项目是基于 [Accessible Astro Starter](https://github.com/incluud/accessible-astro-starter) 二次开发的安全社团官网，使用 Astro 6 构建，部署于 GitHub Pages。
11-
网站包含首页、关于我们、成员展示、招新页面、知识库等功能，所有内容均通过 Markdown/MDX 管理，无需后端。
11+
本项目是**花江安全**（原科协安全部）的社团官方网站，基于 [Accessible Astro Starter](https://github.com/incluud/accessible-astro-starter) 二次开发。
12+
网站包含首页、关于我们、成员展示、招新页面、知识库等功能，所有内容通过 Markdown / MDX 管理，无需后端数据库。
13+
14+
**技术栈：** Astro 6、Node.js、GitHub Pages、Docker (可选)。
15+
**核心设计理念：** 静态生成（SSG）、响应式布局、无障碍访问、极简维护。
1216

1317
---
1418

@@ -36,73 +40,113 @@ npm run dev
3640
## 成员管理
3741

3842
### 收集信息
39-
1. 使用腾讯文档/Excel 创建表格，表头如下：
43+
1. 使用腾讯文档 / Excel 创建表格，表头如下：
4044
```
4145
id,name,image,bio,motto,grade,links
4246
```
43-
- `id`：唯一标识（英文/拼音，用于网址）
47+
- `id`：唯一标识（英文/拼音，用于网址和文件名）
4448
- `name`：显示名称（中文可）
4549
- `image`：头像文件名（如 `today.jpg`，图片放在 `public/img/` 下）
4650
- `bio`：一句话简介
47-
- `motto`：格言
48-
- `grade`：年级（如 `2025`，会自动分组）
49-
- `links`：链接，格式为 `类型:URL`，多个用英文逗号分隔（如 `github:https://..., blog:https://...`）
51+
- `motto`：格言（选填）
52+
- `grade`：年级（如 `2025`，会自动按年级分组）
53+
- `links`：个人链接，格式 `类型:URL`，多个用英文逗号分隔
54+
示例：`github:https://github.com/todaymvp, blog:https://todaymvp.github.io`
5055

51-
2. 成员填写后，导出为 **CSV 文件**（UTF-8 编码）。
56+
2. 成员填写后，导出为 **CSV 文件**（UTF-8 编码，逗号分隔）。
5257

53-
3. 将头像图片放入 `public/img/`，文件名与表格 `id` 一致。
58+
3. 将头像图片放入 `public/img/`，文件名与表格 `id` 一致（如 `today.jpg`）。
5459

55-
### 导入成员
60+
### 批量导入成员
5661
在项目根目录运行：
5762
```bash
5863
node csv2mdx.mjs 成员.csv
5964
```
60-
脚本会自动在 `src/content/projects/` 下生成每个成员的 `.mdx` 文件，刷新页面即可看到新成员卡片。
65+
脚本会自动在 `src/content/projects/` 下生成每个成员的 `.mdx` 文件。
66+
刷新页面即可看到新成员卡片，按年级分组排列。
67+
68+
> 💡 `.mdx` 文件 = YAML 头部（结构化信息）+ Markdown 正文（个人介绍），可以直接编辑。
6169
6270
---
6371

6472
## 部署
6573

6674
### 自动部署（GitHub Actions）
67-
项目已配置好 `.github/workflows/deploy.yml`，每次推送 `main` 分支会自动构建并部署到 GitHub Pages。
68-
69-
**只需要确保仓库设置中 Pages 的部署源为 GitHub Actions。**
75+
项目已配置好 `.github/workflows/deploy.yml`，每次推送 `main` 分支会自动构建并部署到 GitHub Pages。
76+
**仓库 Settings → Pages → Build and deployment → 选择 GitHub Actions。**
7077

7178
### 手动构建
7279
```bash
7380
npm run build
7481
```
75-
构建产物在 `dist/` 目录，可自行上传到任何静态服务器。
82+
构建产物在 `dist/` 目录，可自行上传到任何静态服务器（如 Nginx、Docker 容器）。
83+
84+
### 服务器 Docker 测试
85+
```bash
86+
docker run --rm -it -v $PWD:/app -w /app -p 8060:4321 node:22-alpine sh -c "npm ci && npm run dev -- --host"
87+
```
7688

7789
---
7890

79-
## 核心文件说明
80-
81-
| 文件/目录 | 作用 |
82-
|-----------|------|
83-
| `theme.config.ts` | 站点名称、导航菜单、主题颜色等全局配置 |
84-
| `src/pages/index.astro` | 首页 |
85-
| `src/pages/about.astro` | 关于我们页面 |
86-
| `src/pages/contact.astro` | 加入我们页面 |
87-
| `src/pages/portfolio/index.astro` | 成员列表页 |
88-
| `src/pages/portfolio/[project].astro` | 成员详情页 |
89-
| `src/pages/blog/` | 知识库页面（什么是 CTF、安全方向等） |
90-
| `src/content/projects/` | 成员数据文件（由 CSV 导入生成） |
91-
| `public/img/` | 头像、宣传照等静态图片 |
92-
| `src/components/Footer.astro` | 页脚（版权、友链等） |
91+
## 核心文件清单
92+
93+
| 文件 / 目录 | 作用 |
94+
|-------------|------|
95+
| `theme.config.ts` | **站点全局配置**：名称、导航菜单、主题颜色、SEO 信息 |
96+
| `src/pages/index.astro` | 首页（Hero + 宣传图 + 特色卡片） |
97+
| `src/pages/about.astro` | 关于我们（社团介绍、方向、资源） |
98+
| `src/pages/contact.astro` | 加入我们（招新信息、靶场、QQ 群） |
99+
| `src/pages/portfolio/index.astro` | 成员列表页（按年级分组） |
100+
| `src/pages/portfolio/[project].astro` | 成员详情页（个人空间） |
101+
| `src/pages/blog/` | 知识库页面（什么是 CTF、安全方向、学习路线等） |
102+
| `src/content/projects/` | **成员数据**（.mdx 文件，由 CSV 导入生成） |
103+
| `public/img/` | 头像、宣传照、Logo 等静态图片 |
104+
| `public/robots.txt` | 搜索引擎爬虫规则 |
105+
| `src/components/Footer.astro` | 页脚（版权、友链、资源中心） |
93106
| `src/components/Hero.astro` | 首页大标题和按钮 |
94-
| `csv2mdx.mjs` | 批量导入成员的 Node.js 脚本 |
107+
| `src/assets/scss/_optimized-pages.scss` | 自定义样式（卡片、格言特效、移动端优化） |
108+
| `csv2mdx.mjs` | **批量导入成员的 Node.js 脚本** |
109+
| `astro.config.mjs` | Astro 构建配置（站点地址、插件等） |
110+
| `README.md` | 项目文档（本文件） |
95111

96112
**修改页面内容时，通常只需编辑对应的 `.astro` 文件或 `.md` 文章，不必改动布局组件。**
97113

98114
---
99115

116+
## 技术说明 & 开发经验
117+
118+
### 为什么选择 Astro 而不是 Hugo / Quartz？
119+
- **Quartz 4**：适合个人博客（基于 Hugo），但官网需要更灵活的布局，魔改成本高。
120+
- **Hugo**：单二进制文件，极快，但 Go Template 语法古老，学习曲线陡峭，适合文档站。
121+
- **Astro**：现代静态生成器，组件化开发，原生支持 Markdown 和 MDX，可自由控制 HTML/CSS，非常适合需要成员展示和自定义布局的社团官网。
122+
123+
### 什么是 MDX？和 Markdown 有什么区别？
124+
- **Markdown (.md)**：纯文本标记语言，适合写文章。
125+
- **MDX (.mdx)**：Markdown + JSX 组件 + YAML Frontmatter。
126+
我们用它来存储成员信息：**YAML 头部**写 id、格言、链接等结构化数据，**Markdown 正文**写个人介绍。
127+
128+
### CSV 导入原理
129+
`csv2mdx.mjs` 使用 `csv-parse` 库解析 CSV，并自动生成符合 Astro 内容集合规范的 `.mdx` 文件。
130+
路径、年级标签、空链接等边界情况均已处理。
131+
**注意**：CSV 中若字段含逗号，必须用英文双引号包裹；中文字段也要用双引号，避免编码问题。
132+
133+
### 样式调整注意事项
134+
- 谨慎修改全局 SCSS（`_optimized-pages.scss`），容易引发样式覆盖和缓存问题。
135+
- 页面内联样式（`style="..."`）优先级最高，适合临时微调。
136+
- 主题自带颜色变量（`--color-primary` 等），尽量使用变量以保证暗色模式兼容。
137+
138+
### 浏览器兼容性 & 缓存
139+
- 修改后如果页面没变化，先尝试硬刷新 (`Ctrl+Shift+R`) 或打开无痕窗口测试。
140+
- 开发服务器 (`npm run dev`) 支持热更新，但极端情况下需手动清除 `.astro` 缓存目录。
141+
142+
---
143+
100144
## 贡献与致谢
101145

102-
- 网站由 **步六孤** 创建并维护。
103-
- 原主题：Accessible Astro Starter by [Incluud](https://incluud.dev)。
104-
- 致敬所有开源贡献者 🧡
146+
- 网站由 **步六孤** 创建并维护，基于 [Accessible Astro Starter](https://github.com/incluud/accessible-astro-starter) 二次开发。
147+
- 原主题作者：[Incluud](https://incluud.dev) · 致敬所有开源贡献者 🧡
105148

106149
---
107150

108-
> 📅 本文档于 2026 年 6 月 23 日整理完成，至此往后，花江安全的故事由你续写。
151+
> 📅 本文档于 2026 年 6 月 23 日整理完成。
152+
> 花江安全的故事，由你续写。

0 commit comments

Comments
 (0)