HUB
Sign inSign up

paulmeier/mermaid-discord-bot

By paulmeier

β€’Updated 7 months ago

Image
0

404

paulmeier/mermaid-discord-bot repository overview

⁠Mermaid Discord Bot

A Discord bot that automatically detects and renders Mermaid⁠ diagram code blocks in chat messages, replying with a rendered PNG image β€” no commands required.


⁠How It Works

Post any message that contains a fenced ```mermaid ``` block:

```mermaid
graph TD
    A[Start] --> B{Is it working?}
    B -->|Yes| C[πŸŽ‰ Great!]
    B -->|No|  D[Debug]
    D --> B
```

The bot detects the block, renders the diagram locally using @mermaid-js/mermaid-cli⁠, and replies with the image β€” all within a few seconds.


⁠Features

FeatureDetails
Automatic detectionNo command needed β€” just post a ```mermaid ``` block
Multiple diagramsAll blocks in one message are rendered (up to MAX_DIAGRAMS_PER_MESSAGE)
Local renderingChromium + mmdc run inside the container β€” no external API calls
Rate limitingPer-user cooldown prevents abuse
Configurable themeSet via MERMAID_THEME env var
Docker-nativeOne docker compose up and it's running
Graceful shutdownHandles SIGTERM/SIGINT cleanly for zero-downtime restarts
Health checkDocker marks the container healthy only after the bot connects

⁠Prerequisites


⁠Setup

⁠1 β€” Create a Discord Application
  1. Go to the Discord Developer Portal⁠
  2. New Application β†’ give it a name β†’ Create
  3. Left sidebar β†’ Bot β†’ Add Bot
  4. Under Token β†’ Reset Token β†’ copy the token β€” this is your DISCORD_TOKEN
  5. Under Privileged Gateway Intents β†’ enable Message Content Intent (required for the bot to read message text)
  6. Left sidebar β†’ OAuth2 β†’ URL Generator
    • Scopes: bot
    • Bot Permissions: View Channels, Send Messages, Attach Files, Read Message History
  7. Open the generated URL to invite the bot to your server
⁠2 β€” Configure the Environment
cp env.example .env

Edit .env and fill in your token:

DISCORD_TOKEN=your_bot_token_here
⁠3 β€” Run
docker compose up -d

Check live logs:

docker compose logs -f

Stop:

docker compose down

⁠Configuration

All options are set via environment variables in .env (or directly in docker-compose.yml):

VariableDefaultDescription
DISCORD_TOKENrequiredDiscord bot token
MERMAID_THEMEdefaultDiagram theme: default | dark | forest | neutral | base
MERMAID_BACKGROUNDwhiteBackground colour β€” any CSS colour or transparent
RENDER_COOLDOWN_MS10000Milliseconds a user must wait between renders (rate limit)
MAX_DIAGRAMS_PER_MESSAGE3Maximum diagrams rendered from a single message
RENDER_TIMEOUT_MS60000Milliseconds before a render is aborted

⁠Supported Diagram Types

All Mermaid diagram types work out of the box:

  • Flowchart / graph
  • Sequence diagram
  • Class diagram
  • State diagram
  • Entity-relationship diagram
  • Gantt chart
  • Pie chart
  • Git graph
  • Mindmap
  • Timeline
  • And more…

⁠Local Development (without Docker)

Requirements: Node.js β‰₯ 20 and Chromium installed locally.

npm install
export DISCORD_TOKEN=your_token_here
npm start

mmdc (the Mermaid CLI) will use the PUPPETEER_EXECUTABLE_PATH env var or its own bundled Chromium. Set puppeteer-config.json args as needed for your OS.


⁠Troubleshooting

Bot doesn't respond to mermaid blocks

  • Confirm Message Content Intent is enabled in the Developer Portal
  • Confirm the bot has Send Messages and Attach Files permissions in the channel
  • Check logs: docker compose logs -f

Rendering fails / timeouts

  • The very first render after startup is slower (Chromium cold start)
  • Increase RENDER_TIMEOUT_MS if timeouts occur on large diagrams
  • Ensure shm_size: 256m is set in docker-compose.yml β€” Chromium needs shared memory

"Cannot find module" errors

  • Run npm install (or rebuild the Docker image with docker compose build --no-cache)

⁠Architecture

Discord message with ```mermaid block
         β”‚
         β–Ό
   src/index.js          β€” discord.js event listener
         β”‚  rate limit check (rateLimiter.js)
         β”‚  extract code from code fence
         β–Ό
   src/renderer.js        β€” writes .mmd file to /tmp,
         β”‚                  spawns mmdc (mermaid-cli)
         β”‚                  via child_process.execFile
         β–Ό
   @mermaid-js/mermaid-cli
         β”‚  launches headless Chromium (puppeteer)
         β”‚  renders diagram β†’ PNG buffer
         β–Ό
   discord.js reply with AttachmentBuilder(buffer)

⁠CI/CD β€” Auto-versioning, Changelogs, and Docker Hub

Two GitHub Actions workflows handle the full release pipeline automatically.

⁠Workflows
FileTriggerWhat it does
release.yml⁠Push to mainRuns semantic-release β†’ cuts a version tag β†’ pushes Docker image
docker-publish.yml⁠Pull request to mainBuild-only validation, no push
⁠How releases work (fully automated)
git push / PR merged to main
         β”‚
         β–Ό
  semantic-release inspects commits since last tag
  using the Conventional Commits spec
         β”‚
         β”œβ”€ no releasable changes? β†’ stops here, no new version
         β”‚
         β–Ό
  Determines next SemVer:
    fix:           β†’ patch  (1.0.0 β†’ 1.0.1)
    feat:          β†’ minor  (1.0.0 β†’ 1.1.0)
    BREAKING CHANGE β†’ major  (1.0.0 β†’ 2.0.0)
         β”‚
         β–Ό
  Updates CHANGELOG.md
  Commits changelog back to main   [skip ci]
  Creates git tag  v1.x.x
  Publishes GitHub Release
         β”‚
         β–Ό  (docker job starts)
  Builds linux/amd64 + linux/arm64
  Pushes to Docker Hub:
    :1.x.x   :1.x   :1   :latest
  Updates Docker Hub description from README
⁠Required Repository Secrets

Go to Settings β†’ Secrets and variables β†’ Actions in your GitHub repo and add:

SecretValue
DOCKERHUB_USERNAMEYour Docker Hub username
DOCKERHUB_TOKENA Docker Hub Access Token (not your password) β€” create one at hub.docker.com/settings/security⁠

Branch protection note: @semantic-release/git pushes the changelog commit directly to main using GITHUB_TOKEN. If your repo has branch protection rules that require PRs, go to Settings β†’ Branches β†’ main and enable "Allow specified actors to bypass required pull requests", adding the GitHub Actions app. Alternatively, replace GITHUB_TOKEN in the workflow with a PAT that has repo scope.

⁠Commit message conventions

This project uses Conventional Commits⁠. Stick to this format to get automatic version bumps:

feat: add support for dark theme diagrams       β†’ minor bump
fix: handle empty mermaid blocks gracefully     β†’ patch bump
docs: update README                             β†’ no bump
chore: update dependencies                      β†’ no bump

feat!: remove command-based rendering           β†’ major bump
# or equivalently:
feat: remove command-based rendering

BREAKING CHANGE: commands are no longer supported
⁠Using the Published Image

Replace <username> with your Docker Hub username:

# docker-compose.yml override
services:
  bot:
    image: <username>/mermaid-discord-bot:latest

Or pull directly:

docker pull <username>/mermaid-discord-bot:latest

⁠License

MIT

Tag summary

Content type

Image

Digest

sha256:fb0473418…

Size

627.4 MB

Last updated

7 months ago

docker pull paulmeier/mermaid-discord-bot