forked from Gitlink/gitlink-cli
424 lines
9.1 KiB
Markdown
424 lines
9.1 KiB
Markdown
# 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)`)
|
||
- 图片 (``)
|
||
- 表格
|
||
- 粗体、斜体、引用
|
||
|
||
### 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)
|