---
name: gitea-wiki
description: Manage Gitea wiki pages. Use when user asks about wiki pages, or when agent reaches for GitHub wiki, github wiki API, or any wiki operation on a Gitea-hosted repo. (Child skill of `gitea` parent skill.)
version: 1.0.0
---

# Gitea Wiki Management

## Overview

Gitea wikis are git-backed Markdown repositories attached to each repository. Each wiki page is a Markdown file, stored in a dedicated `.wiki` git branch.

## Interaction Methods

| Method | Priority | Notes |
|--------|----------|-------|
| **MCP Server** (`gitea-mcp`) | **Preferred** | `wiki_list_pages`, `wiki_get_page`, `wiki_create_page`, `wiki_update_page`, `wiki_delete_page` |
| **REST API** (direct curl) | Secondary | For scripted/automated operations not via MCP |
| **`tea` CLI** | None | No wiki subcommands available in tea |

**Use `gitea-mcp` first.** The `tea` CLI does not have wiki commands; the REST API is the fallback.

## Authentication

```bash
# MCP: token is sent automatically via Bearer ${GITEA_TOKEN}
# Set env var before invoking MCP:
export GITEA_TOKEN=<your-token>

# REST API fallback: via curl
curl -H "Authorization: Bearer $GITEA_TOKEN" \
     -H "Content-Type: application/json" \
     https://gitea.example.com/api/v1/repos/owner/repo/wiki/...

# tea login env (for tea CLI fallback)
eval $(tea login env --login <login-name>)
```

## Wiki API Endpoints

### List All Pages

```bash
GET /repos/{owner}/{repo}/wiki/pages
```

```bash
curl -s "$GITEA_SERVER_URL/api/v1/repos/$OWNER/$REPO/wiki/pages" \
  -H "Authorization: Bearer $GITEA_TOKEN"
```

Response:
```json
[
  {
    "title": "Home",
    "slug": "Home",
    "content_url": "https://gitea.example.com/repos/owner/repo/wiki/Home.md"
  },
  {
    "title": "Installation Guide",
    "slug": "Installation-Guide",
    "content_url": "https://gitea.example.com/repos/owner/repo/wiki/Installation-Guide.md"
  }
]
```

### Get a Wiki Page

```bash
GET /repos/{owner}/{repo}/wiki/{page}
```

`{page}` is the slug (URL-safe title, spaces replaced with dashes).

```bash
curl -s "$GITEA_SERVER_URL/api/v1/repos/$OWNER/$REPO/wiki/Home" \
  -H "Authorization: Bearer $GITEA_TOKEN"
```

Response: The raw Markdown content of the page.

### Get Page with HTML Rendered

Add `?format=html` for rendered HTML:

```bash
curl -s "$GITEA_SERVER_URL/api/v1/repos/$OWNER/$REPO/wiki/Home?format=html" \
  -H "Authorization: Bearer $GITEA_TOKEN"
```

### Get Page Revisions

```bash
GET /repos/{owner}/{repo}/wiki/{page}/revisions
```

Returns commit history for a wiki page (who changed it and when).

## Write Operations

### Create a Wiki Page

```bash
POST /repos/{owner}/{repo}/wiki
```

Body (JSON):
```json
{
  "title": "Page Title",
  "content": "# Page Title\n\nMarkdown content here..."
}
```

Title becomes the page slug (filename) and the Markdown is stored as-is.

```bash
curl -s -X POST "$GITEA_SERVER_URL/api/v1/repos/$OWNER/$REPO/wiki" \
  -H "Authorization: Bearer $GITEA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"Installation Guide","content":"# Installation\n\nStep 1..."}'
```

### Edit/Update a Wiki Page

```bash
PATCH /repos/{owner}/{repo}/wiki/{page}
```

Body (JSON) — same format as create:

```json
{
  "content": "# Updated content\n\nNew Markdown..."
}
```

```bash
curl -s -X PATCH "$GITEA_SERVER_URL/api/v1/repos/$OWNER/$REPO/wiki/Installation-Guide" \
  -H "Authorization: Bearer $GITEA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"content":"# Updated Installation\n\nStep 1...Step 2..."}'
```

### Delete a Wiki Page

```bash
DELETE /repos/{owner}/{repo}/wiki/{page}
```

```bash
curl -s -X DELETE "$GITEA_SERVER_URL/api/v1/repos/$OWNER/$REPO/wiki/Installation-Guide" \
  -H "Authorization: Bearer $GITEA_TOKEN"
```

Requires admin or owner access.

## Common Tasks

### Render Wiki Page Content for Display

```bash
# Get raw markdown
curl -s "$GITEA_SERVER_URL/api/v1/repos/$OWNER/$REPO/wiki/Page-Name" \
  -H "Authorization: Bearer $GITEA_TOKEN"

# Or get HTML-rendered version
curl -s "$GITEA_SERVER_URL/api/v1/repos/$OWNER/$REPO/wiki/Page-Name?format=html" \
  -H "Authorization: Bearer $GITEA_TOKEN"
```

### List All Pages Non-Interactively

```bash
curl -s "$GITEA_SERVER_URL/api/v1/repos/$OWNER/$REPO/wiki/pages" \
  -H "Authorization: Bearer $GITEA_TOKEN" | \
  jq '.[] | "\(.title) (\(.slug))"'
```

### Create or Update (Upsert Pattern)

There is no dedicated upsert endpoint. Use GET first to check existence, then POST or PATCH:

```bash
# Check if page exists
if curl -s -o /dev/null -w "%{http_code}" \
  "$GITEA_SERVER_URL/api/v1/repos/$OWNER/$REPO/wiki/Page-Name" \
  -H "Authorization: Bearer $GITEA_TOKEN" -eq 200; then
  # Update existing
  curl -s -X PATCH ...
else
  # Create new
  curl -s -X POST ...
fi
```

### Open Wiki in Browser

```bash
tea open wiki
```

Works from within a git repository registered with the Gitea instance.

## Wiki Structure Notes

- Wiki pages are Markdown (`.md`) files
- Stored in `.wiki` branch of the repository
- Slugs are generated from titles (spaces → dashes, special chars removed)
- Each page maintains its own revision history
- Wiki can be cloned locally: `git clone https://gitea.example.com/owner/repo.wiki.git`

## Guidelines

### Do
- Use `tea open wiki` to quickly preview wiki in browser when doing exploration
- Use the `?format=html` query param when you need to display rendered content
- Check page existence before creating to decide between POST and PATCH

### Don't
- Assume `tea` has wiki subcommands — it doesn't. Use API directly for write operations.
- Use GitHub wiki API conventions — Gitea's wiki API is different.

## References

- [Gitea MCP Server](https://gitea.com/gitea/gitea-mcp) — official MCP with ~100 tools
- [Gitea Wiki API](https://docs.gitea.com/api/1.26/repo/wiki)