Interactive map-based storytelling for WordPress.

Mapthread transforms your travel stories, hiking adventures, and geographic narratives into interactive experiences with maps. Upload a GPX file, place markers in your story, and watch as readers scroll - the map automatically pans and zooms to follow along.

Perfect for:

• Hiking and adventure blogs
• Travel storytelling
• Cycling route documentation
• Race and event recaps
• Location-based historical narratives

• Map automatically follows your narrative as readers scroll
• Pauses when readers explore the map themselves, resumes when they scroll on
• Click any marker to jump to that part of the story text

• Upload a GPX file from any hiking, cycling, or fitness app
• Elevation profile with distance and gain/loss stats
• Street, Satellite, Topographic map styles plus more from Mapbox, Thunderforest, JawgMaps, and Stadia Maps (with API key)
• Fullscreen mode, layer switcher, and optional GPX download for readers

• Place waypoints anywhere in your story with optional emoji pins
• Find locations by address or paste coordinates
• Without a GPX file, markers are connected together using a straight line

• Two-column desktop view: story on the left, sticky map on the right
• Mobile-friendly: map tucks away so the story loads first
• Readers can dismiss and restore the map at any time

• Maling Ancient Road
• Jiyugaoka's Green Roads
• Hakuba: Into The Abyss
• Cycling the Shimanami Kaido

1. Go to Plugins > Add New in WordPress admin
2. Search for "Mapthread"
3. Click Install Now > Activate

1. Download the latest release from GitHub Releases
2. Upload the mapthread folder to /wp-content/plugins/
3. Activate through the Plugins menu in WordPress

cd wp-content/plugins
git clone https://github.com/randomwire/Mapthread.git
cd Mapthread
npm install
npm run build

1. Create or edit a post
2. Add the Map GPX block and upload your GPX file
3. Write your story, inserting Map Marker blocks at key points
4. Set coordinates for each marker (use the built-in address search, or paste from Google Maps)
5. Publish — the map automatically follows as readers scroll

• Map GPX: Uploads and displays your GPS track. Settings: progress indicator (auto-follow on/off), elevation profile, default map style, GPX download toggle.
• Map Marker: Places waypoints in your story. Settings: title, coordinates (with address search autocomplete), zoom level, optional emoji icon.

GPX files aren't required — Mapthread also works with just markers. Adding a Map GPX block without a file connects markers with straight lines.

• WordPress: 6.0+ with a block theme
• PHP: 7.4+
• Browsers: Chrome 105+, Safari 15.4+
• Tested themes: Twenty Twenty-Four, Twenty Twenty-Five

npm install
npm run build        # Production build
npm run start        # Development watch mode
npm run lint:js      # Check JavaScript
npm run format       # Format code

mapthread/
├── mapthread.php                 # Main plugin file
├── includes/
│   ├── class-mapthread.php       # Core class
│   ├── class-mapthread-settings.php # Settings page
│   └── blocks/
│       ├── map-gpx/            # GPX block
│       └── map-marker/         # Marker block
├── assets/
│   ├── js/
│   │   └── mapthread-frontend.js # Map behavior
│   └── css/
│       └── mapthread-frontend.scss
├── build/                      # Compiled assets
└── package.json

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Write tests if applicable
5. Submit a pull request

• Documentation: GitHub Wiki
• Issues: GitHub Issues
• WordPress.org: Support Forum

Libraries: Leaflet.js (BSD-2-Clause), Chart.js (MIT), Leaflet.fullscreen (MIT), Lucide (ISC)

Services: OpenStreetMap tiles & Nominatim geocoding, Open-Elevation API, optional tile providers (Mapbox, Thunderforest, JawgMaps, Stadia Maps)

See readme.txt for full external service documentation including data usage and privacy policies.

GPLv2 or later. All bundled libraries are GPL-compatible.

See CHANGELOG.md for version history.

• Koya Bound
• Riding the New Silk Road
• Eater Maps
• Animated Map Path for Interactive Storytelling

Made for storytellers and adventurers