Why GitHub ignores your GeoJSON styling

I keep a private GitHub repo of (almost) every multi-day walk I’ve done, plus the ones I’m still planning. GPX files from CalTopo go in, GeoJSON comes out, and GitHub renders each file as a map on the file page. That last part is why we’re here. No app, no server, no map hosting. Commit a .geojson file and GitHub draws it for free.

Each trail carried its own colour, cycled from a 24-colour palette and written into the feature properties as simplestyle:

"properties": {
  "name": "Mt Isobel",
  "status": "done",
  "stroke": "#3cb44b",
  "stroke-width": 4,
  "stroke-opacity": 0.9
}

Those are the property names from the spec, and from GitHub’s own documentation. GitHub rendered every trail in the same default blue.

Ruling out the file

I assumed I’d made a mistake. I checked the property placement, the hex values, the geometry types, the file size against the 10 MB render limit, and the CRS84 projection requirement. All of it was fine. The map itself rendered correctly. Only the colour was missing.

Searching didn’t clear it up. GitHub’s documentation has a “Styling features” section listing marker-size, marker-color, marker-symbol, stroke, stroke-opacity, stroke-width, fill and fill-opacity, with a pointer to version 1.1.0 of the simplestyle spec. By that page, my file should work.

The GitHub.com version of the same page doesn’t have that section. There’s no deprecation note or replacement text, so unless you happen to have both versions open, there’s nothing to notice.¹

What happened

The documentation is built from a public repo, so the answer is in the source. The styling section is still in the file, wrapped in a version conditional:

{% ifversion geoJSON-with-MapBox %}
### Styling features
...
{% endif %}

The flag that controls it, data/features/geoJSON-with-MapBox.yml, has the explanation in a comment:

# Dotcom now uses Azure maps for geoJSON, but GHES/AE will still use the existing MapBox system
versions:
  ghes: "*"

GitHub.com moved its map rendering from Mapbox to Azure Maps. Azure Maps doesn’t implement simplestyle, so the styling properties stopped doing anything. Enterprise Server kept the Mapbox renderer, which is why the styling documentation still exists and is now scoped to Enterprise Server only. The same commit swapped the further reading links from Leaflet and Mapbox to Azure Maps on the GitHub.com page.

That commit is dated 27 June 2022.² I didn’t find a changelog post or deprecation notice to go with it, and there’s no error to catch: the properties are still valid GeoJSON, so nothing has cause to complain about them. They just aren’t read.

I haven’t found this written up elsewhere. Searches mostly return the Enterprise Server page, or posts from back when it still worked.

A test case

That’s circumstantial: a comment in a config file, and my own map being the wrong colour. So there’s a test case in a public repo, geojson-simplestyle-test. Six features in three pairs, each a styled feature beside an identical unstyled control. If simplestyle works, the pairs look different.

The renderer is easier to check than the map. File pages load their maps from viewscreen.githubusercontent.com, which pulls in /static/azure/atlas.min.css. atlas is the Azure Maps SDK global, and there’s no Mapbox or Leaflet stylesheet on the page. Gists go through the same viewer, so a .geojson gist loses its colours in exactly the same way.

Its JavaScript bundle has no marker-color, marker-size or marker-symbol, and no mention of simplestyle. stroke-width and fill-opacity appear only as Mapbox GL style names like circle-stroke-width (Azure Maps is a Mapbox GL fork) and as SVG attributes in the interface code. Nothing reads styling from a feature’s properties, which matches both the flag comment and what I was seeing.

What to do instead

Nothing in the file will fix this. The decision is server-side. What worked for me was to stop encoding meaning in colour and start encoding it in the data. Every feature in my repo carries a status property (done, doing, to do) alongside its name. It travels with the file, it survives into the combined map, and it can be grepped. None of that depends on a renderer honouring a styling convention.

Colour then becomes something the viewer applies at display time. I read the files locally in VS Code with Geo Data Viewer, which renders them with kepler.gl. It ignores simplestyle too, so the colours come from the layer config saved alongside the data: green for done, amber for doing, red for the one I haven’t started.

Neither viewer reads simplestyle, so the generator no longer writes it. The palette is gone, and the GeoJSON carries identity, status and geometry only.

The map still renders on GitHub, which is most of what I wanted from it. It just renders in one colour.