ICFK 文档站 · 写作指南#

把这份放到 docs-src/writing-guide.md 里,新人贡献者可以直接在文档站读到。

两种写作方式#

方式一:网页可视化编辑(推荐)#

适合:改改文字、补段落、换图、调顺序。零门槛,所见即所得。

1. 用超管账号登录 squad.cyou
2. 在主站点头像 → 文档管理(进入后台 )
3. 找到要编辑的页面,点"编辑"按钮
4. 进入 GitBook 风格编辑器,所见即所得

编辑器操作:

方式二:直接编辑 .md 文件#

适合:大段重写、批量修改、需要 git 版本管理。

1. 在 docs-src/ 目录下找到对应文件,如 docs-src/xxx/xxxx.md
2. 用任何编辑器改(VSCode / Vim / Typora / 宝塔在线编辑器 都行)
3. 保存上传到服务器对应路径

新建 .md 文件需要做两件事:

1. 把 .md 文件放到 docs-src/ 下合适的子目录(如 docs-src/owner/optimization.md)
2. 打开 docs-src/_meta.json,在对应分组的 items 数组里添加一条:

json
   { "title": "服务器优化建议", "page": "owner/optimization" }

注意 page 不带 .md 后缀,路径用 / 分隔

不修改 _meta.json 的话,文件能访问但侧边栏不会显示。

Markdown 语法速查#

docs.php 自带的 markdown 解析器支持以下语法:

标题#

text
# 一级标题(每篇唯一,会作为页面标题)
## 二级标题(右侧 TOC 会自动收录)
### 三级标题(右侧 TOC 也会收录)
#### 四级标题

二级和三级标题会自动获得锚点链接,鼠标悬停时旁边出现 #。

文本格式#

text
**加粗**           → 加粗
*斜体*             → 斜体
`行内代码`         → 行内代码
[[Shift]]          → 渲染成键盘按键样式 ⌨ Shift
[[Ctrl]]+[[C]]     → 多个连用
[文字](URL)        → 链接(站内不带 https:// 不开新窗口,外链自动 target=_blank)
![描述](图片URL)   → 图片(自动 lazy load)

列表#

text
无序:
- 第一项
- 第二项
  - 嵌套(缩进 2-4 空格)
- 第三项

有序:
1. 第一步
2. 第二步
3. 第三步

表格#

text
| 字段 | 类型 | 说明 |
|------|------|------|
| id   | int  | 主键 |
| name | str  | 名称 |

第二行的 --- 必须有,中间的对齐冒号(:---: 居中, ---: 右对齐)目前不解析,统一左对齐渲染。

代码块#

`

text

php

text

`

支持的语言标签:php、js、bash、json、sql、yaml、ini、html、css 等。语言标签不影响实际渲染颜色(目前没接 highlight.js),只显示在右上角作为标识。

引用#

text
> 这是一段引用,左侧带蓝色竖线和淡蓝背景。
> 多行写在一起会合并为同一段。

提示框(callout)— 这是站点的特色组件#

文档站里最重要的语义化组件,5 种风格对应 5 种语气:

text
:::info 这是信息标题
普通信息提示。蓝色,中性语气,适合 "顺便说一下" 类内容。
:::

:::success 操作成功
成功 / 推荐 / 已完成 类型。绿色,正向语气。
:::

:::warning 注意事项
警告 / 容易踩坑 / 需要小心。橙色,提醒语气。
:::

:::danger 危险操作
不可逆 / 数据丢失 / 严重影响。红色,严肃语气,玩家 / 服主必须看到的内容用这个。
:::

:::tip 小窍门
非必要但有用的小贴士。紫色,轻松语气,适合 "老兵才知道" 类内容。
:::

注意:::: 和 ::: 必须各占一整行,内部可以放任何 markdown(标题、列表、代码块等都可以嵌套)。

分割线#

text
---

kbd 键盘按键#

text
按 [[Esc]] 退出编辑模式。
保存用 [[Ctrl]]+[[S]]。

写作风格建议#

参考你站现有的几篇示范(rank/intro、player/getting-started 等)总结的风格:

1. 第一句话就告诉读者"这页讲什么"#

不要开篇先讲背景。读者来到这页是有目的的,直接告诉他这页能解决什么问题。

markdown
# rank.exe 程序配置

> 数据采集程序的下载、配置、运行 — 5 分钟搞定。

2. 用 callout 强调要点#

每篇至少有 1-2 个 callout,把"必须知道"的内容圈出来。读者扫读时眼睛会自动停在彩色块上。

3. 步骤用有序列表,每步一句话#

markdown
## 接入排位的三步

1. 在主站点"申请服务器" → 拿到 SRV 编号
2. 把 rank.exe 放到服务器 Logs 目录
3. 首次启动会自动生成 config.json,填入 SRV 编号即可

不要写成大段文字。读者扫一眼就能知道有几步、每步在做什么。

4. 路径、命令、字段名一律用 行内代码#

markdown
配置文件 `config.json` 在服务器的 `SquadGame/Logs/` 目录。

避免用引号包裹路径,看起来像普通字符串。

5. 有外链的、容易过期的内容,带上更新时间#

markdown
> 截至 2026-04 测试,上述步骤适用于 Squad v9.x。如有变化请反馈。

6. 截图要紧凑#

• 上传到编辑器,自动放在 /uploads/docs/yyyy-mm/
• 截图带白边的话,在系统截图工具里裁掉
• 大于 1600px 宽度的图,先在本地缩到 1200-1600 再传(等后端加自动压缩功能)
• 如果截图里有玩家 ID / IP 等敏感信息,用图片编辑器抹掉

7. 不要写主观评价#

❌ "我觉得这个机制不太合理" ✅ "本机制下,玩家 X 的情况会得到 Y 结果"

文档是工具书,不是论坛帖子。

常见的写作场景#

场景 1:加一篇全新的攻略#

1. 在后台 /docs_admin.php 点"新建页面"
2. 填标题、选分组(比如"玩家帮助文档")
3. 自动跳到编辑器,直接开写
4. 写完保存

优点:零文件操作,生效立等。 缺点:页面 slug 是自动生成的 custom/page-xxxxxx,URL 不太友好。如果想要 player/advanced-tactics 这种漂亮路径,就走方式二(创建 .md 文件 + 改 _meta.json)。

场景 2:修复一个错别字#

1. 直接在文档站打开那页
2. 右上角点"编辑"
3. 改完保存

5 秒搞定。

场景 3:整段替换更新某个机制说明#

打开页面 → 编辑 → 选中要替换的整段 → 删除 → + 插入新块 → 写新内容 → 保存。

或者更暴力的:在后台点"回退源文件",这页就回到 .md 状态;然后改 .md 文件覆盖上传,搞完后别再用网页编辑这页。

场景 4:批量更新(比如赛季更替)#

赛季换了,要批量改 10 篇文档里的"S6"为"S7"。

• 网页编辑器一篇一篇改 → 太慢
• 建议:每篇先在后台"回退源文件",然后在 docs-src/ 用 sed 批量替换:

bash
  cd /www/wwwroot/squad.cyou/docs-src
  grep -rl "S6" *.md | xargs sed -i 's/S6/S7/g'

• 检查没改坏后,直接生效

编辑权限边界#

如果你想给普通管理员也开放编辑权限,见 README_部署集成指南.md 里的 FAQ。

重要提醒#

最后:写文档是回报率最高的事情。一篇 1 小时写好的攻略,可能让 1000 个新玩家少卡 1 小时,效率 1000 倍。