gitlink-cli/skills/gitlink-wiki/references/wiki-create.md

wiki +create

前置条件： 先阅读 ../../gitlink-shared/SKILL.md 了解认证、全局参数和安全规则。 ⚠️ 写入操作 — 执行前必须确认用户意图。

创建新的 Wiki 页面。支持直接提供内容或从文件读取。

命令

# 创建简单页面（使用 --content）
gitlink-cli wiki +create --title "Home" --content "# Welcome\n\nThis is the home page."

# 创建页面（从文件读取）
gitlink-cli wiki +create --title "API Reference" --file api.md

# 创建页面并添加提交消息
gitlink-cli wiki +create --title "Getting Started" \
  --content "# Getting Started\n\n..." \
  --message "Initial documentation"

# 创建多行内容页面
gitlink-cli wiki +create --title "Guide" --content "# User Guide

## Installation
Run the following command:

\`\`\`bash
npm install
\`\`\`

## Usage
\`\`\`bash
npm start
\`\`\`"

参数

参数	Short	必填	说明
--title	-t	是	Wiki 页面标题
--content	-c	是*	Wiki 页面内容（纯文本，与 --file 二选一）
--file	-f	是*	从文件读取内容（与 --content 二选一）
--message	-m	否	提交消息（可选）
--owner		否	仓库所有者（自动从 git remote 解析）
--repo		否	仓库名称（自动从 git remote 解析）
--format		否	输出格式: json/table/yaml
--debug		否	开启调试输出

• --content 和 --file 必须指定其中一个

返回字段

Table 格式

列名	说明
title	创建的页面标题
message	操作结果消息

JSON 格式

{
  "ok": true,
  "data": {
    "title": "Home",
    "message": "Wiki page created successfully"
  }
}

Workflow

1. Confirm the page title and content with the user.
2. Check if the page already exists (optional, use wiki +view).
3. Execute gitlink-cli wiki +create --title "<title>" --content "<content>".
4. Report the creation result and page URL.

[!CAUTION] This is a Write Operation — confirm user intent before executing.

API

POST https://gateway.gitlink.org.cn/api/wiki/open/createWiki
Body: {
  "owner": "...",
  "repo": "...",
  "projectId": 123,
  "pageName": "<title>",
  "title": "<title>",
  "content_base64": "<base64-encoded-content>",
  "message": "<optional-message>"
}

工作流程：

1. CLI 获取 project_id
2. 将内容 Base64 编码为 content_base64
3. 调用 Gateway API 创建页面
4. 返回创建结果

使用场景

场景 1: 创建首页

当用户请求"创建项目首页"时：

gitlink-cli wiki +create --title "Home" \
  --content "# Project Home

## Overview
This project is a CLI tool for GitLink platform.

## Features
- Repository management
- Issue tracking
- Pull requests

## Getting Started
See the [Getting Started](Getting-Started) page."

场景 2: 从现有文件创建

# 从 README.md 创建 Wiki
gitlink-cli wiki +create --title "Home" --file README.md

# 从多个文件创建多个页面
gitlink-cli wiki +create --title "API Reference" --file docs/api.md
gitlink-cli wiki +create --title "User Guide" --file docs/guide.md

场景 3: 创建代码文档

gitlink-cli wiki +create --title "CLI Reference" --content "# CLI Commands

## Repository Commands
\`\`\`bash
gitlink-cli repo +list
gitlink-cli repo +create -n my-project
\`\`\`

## Issue Commands
\`\`\`bash
gitlink-cli issue +list
gitlink-cli issue +create -t \"Bug: ...\"
\`\`\`"

场景 4: 批量创建 Wiki 页面

#!/bin/bash
# 从 docs/ 目录批量创建 Wiki 页面

for mdfile in docs/*.md; do
    # 从文件名提取标题（去掉 .md 后缀）
    title=$(basename "$mdfile" .md)

    echo "Creating Wiki page: $title"
    gitlink-cli wiki +create --title "$title" --file "$mdfile"
done

内容编码

Base64 自动处理

无需手动编码 — CLI 自动处理：

# CLI 会自动将以下内容 Base64 编码
gitlink-cli wiki +create --title "Test" --content "Hello, World!"

# 等效于手动编码（不推荐）
gitlink-cli api POST "https://gateway.gitlink.org.cn/api/wiki/open/createWiki" \
  --body '{
    "owner": "...",
    "repo": "...",
    "projectId": 123,
    "pageName": "Test",
    "title": "Test",
    "content_base64": "SGVsbG8sIFdvcmxkIQ=="
  }'

多行内容处理

# 方法 1: 使用 \n 换行
gitlink-cli wiki +create --title "Test" \
  --content "Line 1\nLine 2\nLine 3"

# 方法 2: 使用 $'' 引号（支持 \n）
gitlink-cli wiki +create --title "Test" --content $'Line 1\nLine 2\nLine 3'

# 方法 3: 从文件读取（推荐）
cat << 'EOF' > temp.md
Line 1
Line 2
Line 3
EOF
gitlink-cli wiki +create --title "Test" --file temp.md

常见问题

Q: 创建失败提示 "page already exists"？

A: 页面标题已存在。解决方法：

# 查看现有页面
gitlink-cli wiki +list

# 使用不同的标题，或先删除现有页面
gitlink-cli wiki +delete --title "Old Title"
gitlink-cli wiki +create --title "New Title" --content "..."

Q: 内容显示格式错误？

A: 确保：

1. Markdown 语法正确
2. 使用 \n 表示换行（单行字符串）
3. 或从文件读取（保留原始格式）

Q: 如何创建包含代码块的页面？

A: 使用正确的 Markdown 语法：

gitlink-cli wiki +create --title "Code Examples" \
  --content '# Code Examples

## JavaScript
\`\`\`javascript
console.log("Hello");
\`\`\`

## Python
\`\`\`python
print("Hello")
\`\`\`'

Q: 支持哪些 Markdown 语法？

A: GitLink Wiki 支持：

• 标题 (#, ##, ###)
• 列表（有序、无序）
• 代码块（```）
• 链接 ([text](url))
• 图片 (![alt](url))
• 表格
• 粗体、斜体、引用

Q: 可以创建 HTML 内容吗？

A: GitLink Wiki 主要支持 Markdown，部分 HTML 可能被过滤。建议使用标准 Markdown 语法。

错误处理

错误	原因	解决方案
required flag --title is missing	未指定标题	添加 --title "Page Title"
--content or --file is required	未提供内容	添加 --content "..." 或 --file file.md
failed to read file	文件不存在或无权限	检查文件路径和权限
page already exists	标题已存在	使用不同标题或先删除现有页面
401 Unauthorized	未登录或 Token 过期	运行 gitlink-cli auth login
403 Forbidden	无权限创建 Wiki	检查是否有项目写入权限

最佳实践

1. 标题命名规范

# 推荐：使用连字符连接单词
"Getting-Started"
"API-Reference"
"User-Guide"

# 避免：空格和特殊字符
"Getting Started"  # 需要引号
"API/Reference"    # 斜杠可能被误解

2. 内容模板

创建文档时使用标准模板：

gitlink-cli wiki +create --title "Page Title" --content '# Page Title

## Overview
Brief description of the page.

## Details
Detailed content.

## Examples
\`\`\`bash
Example code
\`\`\`

## See Also
- [Related Page 1](Related-Page-1)
- [Related Page 2](Related-Page-2)'

3. 从文件创建

对于复杂内容，先创建文件再导入：

# 1. 创建本地 Markdown 文件
cat > home.md << 'EOF'
# Home

Welcome to the project!
EOF

# 2. 从文件创建 Wiki
gitlink-cli wiki +create --title "Home" --file home.md

# 3. 清理临时文件
rm home.md

4. 批量创建工作流

#!/bin/bash
# 批量创建项目文档

# 定义页面列表
declare -A pages=(
  ["Home"]="home.md"
  ["Getting-Started"]="getting-started.md"
  ["API-Reference"]="api.md"
  ["FAQ"]="faq.md"
)

# 遍历创建
for title in "${!pages[@]}"; do
  file="${pages[$title]}"
  if [ -f "$file" ]; then
    echo "Creating: $title from $file"
    gitlink-cli wiki +create --title "$title" --file "$file"
  else
    echo "Warning: $file not found, skipping $title"
  fi
done

完整示例

示例：创建完整项目 Wiki

#!/bin/bash
# 为新项目创建完整的 Wiki 文档结构

# 1. 创建首页
gitlink-cli wiki +create --title "Home" --content '# Project Home

## Overview
This is a demonstration project for gitlink-cli Wiki.

## Documentation
- [Getting Started](Getting-Started)
- [API Reference](API-Reference)
- [Contributing](Contributing)

## Support
- [FAQ](FAQ)
- [Contact Us](Contact-Us)'

# 2. 创建入门指南
gitlink-cli wiki +create --title "Getting-Started" --content '# Getting Started

## Installation
\`\`\`bash
npm install
\`\`\`

## Configuration
\`\`\`bash
cp .env.example .env
\`\`\`

## Running
\`\`\`bash
npm start
\`\`\`'

# 3. 创建 API 文档
gitlink-cli wiki +create --title "API-Reference" --content '# API Reference

## Endpoints

### GET /api/users
Get user information.

### POST /api/issues
Create a new issue.

## Examples
See the [Examples](Examples) page.'

echo "Wiki documentation structure created successfully!"

References

• gitlink-wiki
• wiki +update — 更新 Wiki 页面
• wiki +delete — 删除 Wiki 页面
• gitlink-shared