GitHub - chrispy90/waymark

Write a story. Scroll it. Publish it anywhere.
Waymark is a self-hosted editor for scroll-driven map stories and the maps inside them.
Build maps with live government data and analysis, reuse them across stories, then share a link or export a website.

Quick start · Features · Saved maps · Export · Self-hosting · Story format

⚡ Start in a minute

You only need Node.js 22.13 or newer. There's nothing to npm install.

git clone https://github.com/chrispy90/waymark.git
cd waymark
npm start

Then open http://localhost:5180.

1. Create your account. The first visit makes you the owner.
2. Answer a few questions. Pick what you're making and a look, add a title and your places, and Waymark sets up the story for you.
3. Click anything to edit it. When you're happy with it, press Publish.

✨ What you can make

A map that moves with the story

The map stays put while story cards scroll past, and it glides to each card's place. You can tilt it, rotate it, switch layers, or swap it for a photo or video on any card. Select words in a card and press Map link to make them send the map somewhere else; click a link in the text to change it, move it to other words, or remove it.

Scroll effects, built in

Effects from the best long-form sites, available as blocks. Add one and it works on phones too. Each effect switches off for readers who ask their device to reduce motion.

You also get chapters that recolor the page, big numbers that count up, and parallax, zoom and wipe-in photos and covers.

Live data from NOAA, NASA, USGS and more

Open Browse public data and click Add. Every layer arrives styled, with popups, a legend and credit to its source. No keys and no sign-ups.

Live layers refresh every time someone opens the story, so a published map stays current.

3D Terrain, Elevation HUD & 3D City Buildings

Turn on realistic 3D elevation with a single click in any story map, moving map or saved map:

• Free global DEM terrain & hillshading: powered by Mapzen Terrarium elevation tiles with dynamic vertical exaggeration (1.0× to 3.0×) and atmospheric sky horizon.
• 3D city building footprints: toggle extruded 3D structures (fill-extrusion) from OpenFreeMap vector building footprints with true-to-height scaling and ambient shadows.
• Camera Tilt & Pitch HUD: live interactive tilt angle indicator in the map status bar with real-time pitch readouts (up to 85°).

3D Polygon & Hexbin Extrusions + Bivariate Mapping

Display complex multivariate geospatial relationships directly on the map:

• 3D Attribute Extrusions: extrude any 2D polygon layer or hexbin summary into 3D height prisms scaled proportionally to any numeric attribute (e.g. population, total sales, earthquake count).
• 3×3 Bivariate Choropleth: map two continuous variables simultaneously (e.g. household income vs climate flood risk) with quantile breaks and an interactive 3×3 matrix legend.

Remote Sensing, STAC Satellite Finder & Time Travel

Professional Earth Observation and spectral analytics without leaving the browser:

• Spectral Index Catalog: one-click live overlays for NASA MODIS NDVI Vegetation Health, False-Color Infrared 7-2-1 (burn scar & flood detection), Sea Surface Temperature (GHRSST), Aerosol Optical Depth (wildfire smoke & dust), Snow Cover NDSI, and USGS 3DEP Shaded Relief & National Hydrography.
• Live STAC Satellite Scene Finder: search Copernicus Sentinel-2 L2A scenes around your map viewport using Element84 Earth Search STAC API. Filter by cloud cover %, inspect scene metadata (MGRS tile, sun elevation, telemetry), and stream 10-meter Cloud-Optimized GeoTIFFs (COG) directly into the map.
• Satellite Time-Travel Before & After: compare multi-date satellite imagery side by side with a draggable swipe divider to detect wildfire burn scars, urban sprawl, drought depletion, or glacial retreat.

Universal GIS Ingest: KML, GPX, Photos, GeoJSON & CSV

Drop any spatial file directly onto the map or Data panel:

• KML & KMZ: parses Google Earth placemarks, folders, lines, polygons, and ExtendedData attributes.
• GPX: reads GPS waypoints, tracks, and routes with automatic distance, elevation gain/loss, and timestamp stats.
• Geotagged JPEG Photos: extracts camera EXIF GPS coordinates and timestamps; multiple photos automatically merge into an interactive photo-points layer with popup image previews.
• Elevation Profile & Slope Analysis Tool: sample polylines or points against the global DEM in the Analyze toolbox to compute total distance, elevation gain/loss, and slope grade percentages (%).
• $ELEVATION_M in Field Calculator: access elevation directly in attribute tables and calculate derived metrics.

Filter it, then analyze it

Filters narrow a layer with plain rules, like magnitude ≥ 5, in the last 7 days or state = Texas. They apply to the map, the insights, the analysis and the export.

Analyze previews every result on a map before you keep it. Results become ordinary layers, and you can re-run them on fresh data. The 23 tools are grouped the way desktop GIS toolboxes group them:

You can also show points as a heatmap or clusters, or use proportional symbols: size points, areas or lines by a number field (circle area grows with the value, and it works together with color). Give a layer a time field and its maps get a time slider with play, showing everything up to a moment or a trailing day, week or month. Readers can scrub it too, and bookmarks and story cards remember where it was set. Bring your own data: GeoJSON, KML, GPX, geotagged photos, CSV, Hosted Feature Layers, or any public ArcGIS layer.

Hosted feature layers & editable attribute tables

Create reusable, server-backed GeoJSON feature layers (like ArcGIS Online Hosted Feature Layers) from the Layers tab on the home screen, from inside the map or story editor, or by promoting any drawn, uploaded, or analyzed layer in one click.

• Editable attribute tables & schema studio: click any cell to edit values inline, or add, rename, and delete columns (string, number, date, boolean). Add or delete feature rows and see live column statistics (Sum, Avg, Min, Max) in the header.
• Field Calculator: compute values across all features using column math (+, -, *, /, % of, % change), automatic spatial geometry measurements ($AREA_KM2, $AREA_ACRES, $LEN_KM, $LAT, $LON), rankings (1..N), or text templates.
• Source attribution & live service URLs: attach source attribution/credits to a hosted layer so it automatically appears on map legends and credits, copy its live /api/layers/:id/geojson endpoint, or export any table to GeoJSON or CSV.

Interactive charts & executive tables

Add a Chart & table block to any story — or click Add chart to story directly from a layer's Insights histogram — to present data alongside your narrative:

• Four views: horizontal Bars, vertical Columns, SVG Donut rings with total callouts, or sortable Executive Tables.
• Live layer aggregation or custom rows: group and aggregate (count, sum, avg, min, max) any layer in your story on the fly, or enter custom rows with prefixes and suffixes (such as $ or %).

Make a map once, use it in every story

Maps on the home screen are maps you build on their own, in a full-screen map editor, and then use in as many stories as you like. Edit the map once and every story that uses it updates, published stories included.

• Layers: live public data, hosted feature layers, your files, or links. Reorder them by dragging, switch them on and off, and zoom to each.
• Per-layer settings: color, proportional symbols, a time field for the time slider, labels, popups, source attribution, filters, visible zoom range and insights, plus an editable attribute table & schema studio you can sort, search, calculate and edit. Click a row number to zoom to that feature.
• Tools: 22 analysis tools (multi-ring trade areas, hub & spoke desire lines, spatial density clusters, attribute table joins, clip, erase, intersect, dissolve, spatial join, buffer, hex bins, Voronoi and more), a time slider, drawing, measuring, place search, a live coordinate & zoom HUD, a basemap gallery and the legend.
• Bookmarks: named views that also remember which layers are on, with a note for each.

Then walk readers through it: one click turns the bookmarks into moving-map cards, so a story can show the raw data, then the analysis, then the result, one card at a time. Any map in a story can also use a saved map, showing one of its bookmarks or a view you frame.

Draw right on the map

Press Draw on any map in the editor and sketch points, lines, freehand routes, areas, boxes, circles and text labels right on it. Give each shape its own colors, fill, line width, dashes or dots, and an arrowhead, plus a name and a description that readers see when they click it. Distances and areas are measured as you draw. Select a shape to move, restyle or duplicate it, trace over any other layer, and reopen a saved drawing or Hosted Feature Layer whenever you like.

Tours from your phone photos

Stop by stop tours have their own tour builder: every stop numbered on a big map, a list with photo thumbnails, and the selected stop's photo, name and text side by side. Drop a batch of photos and each becomes a stop where it was taken, in the order you took it, named after the file. Photos without a location are flagged and placed with a click. Add stops by searching or clicking the map, drag markers to move them, and drag the list to reorder.

An editor that gets out of the way

Click anything in the live preview to edit it. You also get drag to reorder, undo and redo, a command palette (Ctrl/⌘+K), a phone preview and autosave. Drafts stay private until you publish again.

Make it loud: the Brutalist look

Switch any story to Brutalist for raw monospace and heavy display type, hard black edges and offset shadows, acid-yellow stickers, a ticker headline, outlined words that fill in as you scroll, and numbered chapters. Or start from the Brutalist zine template.

Every story works on a phone

Start with a few questions, not a demo to delete

New story asks what you're making, how it should look, its title and cover, and where it goes. Then it builds the story around your places and chapters, with short prompts where your words go. A checklist in the editor walks you through the rest: cover photo, your own text, photos, a phone check and publishing.

Every kind comes in eight looks. Each one sets the type, colors, chapter colors, map style and scroll animation. You can switch later under Story → Look & feel, and restyle existing chapters and maps to match in one click.

Prefer to learn from something finished? Explore an example opens a complete story to take apart: the moving map, walk, essay, Brutalist zine and Down the Potomac samples. Any story can also use Before & after, a block with two maps in one view and a draggable divider, or Chart & table, an interactive breakdown of any layer or dataset.

🚀 Publish it anywhere

Publish gives a story a public link like /s/your-story, with a preview image when the link is shared.

Export as a website turns a story into plain files that run on any web server, with no Node, no database and no Waymark.

The export includes the page, your images, a snapshot of your map data (saved maps included) and, optionally, the map library. Every path is relative, so it works in any folder. You can also export from the command line:

node server.js export my-story --war --out /opt/tomcat/webapps/my-story.war

node server.js stories                       # find the story's link or id
node server.js export my-story               # published version, as a .zip
node server.js export my-story --draft       # the unpublished draft

🏠 Host it yourself

Your stories, saved maps, accounts and images all live in one data/ folder. Waymark runs anywhere that has Node 22.13+ or Docker and a persistent disk: a VPS, a home server, Fly.io, Railway, Render and so on.

1. Put it behind HTTPS. Caddy is the easiest: caddy reverse-proxy --from stories.example.com --to localhost:5180
2. In .env, set APP_URL=https://stories.example.com and COOKIE_SECURE=1.
3. Once your accounts exist, set ALLOW_SIGNUP=0 to close sign-ups.
4. Back up data/. It holds everything.

npm run users                                 # list accounts
npm run reset-link -- someone@example.com     # print a reset link
npm run set-password -- someone@example.com   # type a new password directly

📚 Under the hood

Waymark is plain JavaScript with no build step and no dependencies. The server uses only Node's built-in modules, including node:sqlite. The browser app is ordinary ES modules. Maps are drawn with MapLibre GL JS on free OpenFreeMap and Sentinel-2 basemaps.

server.js              entry point + startup checks
server/index.js        HTTP server: API routes, uploads, published pages, static files
server/db.js           SQLite schema (built-in node:sqlite)
server/auth.js         password hashing, sessions, reset tokens, rate limiting
server/mail.js         minimal SMTP client
server/cli.js          admin commands
server/brand.js        app name and tagline
public/                the web app (plain ES modules, no build step)
  js/render.js         story → page; all block renderers
  js/effects.js        scroll-driven effects engine (one rAF loop, on-screen elements only)
  js/fog.js            weather for the Fog look (fog layers, lantern, gusts, lightning, visibility readout)
  js/ui.js             icons, logo, toasts, menus, dialogs
  js/maps.js           MapLibre helpers: basemaps, views, data layers (incl. heatmap/clusters), legend, popups
  js/analysis.js       geospatial tools and layer statistics (Turf.js, loaded only in the editor)
  js/workbench.js      Add data, Analyze and Draw workspaces
  js/mapeditor.js      the saved-map editor (map.html)
  js/webmap.js         saved maps in stories: builds them into a story before it's shown or exported
  js/table.js          hosted feature layers, editable attribute tables, schema studio and field calculator
  js/layer-form.js     layer settings, shared by the story editor and the map editor
  js/catalog.js        public data catalog (government sources + ArcGIS Online search)
  js/export-core.js    static-site / .war exporter (shared by the editor and `node server.js export`)
  js/export.js         the export dialog
  js/zip.js            minimal zip writer
  js/builder.js        the story editor
  js/wizard.js         the New story wizard; story-kit.js builds stories from its answers and holds the looks
  js/tour.js           the tour builder for Stop by stop; exif.js reads where and when photos were taken
  js/templates.js      finished examples
  map.html             the saved-map editor page
  welcome.html         landing page for signed-out visitors (itself a story)
  stories/, data/      sample story and sample GeoJSON
docs/SCHEMA.md         the story and saved-map file formats
test/                  API tests plus unit tests for saved maps, hosted layers, the wizard, photo locations and story formats (node:test)

🤝 Contributing

Bug reports, ideas and pull requests are welcome. Start with CONTRIBUTING.md. Please report security problems privately, as described in SECURITY.md. Each release is listed in the changelog.

Background

This project started as a rebuild of the ArcGIS StoryMaps reading and authoring experience. It was written from scratch using only public behavior and open formats. Esri's open-source classic templates (Map Journal, Map Series, Apache-2.0) and mapbox/storytelling (BSD-3) were studied for data models and UX patterns only. No code was copied, and the current closed-source ArcGIS StoryMaps product was not used.

License

Waymark is released under the MIT License.

It loads these open-source libraries from a CDN (an exported story can bundle MapLibre, along with its license): MapLibre GL JS (BSD-3-Clause) and, in the editor only, Turf.js (MIT).

Map tiles and data come from their providers, which are credited on every map: OpenStreetMap contributors and OpenFreeMap (ODbL), Sentinel-2 cloudless by EOX (CC-BY 4.0), and USGS, NOAA, NASA, US Census Bureau, NPS, USDA Forest Service, EPA, NIFC and Natural Earth (public domain). If you host Waymark for others, keep those credits visible.