Discourse Murmurations — Quick Install & Dev Summary

What this is

Small WordPress plugin that:

• fetches users from a Discourse forum
• geocodes their locations
• exposes a Murmurations-compatible JSON feed
• provides a lightweight Leaflet map embed via shortcode

Install & setup (site owners)

Recommended (production)

• Download the latest ZIP from the repository Releases page (use the release ZIP, not the raw repo download).
• WP Admin → Plugins → Add New → Upload Plugin → select the ZIP → Install and Activate.

Why this: release zips contain packaged assets and avoid including development files.

Developer / quick local

• Clone into your local WP install plugins folder, or use the included docker-compose to run a disposable WP instance.

Docker quickstart (local dev):

git clone https://github.com/The-Digital-Circle/discourse-murmurations.git
cd discourse-murmurations
docker-compose up -d
# visit http://localhost:8080 and finish WP setup

Minimum configuration to show a map

1. WP Admin → Settings → Discourse Murmurations
   • Set Discourse Base URL
   • Create a Discourse API key and paste it in
   • API Username (usually system)
2. (Optional) Choose Tile Provider and set provider API key if required.
3. Save and click Manual Update (admin) to produce the JSON feed.

Where the JSON is

• Preferred REST endpoint: /wp-json/murmurations/v1/map
• Fallback (no pretty permalinks): /index.php?rest_route=/murmurations/v1/map

Embed the map

• Insert [murmurations_map] into a post or page. Optional shortcode attributes: src (JSON URL), width, height, zoom.

Quick troubleshooting

• If tiles are missing or CORS/opaque responses appear: ensure provider API key is set and the provider allows requests from your site origin (the embed sends Origin/Referrer).
• Inspect DevTools Console for dm: debug messages from the embed.
• Verify inline config: console.log(window.dmMurmConfigs) in the page console — the emitted object should include markerStyle, tileProvider and accentColor.

Development summary (contributors)

Essential files

• discourse-murmurations.php — plugin bootstrap, provider list, shortcode config emission.
• includes/ — PHP classes: admin settings, Discourse API client, geocoding service, generator, cron scheduler.
• assets/js/murmurations-embed.js — client-side embed (Leaflet map, markers, popups, clustering).
• assets/css/frontend.css — frontend styles for markers, clusters and popups.
• tools/ — small PHP scripts for checks and diagnostics.

Start developing

• Option A: docker-compose (see above).
• Option B: clone into your normal WP development instance plugins folder and activate.

Useful WP-CLI checks

# view saved options
wp option get discourse_murmurations_settings --format=json
# tile API key (stored non-autoload)
wp option get discourse_murmurations_tile_api_key

Quick validation cycle

1. Make changes to assets/js/murmurations-embed.js or assets/css/frontend.css.
2. In WP Admin run Manual Update (to refresh JSON) if you changed server-side behavior.
3. Reload the page that contains the shortcode with DevTools Network caching disabled.

Packaging a release

• Use scripts/package-release.sh to produce a release ZIP. Ensure working tree is clean and built assets present.

Contributing

• Fork → branch → PR. Keep changes small, include screenshots for UI work and describe any DB migration required.

License & support

• GPLv3
• Report issues on GitHub with reproduction steps and any console/network logs.