Changelog Bot - Documentation

⚙ How It Works

1

Documentation Updated

A bot's HTML documentation page is modified and pushed to the GitHub Pages repository.

2

Trigger Detected

The bot polls for a trigger.json file every 3 seconds. When found, it reads the commit message and deletes the trigger.

3

Hash Comparison

MD5 hashes of all documentation files are computed and compared against stored hashes to detect which files changed.

4

Notifications Sent

Formatted embed messages with "About" buttons are sent to all configured changelog channels across servers.

✨ Features

📰 Change Detection

Uses MD5 hashing to detect when documentation files change. Compares current file hashes against stored snapshots to identify updates.

📣 Multi-Server Notifications

Sends changelog notifications to multiple Discord servers simultaneously. Each server can configure its own changelog channel.

💬 Commit Messages

Includes the git commit message in notifications so users know what changed. Supports both single and multi-bot update embeds.

🛠 About Buttons

Each notification includes interactive "About" buttons that show bot details including description, tech stack, and documentation link.

🌱 Seed Mode

Run with --seed flag to snapshot all current file hashes without sending notifications. Useful for initial setup.

📊 Multi-Bot Batching

When multiple documentation files change at once, they're batched into a single embed with inline fields and button rows.

💻 Commands & Interactions

The Changelog Bot is fully automated and does not use slash commands. Instead, it operates through CLI commands, file-based triggers, and interactive button components.

⌨ CLI Commands

node index.js CLI

Starts the bot and begins polling for trigger files every 3 seconds.

Connects to Discord, starts the polling loop, and monitors for trigger.json in the bot's root directory. When a trigger is found, it checks all 16 documentation files for changes and sends notifications.

node index.js --seed CLI

Snapshots all current documentation file hashes without sending any Discord messages.

Use this when setting up the bot for the first time or after adding new bots to bots.json. It computes MD5 hashes for all documentation files and saves them to changelog_settings.json, then exits immediately.

📄 File Triggers

trigger.json File Trigger

Create this file in the bot's root directory to trigger a changelog check.

Format: {"message": "Your commit message here"}

The bot polls for this file every 3 seconds. When found, it reads the optional message field (used as the changelog description), deletes the file, then checks all documentation files for changes. Typically created automatically by a Git post-push hook.

🟠 Button Interactions

About [Bot Name] Button

Displays detailed information about the updated bot.

Each changelog notification includes an interactive button for every bot that was updated. Clicking the button shows an ephemeral embed with:
• Bot description
• Tech stack
• Link to documentation page

📩 Notification Types

Single Bot Update Auto Notification

Sent when one bot's documentation changes.

Shows a colored embed with the bot's emoji and name, the commit message as description, a direct link to the documentation, the tech stack in the footer, and one "About" button.

Multi-Bot Update Auto Notification

Sent when multiple bots' documentation changes in a single push.

Shows a blurple embed with inline fields listing each updated bot and their documentation links. Includes up to 25 "About" buttons across up to 5 rows (Discord's component limit).

🔧 Configuration

config.json

Key	Type	Description
`token`	String	Discord bot token
`clientId`	String	Discord application client ID

changelog_settings.json

Key	Type	Description
`changelog_channels`	Object	Map of guild IDs to channel IDs where changelogs are posted
`file_hashes`	Object	Stored MD5 hashes for each bot's documentation file
`posted_hashes`	Object	Hashes of messages already posted (deduplication)
`alert_roles`	Object	Roles to ping when changelogs are posted (per guild)

bots.json Entry Format

Key	Type	Description
`name`	String	Display name of the bot
`filename`	String	HTML documentation filename (e.g. `sports-bot.html`)
`color`	String	Hex color for embed (e.g. `0x2ECC71`)
`emoji`	String	Emoji used in embed titles and buttons
`description`	String	Short description shown in "About" embeds
`tech`	String	Tech stack shown in embed footer

📁 File Structure

changelog-bot/
├── index.js # Main entry point, Discord client, trigger polling
├── config.json # Bot token and client ID
├── bots.json # Registry of all monitored bots
├── changelog_settings.json # Channel config, hashes, state
├── package.json # Dependencies (discord.js v14)
└── utils/
    ├── changelogService.js # Core logic: detect changes, send notifications
    ├── embedBuilder.js # Build Discord embeds and buttons
    ├── hashService.js # MD5 hashing of documentation files
    └── logger.js # Console logging utility

🚀 Setup

1. Install

Run npm install in the changelog-bot directory to install discord.js v14.

2. Configure

Add your bot token and client ID to config.json. Add changelog channel IDs to changelog_settings.json.

3. Seed Hashes

Run npm run seed to snapshot current documentation hashes without sending notifications.

4. Start

Run npm start to begin polling. Create a trigger.json file to trigger change detection.