A Discord bot that automatically detects and renders Mermaidβ diagram code blocks in chat messages, replying with a rendered PNG image β no commands required.
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.
| Feature | Details |
|---|---|
| Automatic detection | No command needed β just post a ```mermaid ``` block |
| Multiple diagrams | All blocks in one message are rendered (up to MAX_DIAGRAMS_PER_MESSAGE) |
| Local rendering | Chromium + mmdc run inside the container β no external API calls |
| Rate limiting | Per-user cooldown prevents abuse |
| Configurable theme | Set via MERMAID_THEME env var |
| Docker-native | One docker compose up and it's running |
| Graceful shutdown | Handles SIGTERM/SIGINT cleanly for zero-downtime restarts |
| Health check | Docker marks the container healthy only after the bot connects |
DISCORD_TOKENbotView Channels, Send Messages, Attach Files, Read Message Historycp env.example .env
Edit .env and fill in your token:
DISCORD_TOKEN=your_bot_token_here
docker compose up -d
Check live logs:
docker compose logs -f
Stop:
docker compose down
All options are set via environment variables in .env (or directly in docker-compose.yml):
| Variable | Default | Description |
|---|---|---|
DISCORD_TOKEN | required | Discord bot token |
MERMAID_THEME | default | Diagram theme: default | dark | forest | neutral | base |
MERMAID_BACKGROUND | white | Background colour β any CSS colour or transparent |
RENDER_COOLDOWN_MS | 10000 | Milliseconds a user must wait between renders (rate limit) |
MAX_DIAGRAMS_PER_MESSAGE | 3 | Maximum diagrams rendered from a single message |
RENDER_TIMEOUT_MS | 60000 | Milliseconds before a render is aborted |
All Mermaid diagram types work out of the box:
Requirements: Node.js β₯ 20 and Chromium installed locally.
npm install
export DISCORD_TOKEN=your_token_here
npm start
mmdc(the Mermaid CLI) will use thePUPPETEER_EXECUTABLE_PATHenv var or its own bundled Chromium. Setpuppeteer-config.jsonargs as needed for your OS.
Bot doesn't respond to mermaid blocks
Send Messages and Attach Files permissions in the channeldocker compose logs -fRendering fails / timeouts
RENDER_TIMEOUT_MS if timeouts occur on large diagramsshm_size: 256m is set in docker-compose.yml β Chromium needs shared memory"Cannot find module" errors
npm install (or rebuild the Docker image with docker compose build --no-cache)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)
Two GitHub Actions workflows handle the full release pipeline automatically.
| File | Trigger | What it does |
|---|---|---|
release.ymlβ | Push to main | Runs semantic-release β cuts a version tag β pushes Docker image |
docker-publish.ymlβ | Pull request to main | Build-only validation, no push |
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
Go to Settings β Secrets and variables β Actions in your GitHub repo and add:
| Secret | Value |
|---|---|
DOCKERHUB_USERNAME | Your Docker Hub username |
DOCKERHUB_TOKEN | A Docker Hub Access Token (not your password) β create one at hub.docker.com/settings/securityβ |
Branch protection note:
@semantic-release/gitpushes the changelog commit directly tomainusingGITHUB_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, replaceGITHUB_TOKENin the workflow with a PAT that hasreposcope.
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
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
MIT
Content type
Image
Digest
sha256:fb0473418β¦
Size
627.4 MB
Last updated
7 months ago
docker pull paulmeier/mermaid-discord-bot