wiki-js-v3
# Wiki.js V3 Skill – All-Encompassing Wiki Administration
**Ersetzt:** `wiki-js-v2` (nur Pages + Assets)
## 🎯 Features
| Feature | V2 | V3 |
|---------|----|----|
| Pages (CRUD) | ✅ | ✅ |
| Assets (Upload/List) | ✅ | ✅ |
| **Move/Copy Pages** | ❌ | ✅ |
| **Page History** | ❌ | ✅ |
| **Version Restore** | ❌ | ✅ |
| **Render (HTML/PDF)** | ❌ | ✅ |
| **Search (Full-Text + Tags)** | ❌ | ✅ |
| **Page Tree/Hierarchy** | ❌ | ✅ |
| **Tags (CRUD)** | ❌ | ✅ |
| **Asset Folders** | ✅ | ✅ |
| **Asset Delete** | ❌ | ✅ |
| **Multi-Locale** | ✅ | ✅ |
| **Retry + Backoff** | ✅ | ✅ |
| **Path-First + ID** | ✅ | ✅ |
---
## 📦 Installation
```bash
# Skill bereits installiert unter:
~/.openclaw/workspace/skills/wiki-js-v3/
# CLI-Wrapper (optional, für direkten Terminal-Zugriff):
chmod +x ~/.openclaw/workspace/skills/wiki-js-v3/bin/wiki.js
ln -s ~/.openclaw/workspace/skills/wiki-js-v3/bin/wiki.js ~/.local/bin/wiki
```
**Environment:**
```bash
export WIKIJS_URL="https://your-wiki.example.com"
export WIKIJS_TOKEN="your_api_key_here"
export WIKIJS_LOCALE="de" # Optional, default: de
```
---
## 🔧 API Coverage
### GraphQL Operations
| Category | Operations |
|----------|-----------|
| **Pages** | `single`, `singleByPath`, `list`, `create`, `update`, `delete`, `move`, `render`, `history`, `restoreVersion` |
| **Search** | `search(query, limit)` |
| **Tags** | `list`, `create`, `delete` |
| **Assets** | `list`, `createFolder`, `delete` |
### REST Operations
| Endpoint | Use Case |
|----------|----------|
| `POST /u` | File upload (multipart/form-data) |
| `GET /f/:hash/:filename` | Static asset serving |
---
## 📝 CLI Reference
### Pages
```bash
# Create or update (idempotent)
wiki upsert docs/setup "Setup Guide" @content.md "setup,wiki"
wiki upsert docs/api "API Reference" "## Overview\n..." "api,docs"
# Get page content
wiki get docs/setup
wiki get 42 # by ID
# Delete page
wiki delete docs/old-page
wiki delete 42
# Move page (changes path)
wiki move docs/old docs/new
# Copy page (creates new page)
wiki copy docs/template docs/new-page
# Show page history
wiki history docs/setup
# Restore specific version
wiki restore docs/setup --version=3
# Render page
wiki render docs/setup --format=html
wiki render docs/setup --format=pdf > setup.pdf
```
### Search
```bash
# Full-text search
wiki search "docker"
# With tag filter
wiki search "kubernetes" --tags="devops,cloud"
# Limit results
wiki search "api" --limit=50
```
### Tree / Hierarchy
```bash
# List all pages
wiki tree
# Filter by path prefix
wiki tree --path=docs
# Control depth
wiki tree --depth=5
```
### Tags
```bash
# List all tags
wiki tags
# Create tag
wiki tags create "new-feature"
# Delete tag
wiki tags delete "deprecated"
```
### Assets
```bash
# List assets
wiki assets
wiki assets --folder=images
wiki assets --kind=IMAGE
# Upload file
wiki upload screenshot.png
wiki upload doc.pdf --folder=documents --name="manual.pdf"
# Delete asset
wiki asset-delete 42
# Create folder
wiki mkdir 0 images "Bilder"
```
### Options
```bash
--pretty, -p Human-readable output (default: JSON)
--locale, -l de Locale override
--private Create private page
--draft Create unpublished page
```
---
## 🔄 Error Handling
| Error | Handling |
|-------|----------|
| `413 Payload Too Large` | Throws descriptive error (chunking not auto-applied for pages) |
| `401 Unauthorized` | Clear token error message |
| `ECONNREFUSED` | Auto-retry with exponential backoff (3 attempts) |
| `Timeout` | 30s default, configurable via `WIKIJS_TIMEOUT` |
---
## 📐 Architecture
```
bin/wiki.js
├── GraphQL Client (query, mutation)
├── REST Upload (form-data)
├── Path Resolution (singleByPath)
├── CLI Parser (arg parsing)
└── Output Formatter (JSON / Pretty)
```
**Dependencies:**
- Node.js built-in modules only
- `form-data` for file uploads (installed on-demand)
---
## 🔐 Security
- Token **only** via environment variable (`WIKIJS_TOKEN`)
- No token logging
- Input validation (null bytes, size limits)
- Path sanitization (strips leading `/`)
---
## 📤 Examples
### Create Documentation Page
```bash
# Write content to file
cat > /tmp/api.md << 'EOF'
# API Reference
## Authentication
All requests require a Bearer token...
## Endpoints
- `GET /api/v1/pages` - List pages
- `POST /api/v1/pages` - Create page
EOF
# Upsert to Wiki
wiki upsert docs/api "API Reference" @/tmp/api.md "api,reference" --pretty
```
### Upload Screenshot and Embed
```bash
# Upload image
wiki upload screenshot.png --folder=images --name="api-auth-flow.png"
# Output: {"id":47,"url":"/f/a3f9b2/api-auth-flow.png",...}
# Create page with embedded image
wiki upsert docs/api-auth "API Authentication" '' "api"
```
### Batch Update via Script
```bash
#!/bin/bash
for file in docs/*.md; do
name=$(basename "$file" .md)
wiki upsert "docs/$name" "$name Documentation" "@$file" "docs"
done
```
---
## 🆚 Migration from V2
| V2 Command | V3 Command |
|------------|-----------|
| `wiki-v2 upsert ...` | `wiki upsert ...` |
| `wiki-v2 get ...` | `wiki get ...` |
| `wiki-v2 delete ...` | `wiki delete ...` |
| `wiki-v2 search ...` | `wiki search ...` |
| `wiki-v2 upload ...` | `wiki upload ...` |
| `wiki-v2 assets ...` | `wiki assets ...` |
| `wiki-v2 mkdir ...` | `wiki mkdir ...` |
| – | `wiki move ...` |
| – | `wiki copy ...` |
| – | `wiki history ...` |
| – | `wiki restore ...` |
| – | `wiki render ...` |
| – | `wiki tree ...` |
| – | `wiki tags ...` |
| – | `wiki asset-delete ...` |
---
## 🐛 Troubleshooting
| Issue | Solution |
|-------|----------|
| `WIKIJS_TOKEN not set` | `export WIKIJS_TOKEN=...` |
| `Page not found` | Check path (no leading `/`) |
| `GraphQL Error: Unauthorized` | Token invalid or expired |
| `GraphQL Error: Forbidden` | **API key lacks write permissions** – create new key with write access in Admin UI |
| `Upload failed: 413` | File too large (>10MB) |
| `Timeout after 30s` | Increase `WIKIJS_TIMEOUT=60000` |
| `Cannot read properties of undefined (reading 'map')` | **Fixed in V3.1** – always include `tags: []` in update mutations |
## ⚠️ API Key Permissions
Wiki.js API keys have **per-key permissions**, not per-group permissions.
| JWT Claim | Meaning |
|-----------|---------|
| `api:1` | API Key ID 1 – may have different permissions than Key 2 |
| `grp:1` | Group ID 1 – does NOT determine write access |
**If `update` returns "Forbidden":**
1. Open Wiki.js Admin UI
2. Go to **API Keys**
3. Create new key with **write permissions** or edit existing key
4. Use the new key in `WIKIJS_TOKEN`
---
## 📚 Wiki.js API Reference
- GraphQL Schema: `{WIKIJS_URL}/graphql-playground`
- REST Upload: `POST {WIKIJS_URL}/u`
- Static Assets: `GET {WIKIJS_URL}/f/:hash/:filename`
---
*Version: 3.0 | Status: All-encompassing | Replaces: wiki-js-v2*
标签
skill
ai
