GH-194 Add comprehensive Multification documentation

content/docs/multification/advanced.mdx

@@ -0,0 +1,112 @@
+---
+title: Advanced Features
+description: i18n, custom formatters, and platform adapters
+icon: Sparkles
+sidebar_position: 6
+---
+
+## Internationalization (i18n)
+
+```java
+public class MyMultification extends PaperMultification<BaseMessages> {
+    private final Map<Locale, BaseMessages> translations;
+
+    @Override
+    protected TranslationProvider<BaseMessages> translationProvider() {
+        return locale -> translations.getOrDefault(locale, translations.get(Locale.ENGLISH));
+    }
+
+    @Override
+    protected LocaleProvider<CommandSender> localeProvider() {
+        return viewer -> viewer instanceof Player p ? p.locale() : Locale.ENGLISH;
+    }
+}
+
+// Load translations
+Map<Locale, BaseMessages> translations = new HashMap<>();
+translations.put(Locale.ENGLISH, loadConfig("messages_en.yml"));
+translations.put(new Locale("pl"), loadConfig("messages_pl.yml"));
+```
+
+<Callout type="tip">
+  Messages are automatically sent in player's language based on their client locale.
+</Callout>
+
+## Global Replacer
+
+Apply transformations to all messages:
+
+```java
+@Override
+protected Replacer<CommandSender> globalReplacer() {
+    return (viewer, text) -> {
+        text = text.replace("{server}", "MyServer");
+
+        // PlaceholderAPI integration
+        if (viewer instanceof Player player) {
+            text = PlaceholderAPI.setPlaceholders(player, text);
+        }
+
+        return text;
+    };
+}
+```
+
+## Custom Notice Types
+
+<Steps>
+  <Step title="Define Content" icon="FileCode">
+    ```java
+    public class HologramContent implements NoticeContent {
+        private final String text;
+        private final Location location;
+        // ...
+    }
+    ```
+  </Step>
+  <Step title="Create Resolver" icon="Puzzle">
+    ```java
+    public class HologramResolver implements NoticeResolver<HologramContent> {
+        private static final NoticeKey<HologramContent> KEY =
+            new NoticeKeyImpl<>("hologram", HologramContent.class);
+
+        @Override
+        public void send(Audience audience, ComponentSerializer<?, ?, String> serializer, HologramContent content) {
+            // Create hologram
+        }
+
+        @Override
+        public NoticeSerdesResult serialize(HologramContent content) { ... }
+
+        @Override
+        public Optional<HologramContent> deserialize(NoticeSerdesResult result) { ... }
+    }
+    ```
+  </Step>
+  <Step title="Register" icon="Plus">
+    ```java
+    this.noticeRegistry.registerResolver(new HologramResolver());
+    ```
+  </Step>
+</Steps>
+
+## Performance Tips
+
+```java
+// ✅ Batch sending
+multification.create()
+    .players(playerList)
+    .notice(config -> config.message)
+    .send();
+
+// ❌ Individual sends
+for (UUID uuid : players) {
+    multification.create().player(uuid).notice(...).send();
+}
+
+// ✅ Async for heavy operations
+multification.create()
+    .all()
+    .notice(config -> config.heavyMessage)
+    .sendAsync();
+```

content/docs/multification/api-reference.mdx

@@ -0,0 +1,108 @@
+---
+title: API Reference
+description: Complete API documentation
+icon: Book
+sidebar_position: 7
+---
+
+## Core Classes
+
+### Multification
+
+```java
+public abstract class Multification<VIEWER, TRANSLATION>
+```
+
+**Abstract methods (must override):**
+- `viewerProvider()` – provides players/console
+- `translationProvider()` – provides config for locale
+- `audienceConverter()` – converts viewer to Adventure Audience
+
+**Optional overrides:**
+- `serializer()` – default: `PlainComponentSerializer` (use MiniMessage)
+- `globalReplacer()` – default: no-op
+- `asyncExecutor()` – default: sync execution
+- `localeProvider()` – default: `Locale.ROOT`
+
+### Notice
+
+```java
+// Static factories
+Notice.chat(String... messages)
+Notice.title(String title, String subtitle)
+Notice.actionbar(String message)
+Notice.sound(String key, float volume, float pitch)
+Notice.bossBar(BossBar.Color color, Duration duration, String message)
+Notice.empty()
+
+// Builder
+Notice.builder()
+    .chat("...")
+    .title("...", "...")
+    .actionBar("...")
+    .sound("...")
+    .bossBar(...)
+    .build()
+```
+
+### NoticeBroadcast
+
+```java
+multification.create()
+    // Target
+    .player(UUID)
+    .players(Iterable<UUID>)
+    .viewer(VIEWER)
+    .console()
+    .all()
+    .onlinePlayers()
+    .onlinePlayers(String permission)
+
+    // Notice
+    .notice(Notice)
+    .notice(config -> config.message)
+
+    // Placeholders
+    .placeholder("{key}", "value")
+
+    // Formatters
+    .formatter(Formatter...)
+
+    // Send
+    .send()
+    .sendAsync()
+```
+
+## Functional Interfaces
+
+```java
+// Extract notice from config
+NoticeProvider<T> = translation -> Notice
+
+// Format text
+Formatter = (viewer, text) -> String
+
+// Replace text globally
+Replacer<V> = (viewer, text) -> String
+
+// Get locale for viewer
+LocaleProvider<V> = viewer -> Locale
+
+// Convert viewer to Audience
+AudienceConverter<V> = viewer -> Audience
+
+// Get config for locale
+TranslationProvider<T> = locale -> T
+```
+
+## Serializers
+
+```java
+// CDN
+new MultificationNoticeCdnComposer(multification)
+new MultificationNoticeCdnComposer(noticeRegistry)
+
+// Okaeri
+new MultificationSerdesPack(multification)
+new MultificationSerdesPack(noticeRegistry)
+```

content/docs/multification/basic-usage.mdx

@@ -0,0 +1,170 @@
+---
+title: Basic Usage
+description: Learn the fundamentals of sending messages with Multification
+icon: BookOpen
+sidebar_position: 3
+---
+
+## Creating Multification
+
+<CodeTabs>
+  <CodeTab label="Paper">
+    ```java
+    public class MyMultification extends PaperMultification<MessagesConfig> {
+        private final MessagesConfig config;
+
+        public MyMultification(MessagesConfig config) {
+            this.config = config;
+        }
+
+        @Override
+        protected TranslationProvider<MessagesConfig> translationProvider() {
+            return locale -> this.config;
+        }
+
+        @Override
+        protected ComponentSerializer<Component, Component, String> serializer() {
+            return MiniMessage.miniMessage();
+        }
+
+        @Override
+        protected AudienceConverter<CommandSender> audienceConverter() {
+            return commandSender -> commandSender; // CommandSender IS Audience
+        }
+    }
+    ```
+  </CodeTab>
+  <CodeTab label="Bukkit">
+    ```java
+    public class MyMultification extends BukkitMultification<MessagesConfig> {
+        private final MessagesConfig config;
+        private final AudienceProvider audienceProvider;
+
+        public MyMultification(Plugin plugin, MessagesConfig config) {
+            this.config = config;
+            this.audienceProvider = BukkitAudiences.create(plugin);
+        }
+
+        @Override
+        protected TranslationProvider<MessagesConfig> translationProvider() {
+            return locale -> this.config;
+        }
+
+        @Override
+        protected ComponentSerializer<Component, Component, String> serializer() {
+            return MiniMessage.miniMessage();
+        }
+
+        @Override
+        protected AudienceConverter<CommandSender> audienceConverter() {
+            return sender -> sender instanceof Player p
+                ? audienceProvider.player(p.getUniqueId())
+                : audienceProvider.console();
+        }
+    }
+    ```
+  </CodeTab>
+</CodeTabs>
+
+## Creating Notices
+
+<Callout type="tip">
+  This section shows the **Java API**. If you're configuring messages in YAML, jump to the [Configuration guide](/docs/multification/configuration) or the
+  [Format guide (for users)](/docs/multification/format).
+</Callout>
+
+```java
+// Simple chat
+Notice chat = Notice.chat("<green>Hello!");
+
+// Multiple lines
+Notice lines = Notice.chat("<gold>Line 1", "<yellow>Line 2");
+
+// Title
+Notice title = Notice.title("<rainbow>Welcome!", "<gray>Subtitle");
+
+// ActionBar
+Notice actionbar = Notice.actionbar("<red>⚠ Warning!");
+
+// Combined (builder)
+Notice complex = Notice.builder()
+    .chat("<green>You received a reward!")
+    .title("<gold>Reward", "<yellow>Check inventory")
+    .actionBar("<green>+$1000")
+    .sound("minecraft:entity.player.levelup")
+    .bossBar(BossBar.Color.GREEN, Duration.ofSeconds(5), "<green>Reward claimed!")
+    .build();
+```
+
+## Sending Messages
+
+```java
+// Single player
+multification.create()
+    .player(playerUUID)
+    .notice(config -> config.welcomeMessage)
+    .placeholder("{player}", player.getName())
+    .send();
+
+// All online players
+multification.create()
+    .all()
+    .notice(config -> config.broadcast)
+    .send();
+
+// Players with permission
+multification.create()
+    .onlinePlayers("admin.notify")
+    .notice(config -> config.adminAlert)
+    .send();
+
+// Console
+multification.create()
+    .console()
+    .notice(config -> config.logMessage)
+    .send();
+
+// CommandSender (viewer)
+multification.create()
+    .viewer(sender)
+    .notice(config -> config.message)
+    .send();
+
+// Async
+multification.create()
+    .all()
+    .notice(config -> config.heavyMessage)
+    .sendAsync();
+```
+
+## Placeholders & Formatters
+
+```java
+// Placeholders
+multification.create()
+    .player(uuid)
+    .notice(config -> config.message)
+    .placeholder("{player}", player.getName())
+    .placeholder("{balance}", String.valueOf(balance))
+    .send();
+
+// Formatters
+Formatter uppercase = (viewer, text) -> text.toUpperCase();
+multification.create()
+    .player(uuid)
+    .notice(config -> config.message)
+    .formatter(uppercase)
+    .send();
+```
+
+## Config Example
+
+```java
+public class MessagesConfig {
+    public Notice welcomeMessage = Notice.builder()
+        .chat("<green>Welcome, {player}!")
+        .title("<gold>Welcome", "<yellow>Enjoy your stay")
+        .sound("minecraft:entity.player.levelup")
+        .build();
+}
+```