GitLab教程(14): Wiki与文档管理

GitLab Wiki提供了内置的文档管理功能，支持Markdown编写和版本控制。本文将介绍如何使用GitLab Wiki管理项目文档。

启用Wiki

# 启用Wiki功能
# Project > Settings > General > Visibility
# 勾选 Wiki

# 访问Wiki
# Project > Plan > Wiki

# Wiki特点
- 使用Git存储，支持版本控制
- 支持Markdown、AsciiDoc、RDoc格式
- 可以克隆到本地编辑
- 支持文件附件
- 全文搜索

创建页面

# 创建首页
# Wiki > Create your first page

Title: Home
Format: Markdown
Content:

# 项目文档

欢迎查看项目文档！

## 快速开始
- [安装指南](installation)
- [快速入门](quickstart)
- [配置说明](configuration)

## 开发文档
- [架构设计](architecture)
- [API文档](api-reference)
- [数据库设计](database-design)

## 其他
- [FAQ](faq)
- [更新日志](changelog)
- [贡献指南](contributing)

# 创建子页面
# Wiki > New page

Title: installation
Content:

# 安装指南

## 系统要求
- Node.js 18+
- PostgreSQL 14+
- Redis 7+

## 安装步骤

```bash
# 克隆项目
git clone https://gitlab.com/group/project.git
cd project

# 安装依赖
npm install

# 配置环境变量
cp .env.example .env
vim .env

# 启动服务
npm start
```

## 验证安装
访问 http://localhost:3000 确认服务正常运行。

页面组织

# 使用目录结构组织页面

# 创建目录页面
Title: guides/installation  # 创建在guides目录下

# 推荐的文档结构
Home (首页)
├── getting-started/
│   ├── installation
│   ├── quickstart
│   └── configuration
├── user-guide/
│   ├── basic-usage
│   ├── advanced-features
│   └── troubleshooting
├── developer/
│   ├── architecture
│   ├── api-reference
│   ├── database-design
│   └── contributing
├── operations/
│   ├── deployment
│   ├── monitoring
│   └── backup
└── changelog

# 页面内链接
[安装指南](getting-started/installation)
[查看API](developer/api-reference)
[返回首页](Home)

侧边栏

# 创建自定义侧边栏
# 创建名为 _sidebar 的页面

Title: _sidebar
Content:

### 📚 文档导航

**入门指南**
- [首页](Home)
- [安装](installation)
- [快速开始](quickstart)

**用户指南**
- [基本使用](basic-usage)
- [高级功能](advanced-features)
- [常见问题](faq)

**开发文档**
- [架构设计](architecture)
- [API参考](api-reference)
- [数据库](database-design)

**运维**
- [部署指南](deployment)
- [监控](monitoring)
- [备份恢复](backup)

---

[更新日志](changelog) | [贡献](contributing)

Markdown增强

# GitLab支持的Markdown扩展

# 任务列表
- [x] 完成安装文档
- [x] 完成配置文档
- [ ] 完成API文档
- [ ] 完成部署文档

# 表格
| 功能 | 状态 | 负责人 |
|-----|------|-------|
| 登录 | 完成 | 张三 |
| 注册 | 进行中 | 李四 |
| 支付 | 计划中 | 王五 |

# 代码块（带语法高亮）
```javascript
const express = require('express');
const app = express();

app.get('/', (req, res) => {
  res.send('Hello World!');
});

app.listen(3000);
```

# 告示框
> **Note**: 这是一个提示信息。

> **Warning**: 这是一个警告信息。

# Mermaid图表
```mermaid
graph LR
    A[开始] --> B{条件判断}
    B -->|是| C[执行A]
    B -->|否| D[执行B]
    C --> E[结束]
    D --> E
```

# 数学公式 (KaTeX)
$E = mc^2$

$$
\sum_{i=1}^{n} x_i = x_1 + x_2 + \cdots + x_n
$$

# 折叠内容

点击展开详细信息

这里是详细的内容...

- 项目1
- 项目2
- 项目3

本地编辑Wiki

# Wiki是一个独立的Git仓库

# 克隆Wiki仓库
git clone git@gitlab.com:group/project.wiki.git
cd project.wiki

# 目录结构
project.wiki/
├── Home.md
├── installation.md
├── quickstart.md
├── architecture.md
├── _sidebar.md
└── uploads/
    └── image.png

# 创建或编辑页面
vim api-reference.md

# 提交并推送
git add .
git commit -m "Add API reference documentation"
git push origin main

# 变更会自动同步到GitLab Wiki

文件附件

# 上传附件
# 编辑页面时，将文件拖放到编辑区域
# 或点击 "Attach a file" 按钮

# 上传后生成的链接
![架构图](uploads/abc123/architecture.png)
[下载PDF](uploads/def456/document.pdf)

# 附件存储在Wiki仓库的uploads目录
project.wiki/
└── uploads/
    ├── abc123/
    │   └── architecture.png
    └── def456/
        └── document.pdf

# 引用项目仓库中的图片
![Logo](/uploads/project-logo.png)
![Diagram](https://gitlab.com/group/project/-/raw/main/docs/diagram.png)

版本历史

# 查看页面历史
# 页面右上角 > Page history

# 历史记录显示
┌─────────────────────────────────────────────────────────────┐
│  Page history: installation                                 │
├─────────────────────────────────────────────────────────────┤
│  Version    Author      Date            Message             │
│  abc123     @zhangsan   2 hours ago     Update requirements │
│  def456     @lisi       1 day ago       Add Docker section  │
│  ghi789     @zhangsan   3 days ago      Initial version     │
└─────────────────────────────────────────────────────────────┘

# 比较版本
# 选择两个版本 > Compare

# 恢复旧版本
# 点击版本 > Revert

搜索

# Wiki全文搜索
# Wiki页面右上角的搜索框

# 搜索支持
- 页面标题
- 页面内容
- 附件名称

# 搜索结果显示
搜索: "installation"

结果:
├── installation (页面)
│   "...按照以下步骤完成installation..."
├── quickstart (页面)
│   "...首先完成installation，然后..."
└── deployment (页面)
    "...与installation类似，部署时需要..."

项目README

# 除了Wiki，项目README也是重要的文档

# README.md 模板
# Project Name

项目简短描述。

## 特性

- ✅ 特性1
- ✅ 特性2
- ✅ 特性3

## 安装

```bash
npm install my-package
```

## 快速开始

```javascript
import { Client } from 'my-package';

const client = new Client();
client.connect();
```

## 文档

完整文档请查看 [Wiki](../../wikis/home)。

## 贡献

欢迎提交PR！请先阅读[贡献指南](CONTRIBUTING.md)。

## 许可证

[MIT](LICENSE)

文档最佳实践

• 保持更新：代码变更时同步更新文档
• 结构清晰：使用目录组织文档
• 提供示例：代码示例比描述更有效
• 使用模板：统一文档格式
• 添加图表：使用Mermaid绘制流程图
• 版本控制：重要变更记录在更新日志

总结

本文介绍了GitLab Wiki的使用方法，包括创建页面、组织结构、Markdown增强和本地编辑。良好的文档是项目成功的关键因素。

下一篇我们将学习GitLab备份与恢复。

cnbugsai

打赏 海报 链接