一、什么是 Repo Wiki，解决什么核心问题

Repo Wiki（仓库 Wiki）是 GitHub / GitLab 内置的轻量级文档系统，直接挂载在代码仓库之下，专为项目提供结构化的在线文档空间。

二、Wiki vs README vs docs 目录对比

项目中常见的文档存放位置有三种，适用场景各不相同：

三、GitHub Wiki 启用与基础操作

3.1 启用 Wiki

1. 打开目标仓库页面，点击顶部标签栏的 Wiki
2. 如果是首次访问，GitHub 会提示 “Create the first page”，点击按钮即可启用
3. 首页默认文件名为 Home.md，作为 Wiki 的入口页面
4. 如果仓库 Settings 中 Wiki 被禁用，需由管理员前往 Settings → Features → Wikis 勾选启用

3.2 基础页面操作

四、Wiki 页面创建与 Markdown 编写

4.1 支持的格式

GitHub Wiki 支持多种标记语言，通过文件扩展名指定：

4.2 Wiki 内链与资源引用

# Wiki 页面内部链接（使用文件名，不含扩展名）
[[Getting-Started]]
[[API-Reference|API 参考文档]]  

# 引用 Wiki 中的图片（图片需上传到 Wiki）
![架构图](/uploads/architecture.png)

# 引用仓库中的文件
[查看源码](https://github.com/user/repo/blob/main/src/main.py)

4.3 Wiki 页面元数据（YAML Front Matter）

虽然 GitHub Wiki 不强制要求 Front Matter，但配合自定义工具时可用于分类和排序：

---
title: 快速开始
category: getting-started
order: 1
updated: 2026-07-15
---

# 快速开始

本文档介绍如何安装和运行项目...

五、侧边栏导航与页面组织

5.1 自动侧边栏

GitHub Wiki 会自动根据 _Sidebar.md 文件生成左侧导航栏。若未创建该文件，侧边栏默认按字母顺序列出所有页面。

5.2 自定义 _Sidebar.md

# _Sidebar.md（Wiki 中的特殊文件名）

## 快速导航

- [[Home|首页]]
- [[Getting-Started|快速开始]]
- [[Installation|安装指南]]

## 使用文档

- [[Configuration|配置说明]]
- [[API-Reference|API 参考]]
- [[Plugins|插件开发]]

## 进阶内容

- [[Architecture|系统架构]]
- [[Design-Notes|设计决策]]
- [[Performance|性能优化]]

## 社区

- [[Contributing|贡献指南]]
- [[Changelog|更新日志]]
- [[FAQ|常见问题]]

5.3 其他特殊页面

六、Wiki 本地 Git 克隆编辑工作流

6.1 克隆 Wiki 仓库

# Wiki 仓库地址 = 主仓库地址 + .wiki.git
git clone https://github.com/user/repo.wiki.git
cd repo.wiki
ls
Home.md  _Sidebar.md  Getting-Started.md  API-Reference.md

6.2 本地编辑后推送

1. 用 VS Code 或任意编辑器打开 Wiki 仓库目录
2. 编辑或新建 .md 文件，使用本地 Git 进行版本管理
3. 本地编辑可使用 Git 分支、diff 等完整工具链，比网页编辑高效得多
4. 完成后推送回远程 Wiki 仓库

git add .
git commit -m "docs: 添加 API 参考文档和配置说明"
git push origin master

6.3 SSH 克隆

# 如果主仓库使用 SSH，Wiki 同样支持
git clone git@github.com:user/repo.wiki.git

七、GitLab Wiki 特性与差异

7.1 核心差异对比

7.2 GitLab Wiki API 操作示例

# 创建 Wiki 页面
curl --request POST \
  --header "PRIVATE-TOKEN: <your_token>" \
  --data "title=Getting+Started" \
  --data "content=%23+Getting+Started%0A%0AWelcome..." \
  "https://gitlab.com/api/v4/projects/<id>/wikis"

# 列出所有 Wiki 页面
curl --header "PRIVATE-TOKEN: <your_token>" \
  "https://gitlab.com/api/v4/projects/<id>/wikis"

八、开源项目 Wiki 协作规范

8.1 开源项目 Wiki 典型结构

Wiki/
├── Home.md              # 首页：项目简介 + Wiki 导航
├── _Sidebar.md          # 侧边栏导航
├── Getting-Started.md   # 新手快速上手
├── Installation.md      # 详细安装步骤
├── Configuration.md     # 配置项完整说明
├── Tutorials/           # 教程系列
│   ├── Basic-Usage.md
│   ├── Advanced-Features.md
│   └── Examples.md
├── Architecture.md      # 架构设计文档
├── Contributing.md      # 贡献流程（可镜像仓库 CONTRIBUTING.md）
├── Code-of-Conduct.md   # 行为准则
├── Changelog.md         # 版本变更记录
└── FAQ.md               # 常见问题解答

8.2 协作规范

九、Wiki 最佳实践与组织模板

9.1 信息架构原则

Tutorials-Basic-Usage.md
Tutorials-Advanced-Features.md
API-Endpoints-Auth.md
API-Endpoints-Users.md

9.2 Home.md 首页模板

# ProjectName Wiki

> 一句话描述项目。

## 快速开始
如果你是第一次接触本项目，请按顺序阅读：
1. [[Getting-Started|快速开始]] — 5 分钟上手
2. [[Installation|安装指南]] — 详细安装步骤
3. [[Configuration|配置说明]] — 所有配置项说明

## 文档目录
- [[Architecture|系统架构]]
- [[API-Reference|API 参考]]
- [[Tutorials-Basic-Usage|基础教程]]
- [[Tutorials-Advanced-Features|进阶教程]]
- [[Deployment|部署指南]]

## 社区
- [[Contributing|贡献指南]] — 如何参与开发
- [[FAQ|常见问题]] — 问题排查
- [[Changelog|更新日志]] — 版本变更记录

9.3 Wiki 与仓库文档同步策略

# .github/workflows/sync-wiki.yml
name: Sync Wiki
on:
  push:
    paths:
      - 'docs/**'
      - 'CHANGELOG.md'
jobs:
  sync-wiki:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: Andrew-Chen-Wang/github-wiki-action@v4
        with:
          path: docs/
          token: ${{ secrets.GITHUB_TOKEN }}

十、常见问题与解决方案