discourse-outline-bridge

A FastAPI service that automatically syncs Discourse topics to Outline collections, keeping your documentation in sync with forum discussions.

How it works

• Discourse fires a webhook on topic create/edit/delete
• The bridge fetches the topic content, cleans it, and upserts it into Outline
• A hidden HTML comment is appended to the Discourse post as a machine-readable marker
• A backlink footer is appended to every Outline document

Only the first post (OP) is synced — replies stay in Discourse as discussion.

Requirements

• Docker + Docker Compose
• A running Discourse instance with API access
• A running Outline instance with API access
• mailcow with nginx (for reverse proxy) — or adapt the nginx config for your setup

Installation

See the full runbook: https://digitallysovereign.org/t/discourse-outline-sync-bridge/632

Configuration

Copy .env-example to .env and fill in all values:

cp .env-example .env
nano .env
chmod 600 .env

Usage (from within /opt/outline-discourse-topics)

Build and start

docker compose down docker compose build docker compose up -d

Monitor log

docker compose logs bridge -f

Sync all configured topics

curl -s -X POST https://your-bridge-url/bulk-sync

Sync a single topic

curl -s -X POST https://your-bridge-url/sync
-H "Content-Type: application/json"
-H "X-Discourse-Event: topic_updated"
-d '{"topic": {"id": 123}}'

Backfill hidden marker to all existing topics

curl -s -X POST https://your-bridge-url/backfill-notices

Backfill a single topic

curl -s -X POST https://your-bridge-url/backfill-notices/123

Refresh all notices and Outline docs after template changes

curl -s -X POST https://your-bridge-url/refresh-notices

Check sync state

curl -s https://your-bridge-url/mappings | python3 -m json.tool

License

GPL-3.0-or-later