# wiki +create

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

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

## 命令

```bash
# 创建简单页面（使用 --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 格式

```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: 创建首页

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

```bash
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: 从现有文件创建

```bash
# 从 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: 创建代码文档

```bash
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 页面

```bash
#!/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 自动处理：

```bash
# 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=="
  }'
```

### 多行内容处理

```bash
# 方法 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:** 页面标题已存在。解决方法：
```bash
# 查看现有页面
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 语法：
```bash
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. 标题命名规范

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

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

### 2. 内容模板

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

```bash
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. 从文件创建

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

```bash
# 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. 批量创建工作流

```bash
#!/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

```bash
#!/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](../SKILL.md)
- [wiki +update](wiki-update.md) — 更新 Wiki 页面
- [wiki +delete](wiki-delete.md) — 删除 Wiki 页面
- [gitlink-shared](../../gitlink-shared/SKILL.md)
