MinecraftUpdates/WIKI_CONFIG.md

# Wiki Configuration Guide

The Minecraft Update Bot uses a subreddit wiki page to manage customizable post templates. This allows different post formats for different release types without restarting the bot.

## Quick Setup

1. Go to your subreddit settings and edit wiki pages
2. Create a new page named "minecraft_update_bot"
3. Add YAML configuration for your post templates
4. Bot loads the configuration automatically

The wiki page name can be customized via the REDDIT_WIKI_PAGE_NAME environment variable.

## Configuration Format

The wiki page must contain valid YAML with this structure:

```yaml
release_type:
  title: "Post title with placeholders"
  body: |
    Post body content
    with {placeholders}
```

## Available Placeholders

Both title and body can use these placeholders:
- {version} - The release version number (e.g., "1.21", "26.3")
- {release_date} - Formatted release date (e.g., "June 13, 2024")
- {type} - The release type (e.g., "release", "snapshot")

## Release Types

Create configuration sections for these release types:

Java Edition:
- release - Final Java Edition releases
- snapshot - Development snapshots
- old_beta - Legacy beta versions
- old_alpha - Legacy alpha versions

Bedrock Edition:
- bedrock-windows - Bedrock Edition 

Special:
- default - Fallback for unconfigured types

## Example Configurations

### Basic Setup (Releases Only)

```yaml
release:
  title: "Minecraft {version} is Available"
  body: |
    A new version of Minecraft Java Edition is available!
    
    Version: {version}
    Released: {release_date}
    
    Download from minecraft.net or use the Minecraft launcher.
```

### Multiple Release Types

```yaml
release:
  title: "Minecraft {version} Released"
  body: |
    # Minecraft {version}
    
    A new release is available!
    
    Version: {version}
    Released: {release_date}
    
    Download: https://minecraft.net

snapshot:
  title: "Minecraft {version} Snapshot"
  body: |
    # Minecraft {version} Snapshot
    
    A new development snapshot is available for testing.
    
    Version: {version}
    Released: {release_date}
    
    Enable snapshots in your launcher preferences.

bedrock-windows:
  title: "Bedrock Edition {version} Available"
  body: |
    # Minecraft Bedrock Edition {version}
    
    A new Bedrock Edition update is available for Windows.
    
    Version: {version}
    Released: {release_date}
    
    Download from the Microsoft Store or through the Minecraft Launcher.

old_beta:
  title: "Minecraft Beta {version} Archive"
  body: |
    Version {version} is now archived.
    Released: {release_date}

old_alpha:
  title: "Minecraft Alpha {version} Archive"
  body: |
    Version {version} is now archived.
    Released: {release_date}

default:
  title: "Minecraft {version} ({type})"
  body: |
    New {type} build: {version}
    Released: {release_date}
```

### Minimal Setup with Defaults

```yaml
default:
  title: "Minecraft {version}"
  body: |
    # New {type} Available
    
    Version: {version}
    Released: {release_date}
```

## Loading and Caching

The wiki configuration:
- Loads on bot startup
- Refreshes automatically during version checks
- Is cached for 5 minutes to avoid excessive wiki requests
- Falls back to embedded defaults if the wiki page is missing or invalid

Warning messages in logs:
- "Error fetching YAML config from wiki" - Cannot read the page
- "Wiki config missing required 'triggers' key" - Invalid YAML format
- An error YAML parse message - Syntax error in configuration

## Formatting Guidelines

YAML syntax rules:
- Use correct indentation (2 spaces recommended)
- Start multi-line strings with | or |-
- Values in double quotes: "string with special characters"
- No tab characters (spaces only)

Text formatting in posts:
- Standard Reddit Markdown supported
- Headers: # Title (single hash for main title)
- Bold: **text**
- Italic: *text*
- Links: [text](url)
- Line breaks: Use actual newlines in the YAML body

## Fallback Behavior

If a release type is not configured:
1. Bot looks for a "default" section
2. If no default exists, uses embedded defaults
3. Embedded default format:
   ```
   Title: Minecraft {version} ({type})
   Body: New {type}: {version}. Released: {release_date}
   ```

## YAML Validation

Test your YAML before adding to wiki:
- Use an online YAML validator at https://www.yamllint.com/
- Check for correct indentation and quotes
- Verify all colons have spaces after them

Common mistakes:
- Indentation with tabs (must be spaces)
- Missing quotes around values with special characters
- Unbalanced quotes
- Trailing colons without values

## Testing Configuration

After updating the wiki page:

1. Send a "reload-config" chat message to the bot (moderators only)
2. Check bot logs for these messages:
   - "[WIKI_CONFIG] Successfully fetched wiki page"
   - "[WIKI_CONFIG] Loaded X configuration(s)"
3. Look for error messages with parsing details

Command for moderators:
```
Send a Reddit chat message to the bot containing: reload-config
```

The bot will reply with success or failure status.

## Troubleshooting

Wiki configuration not loading:
1. Check page name is exactly "minecraft_update_bot" (or your custom name)
2. Verify the bot can read the wiki (check subreddit permissions)
3. Use YAML validator to find syntax errors
4. Check bot logs for error messages

Posts not formatting correctly:
- Verify placeholder names: {version}, {release_date}, {type}
- Check YAML indentation is consistent
- Use | for multi-line bodies (not single quotes)
- Test problematic sections in a YAML validator

Configuration not updating after wiki change:
- Wait up to 5 minutes (cache timeout)
- Or send "reload-config" chat command (moderators)
- Check bot logs to confirm reload was successful

Fallback config triggering:
- Check for YAML parse errors in logs
- Verify the wiki page is readable
- Ensure "release" configuration exists or "default" is defined

## Examples with Real-World Scenarios

### Example 1: Simple Release Announcements

For a subreddit that only posts final releases:

```yaml
release:
  title: "Minecraft {version} - Out Now!"
  body: |
    The official release of Minecraft {version} is now available!
    
    Released: {release_date}
```

### Example 2: Community-Focused Posts

```yaml
release:
  title: "What's New in Minecraft {version}?"
  body: |
    # Minecraft {version} Released
    
    We have a new version!
    
    **Version:** {version}
    **Release Date:** {release_date}
    
    What are you most excited to try?

snapshot:
  title: "Snapshot: Try the Latest Features"
  body: |
    # {version} Snapshot Available
    
    Want to test upcoming features? This is your chance!
    
    Released: {release_date}
    
    Remember: Snapshots can be unstable. Use separate worlds for testing!
```

### Example 3: Structured with Emojis (if preferred)

```yaml
release:
  title: "[RELEASE] Minecraft {version}"
  body: |
    Minecraft {version} is now available!
    Released: {release_date}

snapshot:
  title: "[SNAPSHOT] Minecraft {version}"
  body: |
    New snapshot available!
    Released: {release_date}
```

## Wiki Markup

Reddit wiki pages support:
- Standard Markdown
- Escape special characters with backslash: \{text\}
- HTML not processed in wiki pages
- Some Reddit-specific formatting may have limitations

3. This confirms your configs were loaded successfully

4. When a new version is posted, you'll see:
   ```
   [BOT] ✓ Posted Minecraft X.X (release_type)
   ```

## Wiki Permissions

Make sure the bot account:
- Has **write** permission to edit the subreddit
- Can access the wiki pages
- Has the right to post to the subreddit

If you get permission errors, add the bot account as a moderator with wiki permissions.