📚 Wiki 编辑者注意事项与编写指南¶

🎯 概述¶

南安一中校园 Wiki 使用 MkDocs Material 主题构建，内容以 Markdown 格式存储。编辑者可以通过管理面板或直接编辑 Markdown 文件两种方式更新内容。

🖥️ 管理面板编辑（推荐）¶

访问地址¶

https://nayz-wiki.daoxiang.xyz/admin

页面管理¶

新建页面
点击管理面板的 「➕ 新建页面」
输入页面路径（如 校园风光/操场.md）
系统自动创建并跳转到编辑页面
编辑页面
在页面列表中找到目标页面
点击 「✏️ 编辑」 进入编辑器
使用 Markdown 格式编写内容
点击 「💾 保存」 自动提交到 Git
删除页面
仅管理员可操作
点击 「🗑️ 删除」，不可撤销

导航管理¶

管理面板中的 「导航管理」 区域可编辑 nav 配置
使用 YAML 格式定义导航结构
示例：

- 首页: index.md
- 人物志:
  - 介绍: pintro.md
  - 某某同学: xxx.md
- 大事记:
  - 介绍: eintro.md
  - 事件名称: event.md

新建页面后，记得添加到导航中

用户管理（仅管理员）¶

可创建/删除编辑者账号
角色分为：管理员、编辑者、观察者
编辑者可以编辑和保存页面
观察者只能查看

📝 Markdown 编写规范¶

基本语法¶

# 一级标题
## 二级标题
### 三级标题

**加粗文字**  *斜体文字*

- 无序列表项
- 无序列表项

1. 有序列表项
2. 有序列表项

[链接文字](https://example.com)
![图片描述](图片路径)

引用和提示¶

> 这是一段引用

!!! note "提示标题"
    这是一条提示信息

!!! warning "警告"
    这是一条警告信息

!!! danger "危险"
    这是一条危险信息

代码¶

行内代码：`code`

代码块：
```python
def hello():
    print("Hello World!")

### 表格

```markdown
| 姓名 | 班级 | 备注 |
|------|------|------|
| 张三 | 高一1班 | 班长 |
| 李四 | 高一2班 | 团支书 |

注意事项¶

文件名规范：使用英文或拼音命名，如 zhangsan.md、shouzhuabing.md
路径规范：不要包含中文和特殊字符
首页：编辑 docs/index.md
图片：放入 docs/assets/images/ 目录，引用路径为 assets/images/xxx.jpg

🔄 Git 同步机制¶

自动提交¶

每次在管理面板中保存或删除页面时，系统会自动执行：

git add -A
git commit -m "更新页面: xxx.md"

手动推送到 GitHub¶

在管理面板找到 「📤 GitHub 同步」 区域
粘贴 GitHub Personal Access Token
点击 「设置 Token」
点击 「⬆️ 推送到 GitHub」

Token 获取路径： GitHub → Settings → Developer settings → Personal access tokens → Generate new token (classic) 勾选 repo 权限

手动从 GitHub 拉取¶

点击 「⬇️ 从 GitHub 拉取」 按钮，将 GitHub 上的最新更改同步到服务器。

自动同步（Webhook）¶

当你在 GitHub 上直接编辑文件并提交时，系统会自动：

收到 GitHub 的 Webhook 通知
在后台执行 git pull
自动重建站点

⏱ 整个过程约需 5-15 秒，刷新网站即可看到更新

⚠️ 注意事项¶

1. 避免冲突¶

❌ 不要同时在管理面板和 GitHub 上修改同一个文件
✅ 日常编辑请使用管理面板
✅ 如需在 GitHub 上编辑，请确保管理面板没有未保存的修改

2. 提交信息规范¶

自动提交的信息格式为：

更新页面: xxx.md
创建页面: xxx.md
删除页面: xxx.md

如需自定义提交信息，可直接在 Git 命令行操作。

3. 图片文件¶

大图片（>1MB）不会被推送到 GitHub（已在 .gitignore 中排除）
图片直接上传到服务器的 docs/assets/images/ 目录
在 Markdown 中引用图片：![描述](assets/images/图片名.jpg)

4. 站点重建¶

每次保存或拉取后，系统会自动执行 mkdocs build 重建站点。如需手动重建，点击管理面板的 「🔄 手动重建站点」。

5. 查看同步状态¶

管理面板的 GitHub 同步区域会显示：

✅ 远程仓库连接状态
📝 未提交的更改数量
📋 最近的提交历史

🚀 快速开始¶

第 1 次使用¶

1. 打开 https://nayz-wiki.daoxiang.xyz/admin
2. 使用管理员分配的账号登录
3. 点击「➕ 新建页面」创建第一篇文档
4. 编写内容后点击「💾 保存」
5. 在导航管理中添加新页面
6. 点击「🔄 手动重建站点」即可看到效果

配置 GitHub 同步（管理员）¶

1. 生成 GitHub Token（Settings → Developer settings → PAT）
2. 粘贴 Token 到管理面板 → 点击「设置 Token」
3. 点击「⬆️ 推送到 GitHub」
4. 可选：在 GitHub 仓库 Settings → Webhooks 配置自动同步

日常编辑流程¶

1. 打开管理面板 → 找到要编辑的页面
2. 点击「✏️ 编辑」 → 修改内容 → 「💾 保存」
3. （可选）点击「⬆️ 推送到 GitHub」同步到远程仓库

🔧 常见问题¶

Q: 保存后网站没有变化？¶

A: 检查管理面板是否提示重建成功。如有错误，检查 Markdown 格式。

Q: GitHub 推送失败？¶

A: 检查 Token 是否有效（未过期），以及仓库地址是否正确。

Q: 导航修改后导航栏没变？¶

A: 保存导航后系统会自动重建。如果还是没变，点击「🔄 手动重建站点」。

Q: 如何恢复被删除的页面？¶

A: 如果已推送到 GitHub，可以在 GitHub 仓库中找回历史版本。

📖 最后更新: 自动同步 🔗 项目地址: github.com/daoxiang0520/nayz-wiki