gitlab-wiki

Wiki 技能

使用 glab api 原始端点调用管理 GitLab Wiki 页面。

快速参考

操作	命令模式	风险
列出页面	glab api projects/:id/wikis	-
获取页面	glab api projects/:id/wikis/:slug	-
创建页面	glab api projects/:id/wikis -X POST -f ...	⚠️
更新页面	glab api projects/:id/wikis/:slug -X PUT -f ...	⚠️
删除页面	glab api projects/:id/wikis/:slug -X DELETE	⚠️⚠️
上传附件	glab api projects/:id/wikis/attachments -X POST ...	⚠️

风险图例：- 安全 | ⚠️ 注意 | ⚠️⚠️ 警告 | ⚠️⚠️⚠️ 危险

何时使用此技能

始终在以下情况下使用：

• 用户提到“wiki”“wiki 页面”或“文档页面”
• 用户想在 GitLab 中创建／编辑项目文档
• 用户提到 wiki slug 或 wiki 内容
• 用户想向 wiki 上传图片

以下情况绝不要使用：

• 用户想要 README 文件（使用 gitlab-file）
• 用户想搜索 wiki 内容（使用 gitlab-search，并指定 wiki_blobs 范围）
• 用户想要外部文档（而非 GitLab wiki）

API 前提条件

必需的令牌范围： api

权限：

• 读取 wiki：Reporter 或更高角色（适用于私有仓库）
• 写入 wiki：Developer 或更高角色（或取决于项目设置）

注意： 项目必须启用 Wiki。

可用命令

列出 Wiki 页面

# List all wiki pages
glab api projects/123/wikis --method GET

# With pagination
glab api projects/123/wikis --paginate

# Using project path
glab api "projects/$(echo 'mygroup/myproject' | jq -Rr @uri)/wikis"

获取 Wiki 页面

# Get page by slug
glab api projects/123/wikis/home --method GET

# Get page with spaces in slug (URL-encode)
glab api "projects/123/wikis/$(echo 'Getting Started' | jq -Rr @uri)" --method GET

# Get nested page
glab api "projects/123/wikis/$(echo 'docs/installation' | jq -Rr @uri)" --method GET

# Get page with specific version
glab api "projects/123/wikis/home?version=abc123" --method GET

# Render HTML
glab api "projects/123/wikis/home?render_html=true" --method GET

创建 Wiki 页面

# Create simple page
glab api projects/123/wikis --method POST \
  -f title="Getting Started" \
  -f content="# Getting Started\n\nWelcome to the project!"

# Create with Markdown format
glab api projects/123/wikis --method POST \
  -f title="Installation Guide" \
  -f content="# Installation\n\n## Prerequisites\n\n- Node.js 18+\n- npm" \
  -f format="markdown"

# Create with custom slug
glab api projects/123/wikis --method POST \
  -f title="API Reference" \
  -f slug="api-docs" \
  -f content="# API Documentation\n\nEndpoints..."

# Create nested page (using directory in slug)
glab api projects/123/wikis --method POST \
  -f title="Database Setup" \
  -f slug="guides/database-setup" \
  -f content="# Database Setup\n\nConfiguration steps..."

更新 Wiki 页面

# Update content
glab api "projects/123/wikis/$(echo 'Getting Started' | jq -Rr @uri)" --method PUT \
  -f content="# Getting Started\n\n## Updated content\n\nNew information..."

# Update title and content
glab api projects/123/wikis/home --method PUT \
  -f title="Home Page" \
  -f content="# Welcome\n\nUpdated home page content."

# Change format (markdown, rdoc, asciidoc)
glab api projects/123/wikis/readme --method PUT \
  -f format="asciidoc" \
  -f content="= README\n\nAsciidoc content here."

删除 Wiki 页面

# Delete page
glab api projects/123/wikis/old-page --method DELETE

# Delete nested page (URL-encode)
glab api "projects/123/wikis/$(echo 'drafts/temp-page' | jq -Rr @uri)" --method DELETE

上传附件

# Upload image
glab api projects/123/wikis/attachments --method POST \
  -F "[email protected]"

# The response contains the markdown link to use
# {"file_name":"screenshot.png","file_path":"uploads/...","branch":"master","link":{"url":"...","markdown":"![screenshot](uploads/...)"}}

Wiki 页面选项

选项	类型	说明
title	string	页面标题（创建时必填）
slug	string	页面 URL slug（未提供时根据标题自动生成）
content	string	页面内容
format	string	内容格式：markdown（默认）、rdoc、asciidoc

格式支持

格式	扩展名	说明
markdown	.md	GitHub 风格的 Markdown
rdoc	.rdoc	Ruby 文档格式
asciidoc	.asciidoc	AsciiDoc 格式
org	.org	Org mode 格式

常见工作流

工作流 1：创建文档结构

project_id=123

# Create home page
glab api projects/$project_id/wikis --method POST \
  -f title="Home" \
  -f content="# Project Wiki\n\n- [Getting Started](Getting-Started)\n- [API Reference](API-Reference)\n- [FAQ](FAQ)"

# Create getting started guide
glab api projects/$project_id/wikis --method POST \
  -f title="Getting Started" \
  -f content="# Getting Started\n\n## Installation\n\n\`\`\`bash\nnpm install\n\`\`\`"

# Create API reference
glab api projects/$project_id/wikis --method POST \
  -f title="API Reference" \
  -f content="# API Reference\n\n## Endpoints\n\n| Method | Path | Description |\n|--------|------|-------------|\n| GET | /users | List users |"

工作流 2：备份 Wiki 内容

# List all pages and save content
mkdir -p wiki_backup
glab api projects/123/wikis --paginate | jq -r '.[].slug' | while read slug; do
  echo "Backing up: $slug"
  glab api "projects/123/wikis/$(echo "$slug" | jq -Rr @uri)" | \
    jq -r '.content' > "wiki_backup/${slug//\//_}.md"
done

工作流 3：迁移 Wiki 内容

# Get page from source project
content=$(glab api projects/123/wikis/home | jq -r '.content')
title=$(glab api projects/123/wikis/home | jq -r '.title')

# Create in target project
glab api projects/456/wikis --method POST \
  -f title="$title" \
  -f content="$content"

工作流 4：向 Wiki 页面添加图片

# 1. Upload image
response=$(glab api projects/123/wikis/attachments --method POST -F "[email protected]")

# 2. Get markdown link
markdown_link=$(echo "$response" | jq -r '.link.markdown')

# 3. Update page to include image
current_content=$(glab api projects/123/wikis/architecture | jq -r '.content')
new_content="$current_content

## Diagram

$markdown_link"

glab api projects/123/wikis/architecture --method PUT \
  -f content="$new_content"

工作流 5：列出所有 Wiki 页面及其标题

glab api projects/123/wikis --paginate | \
  jq -r '.[] | "[\(.title)](\(.slug))"'

Wiki Slug

Slug 是标题的 URL 安全版本：

• 空格会变成连字符：Getting Started → Getting-Started
• 特殊字符会被移除
• 保留大小写

对于嵌套页面，请在 slug 中使用目录结构：

• guides/installation 会在 guides/ 下创建页面

故障排查

问题	原因	解决方案
404 Not Found	Wiki 已禁用或页面不存在	在项目设置中启用 Wiki，并检查 slug
403 Forbidden	没有写入权限	需要 Developer 或更高角色，或检查 Wiki 权限
内容为空	编码问题	检查内容字符串的转义
Slug 不匹配	自动生成的 slug 不同	显式设置 slug 参数
上传失败	内容类型错误	文件上传时使用 -F 标志

最佳实践

1. 使用有意义的 slug：保持 URL 易读且一致
2. 创建主页：从 home/index 页面开始
3. 使用相对链接：通过 slug 在 Wiki 页面之间建立链接
4. 采用结构化组织：使用 slug 目录进行整理
5. 添加图片：上传屏幕截图和示意图，让内容更清晰

相关文档

• API 助手
• 安全防护措施
• 快速参考
• GitLab Wiki API