By MW in mediawiki — 28 Jul 2024

Building Interactive Maps with MediaWikis Kartographer Extension

Why Kartographer Matters in a MediaWiki World

If you’ve ever scrolled through a Wikipedia entry and clicked a tiny globe icon, you’ve already seen Kartographer at work. The extension swaps a static coordinate link for a sleek, zoom‑able map that lives right on the page. No iframes, no extra clicks – just a slice of OpenStreetMap rendered with Leaflet, all courtesy of a few wiki‑syntax tags. For communities that love geography (think city‑pages, biodiversity lists, historic battlefields), that tiny interactive pane can turn a bland article into a mini‑atlas.

Getting the Extension on Your Wiki

First things first: Kartographer isn’t a plug‑and‑play widget you can paste into a Fandom page. You need to install it on a MediaWiki installation that meets the following baseline:

MediaWiki ≥ 1.33 (the LTS releases are safest)
PHP ≥ 7.2 (the extension leans on modern language features)
Composer installed – Kartographer pulls in Leaflet via Composer

Once those boxes are ticked, drop the extension folder into extensions/ and run the usual Composer command:

cd extensions/Kartographer
composer install --no-dev

Then add two lines to LocalSettings.php – the first loads the extension, the second flips the switch that tells MediaWiki you want the JavaScript assets to be served automatically:

// Load Kartographer
wfLoadExtension( 'Kartographer' );

// Enable the map UI on all pages (you can restrict later with $wgGroupPermissions)
$wgKartographerEnableMap = true;

If you’re running a Wikimedia‑style site (e.g., a language‑specific Wikipedia clone), the $wgKartographerMapService variable already points to Wikimedia’s CDN. For private wikis you’ll probably want the default https://maps.wikimedia.org endpoint, or you can self‑host Leaflet tiles – the docs have a tiny section on that.

The Core Tags: `<mapframe>` and `<maplink>`

Seriously, the whole magic lives in two tags. Neither of them looks like traditional HTML – they’re MediaWiki parser tags, which means they get expanded during page rendering.

1. `<mapframe>`

This tag inserts the actual map box. At its simplest you feed it a single coordinate pair:

<mapframe latitude="40.7128" longitude="-74.0060" zoom="10" />

That snippet tacks a 250 × 250‑pixel map of Manhattan into the article. You can tweak a handful of attributes:

width / height – pixel dimensions, or percentages if you like fluid layouts.
zoom – integer 0‑18, higher means you’re looking at the street‑level.
thumb – set to true to get a thumbnail‑style preview that expands on click.
layers – a pipe‑separated list of predefined layers (e.g., osm|wikidata).

Here’s a more fleshed‑out example that also loads a custom GeoJSON overlay (we’ll get to that later):

<mapframe 
  latitude="51.5074" 
  longitude="-0.1278" 
  zoom="12" 
  width="600" 
  height="400" 
  layers="osm|myplaces" 
/>

Notice the line‑breaks – they’re optional but make the markup easier on the eyes, especially when you pile on many attributes.

2. `<maplink>`

If you just want a clickable link that launches a full‑screen map, <maplink> is your go‑to. It’s often paired with <mapframe> on the same page, acting like a “see bigger” button.

<maplink 
  latitude="34.0522" 
  longitude="-118.2437" 
  zoom="10" 
  text="Open a larger map of Los Angeles" 
/>

The text attribute the default “view larger map” phrasing, so you can match your article’s tone.

Adding Real‑World Data with GeoJSON

Static points are fine, but real power of Kartographer shines when you load GeoJSON – a lightweight format for geographical features. You can host the JSON file anywhere (the same server, GitHub, or a CDN) and reference it via the data attribute on <mapframe>:

<mapframe 
  latitude="48.8566" 
  longitude="2.3522" 
  zoom="13" 
  data="https://example.org/paris-parks.geojson" 
/>

That line pulls in every park polygon from the external file and renders them with the default style (a semi‑transparent green fill). Want a different look? Add a style attribute that points to a JSON style object – the same syntax Leaflet uses:

<mapframe 
  latitude="48.8566" 
  longitude="2.3522" 
  zoom="13" 
  data="https://example.org/paris-parks.geojson" 
  style='{"color":"#006400","weight":2,"fillOpacity":0.3}' 
/>

Note the single quotes around the JSON string; MediaWiki’s parser would get confused if you used double quotes inside double‑quoted attributes.

Layer Management: Stacking Tiles and Overlays

Kartographer comes with a handful of built‑in tile layers: osm (the default OpenStreetMap raster), osm-fr (the French style), and wikidata (points from Wikidata). You can also register custom layers in LocalSettings.php:

$wgKartographerLayers['myplaces'] = [
    'label' => 'My custom places',
    'type'  => 'geojson',
    'url'   => 'https://example.org/myplaces.geojson',
    'style' => [
        'color' => '#ff6600',
        'weight' => 3
    ]
];

After that, the layers attribute on <mapframe> can reference myplaces alongside the default OSM tiles. The UI automatically adds a layer switcher in the map corner – a handy way for readers to toggle between, say, modern streets and historic maps.

Performance Tips (and Common Pitfalls)

Interactive maps are great, but they can also slow a page down if you’re not careful.

Limit GeoJSON size. A 50‑KB file loads instantly; a 5‑MB file will make the reader wait and could even time out. If you need a lot of points, consider clustering – Kartographer supports Leaflet’s MarkerCluster plugin out of the box when you add cluster=true to the tag.
Cache aggressively. Set proper Cache‑Control headers on your GeoJSON endpoint. The extension respects HTTP caching, so the map won’t re‑download the same data on every visit.
Watch your CSS. Because the map is rendered inside a <div> with the class mw-kartographer, custom site skins that override generic div width/height can distort the map. Test on a few pages before you roll the feature out site‑wide.
Mind the coordinates. Latitude must be between –90 and 90, longitude between –180 and 180. A stray sign or a misplaced decimal point will throw the map off to the Atlantic or even crash the rendering script. (I’ve seen one editor accidentally type “-800.0” for longitude – that was a fun debugging session.)

Putting It All Together: A Mini‑Case Study

Suppose you’re curating an article about the “Great Lakes.” You want a map that shows the lakes themselves, city markers, and a clickable link to a full‑screen view. Here’s a compact yet complete markup that achieves that:

<mapframe 
  latitude="45.0" 
  longitude="-84.0" 
  zoom="5" 
  width="100%" 
  height="400" 
  layers="osm|greatlakes" 
/>

<maplink 
  latitude="45.0" 
  longitude="-84.0" 
  zoom="6" 
  text="Explore the Great Lakes in full screen" 
/>

And the PHP snippet that registers the custom “greatlakes” layer (hosted as greatlakes.geojson on the same wiki):

$wgKartographerLayers['greatlakes'] = [
    'label' => 'Great Lakes boundaries',
    'type'  => 'geojson',
    'url'   => $wgScriptPath . '/extensions/Kartographer/resources/greatlakes.geojson',
    'style' => [
        'color' => '#1e90ff',
        'weight' => 2,
        'fillOpacity' => 0.2
    ]
];

When the page renders, readers first see a tidy rectangular map with the lake outlines in a soft blue. Below it sits a link that, when clicked, expands the map to the whole screen, preserving the same layer stack.

Beyond Wikis: Using Kartographer’s JavaScript Outside MediaWiki

Because the heavy lifting is done by Leaflet, you can reuse the same geojson files or even the Kartographer‑generated JavaScript in non‑wiki projects. The GitHub repo (wikimedia/mediawiki-extensions-Kartographer) includes a dist/kartographer.js bundle that you can import via a CDN. The API is straightforward: call mw.kartographer.map.init() on a container element, pass the same parameters you’d use in the wiki tags, and you’ve got a self‑contained map widget. It’s a handy trick if you’re migrating a wiki section to a static site but still want the same geographic flavor.

Wrapping Up

Building interactive maps with the Kartographer extension is a blend of a few small steps – install, configure a couple of variables, sprinkle <mapframe> and <maplink> tags, and optionally feed in GeoJSON layers. The result feels native, loads quickly (thanks to tile caching), and gives readers a tactile sense of place without ever leaving the article. Whether you’re documenting a city’s transit network or mapping the spread of a rare plant, the extension offers a low‑maintenance, visually consistent solution that scales from a single page to an entire wiki.

As with any tool, the sweet spot lies in keeping the data light, testing the UI across skins, and using the layer system to avoid clutter. When those boxes are checked, you’ll find Kartographer turning ordinary text into a dynamic, map‑driven narrative – and that’s something even the most seasoned cartographer would tip their compass to.