ascension-char-exporter/.ai/wiki-formatting-guide.md

# Wiki.js Formatting Guide for AI/LLM

This document provides formatting guidelines for creating and editing Wiki.js articles in this repository.

## Project Overview

This is the ExilesWiki project for an Ascension WoW private server. Articles are written in Markdown format with Wiki.js-specific features enabled.

## Markdown Features

### Standard Markdown
- Headers: `#`, `##`, `###`, etc.
- **Bold**: `**text**`
- *Italic*: `*text*`
- Lists: `-` or `1.`
- Links: `[text](url)`
- Code blocks: triple backticks

### Wiki.js Specific

#### Icons
Icons are stored in `/icons/` directory and referenced as:
```markdown
![Icon Alt Text](/icons/path/to/icon.png)
```

Examples:
- Class icons: `![Paladin](/icons/classes/classicon_paladin.png)`
- Item icons: `![Item Name](/icons/items/itemicon_name.png)`

#### Tables
MultiMarkdown Table format is enabled:
```markdown
| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Data     | Data     | Data     |
```

- Use `<br>` for line breaks within cells
- Tables support standard markdown formatting inside cells

#### PlantUML Diagrams
PlantUML code blocks are rendered as diagrams:

````markdown
```plantuml
@startuml
title Diagram Title
' Your PlantUML code here
@enduml
```
````

**C4 PlantUML for Rotations:**
For ability rotations/priority systems, use C4 PlantUML format:

````markdown
```plantuml
@startuml
!define C4 true
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Context.puml

title Ability Priority System

rectangle "Priority System" {
  (1) Ability Name : Description
  (2) Another Ability : Description

  (1) -down-> (2)
}
@enduml
```
````

#### External Links

**Ascension Database Links:**
Link items/spells to the Ascension database:
```markdown
[Item Name](https://db.ascension.gg/?item=ITEMID)
[Spell Name](https://db.ascension.gg/?spell=SPELLID)
```

Example:
```markdown
[Lionheart Helm](https://db.ascension.gg/?item=12640)
[Deranged Druid](https://db.ascension.gg/?spell=84531)
```

## Content Structure

### Class Guides

Typical structure for class guides:

1. **Title & Icon**: Class name with class icon
2. **Introduction**: Brief overview and author credit
3. **Pre-Raid BiS Gear**: Table format with slot/item options
4. **Enchants**: Table with slot/enchant/stats
5. **Talents**: Key talent descriptions
6. **Mystic Enchants**: Organized by rarity (Artifact, Legendary, Epic, Rare)
7. **Macros**: Code blocks with macro examples
8. **Rotation**: PlantUML priority diagram + text breakdown

### Formatting Best Practices

- Use tables for gear lists, enchants, and stat comparisons
- Use code blocks for macros, commands, and configuration
- Include icons for visual appeal (class icons, item icons)
- Link items to db.ascension.gg when possible
- Use PlantUML for visual representations of rotations/priorities
- Break long lists with headers and categories
- Use bold for important terms or item/ability names
- Use italic for quest/flavor text

## File Organization

```
exileswiki/
├── .ai/                           # AI/LLM documentation
│   └── wiki-formatting-guide.md
├── scripts/                       # Utility scripts
│   ├── add_item_links.py         # Auto-link items to db
│   └── item_links_found.json     # Cache of found item IDs
├── icons/                         # Icon assets
│   ├── classes/
│   └── items/
└── *.md                          # Wiki articles
```

## Scripts

### add_item_links.py
Automatically searches db.ascension.gg for items in guides and adds proper links.

Usage:
```bash
python3 scripts/add_item_links.py
```

The script:
1. Extracts item names from markdown files
2. Searches db.ascension.gg for each item
3. Saves results to `item_links_found.json`
4. Reports items that need manual lookup

## Tips for AI/LLM

When creating or editing wiki articles:

1. **Always check existing articles** for formatting consistency
2. **Use the icon path format** `/icons/category/name.png` (absolute path from root)
3. **MultiMarkdown tables** support `<br>` for multi-line cells
4. **PlantUML C4 diagrams** work well for ability priority systems
5. **Item links** should use format `[Name](https://db.ascension.gg/?item=ID)`
6. **Code blocks** for macros should specify language (e.g., ````lua` or just ``` for plain)
7. **Test PlantUML** syntax before committing (validate it renders)
8. **Keep tables readable** in source - align columns when possible

## Example Article Structure

```markdown
# Class Name Guide

![Class Icon](/icons/classes/classicon_name.png)

*By Author*

Brief introduction...

## Section Header

Content with [linked items](https://db.ascension.gg/?item=12640)...

| Header 1 | Header 2 |
|----------|----------|
| Data     | Data     |

```plantuml
@startuml
title Diagram
@enduml
```

## Another Section

More content...
```

## Resources

- [Wiki.js Documentation](https://docs.requarks.io/)
- [PlantUML Documentation](https://plantuml.com/)
- [Ascension Database](https://db.ascension.gg/)
- [MultiMarkdown Table Syntax](https://fletcher.github.io/MultiMarkdown-6/syntax/tables.html)