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:

![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:

| 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:

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

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

```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:

[Item Name](https://db.ascension.gg/?item=ITEMID)
[Spell Name](https://db.ascension.gg/?spell=SPELLID)

Example:

[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:

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

# 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)