---
name: wiki-writing
description: 在 Gitea wiki 中编写和维护文档。规范格式、操作流程、排版约定。
version: 1.0.0
author: 星月
metadata:
  hermes:
    tags: [wiki, documentation, gitea, writing]
---

# Wiki 编写规范

在 Gitea 仓库的 wiki 中编写和维护文档。

## Wiki 仓库操作

Gitea wiki 本质是一个独立的 git 仓库，地址为 `<repo>.wiki.git`。

### Clone

```bash
git clone https://git.shazhou.work/<owner>/<repo>.wiki.git /tmp/<repo>-wiki
```

### 编辑流程

```bash
cd /tmp/<repo>-wiki

# 编辑或新建 .md 文件
# 文件名即 wiki 页面名（用 kebab-case，如 cursor-agent-setup.md）

git add -A
git commit -m "docs: 简要说明改了什么"
git push
```

### 页面命名

- 文件名用 **kebab-case**：`cursor-agent-setup.md`，不要用空格或中文文件名
- `Home.md` 是 wiki 首页，必须存在
- 文件名会直接显示为 wiki 侧边栏的页面标题

## 排版约定

### 语言与标点

- **中文文档用中文标点**：`，。：；！？（）【】「」`
- **英文/代码文档用英文标点**
- 不要在中文文档中混用半角标点（Gitea 的 "ambiguous Unicode" 警告可忽略，那是给代码文件设计的）

### 中英文混排

- 中文与英文/数字之间加一个空格：`使用 Cursor Agent 做编码任务`
- 中文与代码块之间加空格：`用 `tea` 命令读取`
- 专有名词保持原文：Gitea、Cursor、Hermes，不要翻译

### 文档结构

```markdown
# 标题

> 作者：xxx | 日期

## 背景
（为什么需要这个）

## 前置条件
（需要什么）

## 步骤
### 1. 第一步
### 2. 第二步

## 注意事项
（坑和经验）
```

### 代码块

- 始终指定语言标记：` ```bash `、` ```python `、` ```markdown `
- 命令用 `bash`，配置文件用对应格式
- 代码块内的注释用英文（避免终端编码问题）

### 元信息

每篇文档开头加作者和日期：

```markdown
> 作者：星月 | 2026-04-22
```

## 内容原则

1. **面向 agent 伙伴** — 假设读者是新加入的 Hermes agent，从零开始
2. **可执行** — 每个步骤给出可直接复制运行的命令
3. **说明 why** — 不只是 how，还要解释为什么这样做
4. **记录坑** — 踩过的坑写进"注意事项"，帮后来者避雷

## 常见操作

### 新建 wiki 页面

```bash
cd /tmp/<repo>-wiki
cat > new-page.md << 'EOF'
# 页面标题

> 作者：你的名字 | 日期

内容...
EOF

git add new-page.md
git commit -m "docs: add new-page"
git push
```

### 更新现有页面

```bash
cd /tmp/<repo>-wiki
git pull  # 先拉最新
# 编辑文件...
git add -A
git commit -m "docs: 说明改了什么"
git push
```

### 查看 wiki 地址

页面在浏览器中的 URL 为：
```
https://git.shazhou.work/<owner>/<repo>/wiki/<page-name>
```
其中 `<page-name>` 对应文件名去掉 `.md` 后缀。

## Pitfalls

1. **wiki 仓库和代码仓库是分开的** — 它们有独立的 git 历史，push wiki 不会触发代码仓库的 CI
2. **Gitea 的 Unicode 警告是误报** — 中文文档里的中文标点会触发 "ambiguous Unicode characters" 警告，忽略即可
3. **文件名避免特殊字符** — 用 kebab-case，不要用空格、中文、或 URL 不友好的字符
4. **先 pull 再改** — wiki 可能被多人编辑，避免冲突