---
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.1.0
---

# Gitea Wiki Management

## Overview

Gitea wikis are git-backed Markdown pages attached to a repository. The MCP server exposes them through two consolidated tools (`wiki_read`, `wiki_write`); the REST API at `/api/v1/repos/{owner}/{repo}/wiki/...` is the fallback. `tea` has no wiki subcommands.

## Interaction Methods

| Priority | Method | Notes |
|----------|--------|-------|
| **Primary** | MCP `mcp__gitea__wiki_read` / `mcp__gitea__wiki_write` | Configured in repo `.mcp.json`; auth via `GITEA_TOKEN` |
| Fallback | REST API via `curl` | For automation outside an MCP-aware client |
| — | `tea` CLI | Not supported — `tea` has no wiki commands |

## MCP tools

Both tools take `owner`, `repo`, and a `method` discriminator.

### `wiki_read` — methods

| `method` | Other args | Returns |
|----------|-----------|---------|
| `list` | — | All page titles + slugs + content URLs |
| `get` | `pageName` | Page metadata + raw markdown |
| `get_revisions` | `pageName` | Commit history for that page |

### `wiki_write` — methods

| `method` | Required args | Notes |
|----------|--------------|-------|
| `create` | `title`, `content` | Title becomes the slug (spaces → dashes). Optional `message` for commit msg. |
| `update` | `pageName`, `content` | `pageName` is the slug. `title` and `message` are optional. |
| `delete` | `pageName` | Requires write access to the wiki. |

### Examples

List pages in `farh/example`:
```
mcp__gitea__wiki_read(method="list", owner="farh", repo="example")
```

Read the `Home` page:
```
mcp__gitea__wiki_read(method="get", owner="farh", repo="example", pageName="Home")
```

Create `Installation-Guide`:
```
mcp__gitea__wiki_write(
  method="create",
  owner="farh", repo="example",
  title="Installation Guide",
  content="# Installation\n\nStep 1...",
  message="docs(wiki): add installation guide"
)
```

Update existing page:
```
mcp__gitea__wiki_write(
  method="update",
  owner="farh", repo="example",
  pageName="Installation-Guide",
  content="# Installation\n\nUpdated...",
  message="docs(wiki): update installation"
)
```

Delete page:
```
mcp__gitea__wiki_write(method="delete", owner="farh", repo="example", pageName="Old-Page")
```

## REST API fallback

The MCP server wraps these endpoints. Use `curl` directly only when MCP isn't reachable.

| Endpoint | Method | Purpose |
|----------|--------|---------|
| `/repos/{owner}/{repo}/wiki/pages` | GET | List all pages |
| `/repos/{owner}/{repo}/wiki/page/{slug}` | GET | Get a page (raw markdown by default; add `?format=html` for rendered HTML) |
| `/repos/{owner}/{repo}/wiki/revisions/{slug}` | GET | Page commit history |
| `/repos/{owner}/{repo}/wiki/new` | POST | Create a page |
| `/repos/{owner}/{repo}/wiki/page/{slug}` | PATCH | Update a page |
| `/repos/{owner}/{repo}/wiki/page/{slug}` | DELETE | Delete a page |

> Slug rules: take the title, replace spaces with `-`, drop characters that aren't `[A-Za-z0-9_./-]`. Gitea returns the canonical slug as `sub_url` in the page metadata — when in doubt, list first and read the slug back.

### Auth

```bash
export GITEA_TOKEN=<your-token>
# Repo MCP config uses: Authorization: Bearer ${GITEA_TOKEN}
```

### Listing pages

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

### Creating a page

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

`content_base64` is also accepted in place of `content` for binary-safe payloads.

### Updating a page

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

### Deleting a page

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

### Rendered HTML

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

### Upsert pattern (no dedicated endpoint)

```bash
status=$(curl -s -o /dev/null -w "%{http_code}" \
  "$GITEA_SERVER_URL/api/v1/repos/$OWNER/$REPO/wiki/page/$SLUG" \
  -H "Authorization: Bearer $GITEA_TOKEN")

if [ "$status" = "200" ]; then
  curl -s -X PATCH "$GITEA_SERVER_URL/api/v1/repos/$OWNER/$REPO/wiki/page/$SLUG" \
    -H "Authorization: Bearer $GITEA_TOKEN" -H "Content-Type: application/json" \
    -d "{\"content\":$(jq -Rs . <body.md)}"
else
  curl -s -X POST "$GITEA_SERVER_URL/api/v1/repos/$OWNER/$REPO/wiki/new" \
    -H "Authorization: Bearer $GITEA_TOKEN" -H "Content-Type: application/json" \
    -d "{\"title\":\"$TITLE\",\"content\":$(jq -Rs . <body.md)}"
fi
```

## Wiki structure notes

- Pages are Markdown files in a dedicated `.wiki` git branch.
- Slug = sanitized title; revision history is per page.
- The whole wiki can be cloned: `git clone $GITEA_SERVER_URL/$OWNER/$REPO.wiki.git`.

## Guidelines

### Do
- Prefer `wiki_read` / `wiki_write` MCP calls — they hide the slug/encoding rules.
- When unsure of a slug, `wiki_read` with `method="list"` and pick the canonical slug from the response.
- Add a `message` on writes — wiki commits are visible in the page revision log.

### Don't
- Assume the slug equals the title. Spaces become `-`; punctuation gets stripped.
- Use the REST API when MCP is available — MCP handles auth and slug encoding.
- Apply GitHub Wiki API conventions; Gitea's endpoints differ in path shape (`wiki/page/{slug}`, `wiki/new`).

## References

- [Gitea MCP server](https://gitea.com/gitea/gitea-mcp)
- [Gitea Wiki API](https://docs.gitea.com/api/next/#tag/repository/operation/repoGetWikiPages)