# Gitea Wiki Formatting Reference

## Wiki API Integration

The Product Owner Assistant skill integrates with Gitea's wiki functionality to create and manage documentation for epics and user stories.

## Gitea Wiki API Endpoints

### Create Wiki Page

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

**Request Body:**
```json
{
  "title": "Page Title",
  "content_base64": "base64_encoded_content",
  "message": "Optional commit message"
}
```

**Example:**
```bash
# Create a wiki page using the API
curl -X POST "https://gitea.arcodange.lab/api/v1/repos/arcodange/dance-lessons-coach/wiki/new" \
  -H "Authorization: token YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Authentication Epic",
    "content_base64": "$(echo '# Authentication System' | base64)",
    "message": "Initial epic documentation"
  }'
```

### Get Wiki Page

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

**Example:**
```bash
# Get a wiki page
curl -X GET "https://gitea.arcodange.lab/api/v1/repos/arcodange/dance-lessons-coach/wiki/page/AuthenticationEpic" \
  -H "Authorization: token YOUR_TOKEN"
```

### List All Wiki Pages

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

**Example:**
```bash
# List all wiki pages
curl -X GET "https://gitea.arcodange.lab/api/v1/repos/arcodange/dance-lessons-coach/wiki/pages" \
  -H "Authorization: token YOUR_TOKEN"
```

### Edit Wiki Page

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

**Request Body:** Same as create

### Delete Wiki Page

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

## Wiki Page Structure

The Product Owner Assistant creates wiki pages with the following structure:

```markdown
# [Epic Title]

**Status**: [Open/In Progress/Completed]  
**Created**: [YYYY-MM-DD]  
**Last Updated**: [YYYY-MM-DD]  
**Epic ID**: #[issue_number]

## Description
[Epic description from the issue]

## User Stories

| ID | Title | Status | Assignee |
|----|-------|--------|----------|
| #43 | [Story Title](#43) | Open | @developer |
| #44 | [Story Title](#44) | In Progress | @developer |
| #45 | [Story Title](#45) | Completed | @developer |

## Progress Summary

- **Total Stories**: 3
- **Completed**: 1 (33%)
- **In Progress**: 1 (33%)
- **Open**: 1 (33%)

![Progress Bar](https://progress-bar.dev/33)

## Progress Details

### Completed Stories (1/3)
- ✅ [#45 - Story Title](link): Completed on [date]

### In Progress Stories (1/3)
- 🚧 [#44 - Story Title](link): Started on [date]

### Open Stories (1/3)
- ⏳ [#43 - Story Title](link): Created on [date]

## Related Issues

- [Issue #46](link): [Title] - [Status]
- [Issue #47](link): [Title] - [Status]

## Dependencies

- [Dependency #1](link): [Description]
- [Dependency #2](link): [Description]

## Risks and Blockers

- **Risk**: [Description] - Mitigation: [Strategy]
- **Blocker**: [Description] - Resolution: [Plan]

## Stakeholders

- **Product Owner**: @product-owner
- **Development Team**: @team-member1, @team-member2
- **Business Sponsor**: @sponsor

## Timeline

- **Start Date**: [YYYY-MM-DD]
- **Target Completion**: [YYYY-MM-DD]
- **Actual Completion**: [YYYY-MM-DD or "In Progress"]

## Success Criteria

- [ ] Criteria 1: [Description]
- [ ] Criteria 2: [Description]
- [ ] Criteria 3: [Description]

## Metrics

- **Business Impact**: [Description]
- **User Adoption**: [Target %]
- **Performance**: [Target metrics]

## Change Log

### [YYYY-MM-DD]
- [Change description]

### [YYYY-MM-DD]
- [Change description]
```

## Markdown Formatting Guide

### Headers

```markdown
# Heading 1
## Heading 2
### Heading 3
#### Heading 4
```

### Text Formatting

```markdown
**Bold text**
*Italic text*
`code`

> Blockquote
```

### Lists

```markdown
- Unordered list item
- Another item
  - Subitem

1. Ordered list item
2. Another item
```

### Links

```markdown
[Link text](https://example.com)
[Issue #42](https://gitea.arcodange.lab/arcodange/dance-lessons-coach/issues/42)
```

### Images

```markdown
![Alt text](https://example.com/image.png)
```

### Tables

```markdown
| Header 1 | Header 2 |
|----------|----------|
| Cell 1   | Cell 2   |
| Cell 3   | Cell 4   |
```

### Code Blocks

````markdown
```go
func main() {
    fmt.Println("Hello World")
}
```
````

## Integration with Product Owner Assistant

The skill automatically generates wiki pages using these templates:

### Creating Epic Wiki Page

```bash
# Create wiki page for an epic
skill product-owner-assistant create-wiki-epic arcodange dance-lessons-coach 42
```

This command:
1. Gets epic details from issue #42
2. Finds all linked user stories
3. Checks status of each story
4. Generates progress metrics
5. Creates a comprehensive wiki page
6. Returns the wiki page URL

### Wiki Page Naming Convention

The skill uses the following naming convention:

```
Epic_[EpicID]_[SanitizedTitle]
```

Examples:
- `Epic_42_Authentication_System`
- `Epic_43_Payment_Processing`
- `Epic_44_User_Profile_Enhancements`

### Content Generation

The wiki content is generated from:

1. **Epic Issue**: Title, description, labels, state
2. **Linked Stories**: IDs, titles, status, assignees
3. **Progress Data**: Completion percentages, counts
4. **Metadata**: Creation dates, update timestamps

## Advanced Wiki Features

### Cross-Referencing

```markdown
# Related Epics

- [[Epic_42_Authentication_System]]
- [[Epic_43_Payment_Processing]]
```

### Embedding Content

```markdown
![[Epic_42_Authentication_System#Progress_Summary]]
```

### Tags and Categories

```markdown
**Tags**: authentication, security, backend
**Category**: Technical Epics
```

## Best Practices for Wiki Documentation

### 1. Keep Updated
- Update wiki pages after each sprint
- Reflect current status and progress
- Document changes in the change log

### 2. Be Comprehensive
- Include all relevant information
- Link to related issues and epics
- Document decisions and rationale

### 3. Use Consistent Formatting
- Follow the standard template
- Use consistent heading structure
- Maintain uniform styling

### 4. Make It Actionable
- Include clear next steps
- Highlight blockers and risks
- Specify owners and responsibilities

### 5. Visualize Progress
- Use progress bars and charts
- Include status indicators
- Show completion percentages

## Examples

### Basic Epic Wiki Page

```markdown
# User Authentication System

**Status**: In Progress  
**Created**: 2024-04-06  
**Last Updated**: 2024-04-06  
**Epic ID**: #42

## Description
Implement comprehensive authentication system with OAuth 2.0, JWT, and session management to improve security and user experience.

## User Stories

| ID | Title | Status | Assignee |
|----|-------|--------|----------|
| #43 | OAuth 2.0 Integration | In Progress | @developer1 |
| #44 | JWT Token Management | Open | @developer2 |
| #45 | Session Management | Completed | @developer1 |

## Progress Summary

- **Total Stories**: 3
- **Completed**: 1 (33%)
- **In Progress**: 1 (33%)
- **Open**: 1 (33%)

![Progress](https://progress-bar.dev/33)
```

### Complete Epic with Dependencies

```markdown
# Payment Processing System

**Status**: Open  
**Created**: 2024-04-06  
**Last Updated**: 2024-04-06  
**Epic ID**: #43

## Description
Implement Stripe and PayPal integration for subscription payments with fraud detection and refund processing.

## Dependencies

- **Epic #42**: User Authentication System (Required for secure payment processing)
- **Service**: Stripe API Integration (External dependency)
- **Service**: PayPal API Integration (External dependency)
- **Team**: Frontend Team (UI integration)

## Risks and Blockers

- **Risk**: Payment provider API changes - Mitigation: Implement adapter pattern
- **Blocker**: Pending legal review of terms and conditions
- **Risk**: PCI compliance requirements - Mitigation: Use tokenization

## Success Criteria

- [ ] Achieve 99.9% payment success rate
- [ ] Process payments in <2 seconds
- [ ] Support 5+ payment methods
- [ ] Pass PCI compliance audit
```

## API Reference

For complete API documentation, see:
- [Gitea API Documentation](https://gitea.com/api/swagger)
- [Wiki API Reference](https://gitea.com/api/swagger#/repository)

This reference guide provides comprehensive information for using Gitea's wiki functionality with the Product Owner Assistant skill.