Massif style release
styles/massif is Python that writes MapLibre styles; everything a user downloads is generated
from it. Users' side: Massif. How the style itself is written:
styles/massif/README.md.
What is where
| Path | What |
|---|---|
styles/massif/*.py, layers/, palette.py | the generator |
styles/massif/sprite-src/, sprite/ | the icon SVGs and the sheet made from them (committed) |
styles/massif/<variant>.json | the MapLibre variants (generated, committed) |
styles/massif/examples/ | the extension examples (osm, custom) |
styles/massif/release/ | release.py (every flavour, npm, GitHub), site.py (the website's copy), screenshots.mjs, the npm README |
styles/massif/demo/ | a page loading the MapLibre styles from the website, npm, a local release or the repo |
styles/massif/LICENSE | MIT-0: use it for anything, no notice required |
carto/, dist/, family.json | generated, gitignored |
tools/style-cli/ | the converter (mapbox2css) and compiler (css2xml) |
tools/style-sprite/ | the sprite sheet (build.mjs) and the icon font's iconotype project (iconotype-project.mjs) |
tools/style-preview/ | the style dev page (style preview) |
styles/massif/compat.json | the oldest SDK these styles need |
.github/workflows/release-styles.yml | CI build of every flavour; the published release |
Building, from a clean checkout
# the tools
(cd tools/style-cli && npm ci && npm run build)
(cd tools/style-sprite && npm ci)
(cd styles/massif/release && npm ci && npx playwright install chromium) # screenshots only
# the style compiler as wasm, for the compiled flavours: from a style-tools-v* release, or
(cd libs-massif/cartocss/util && emcmake cmake -B build-wasm -DCMAKE_BUILD_TYPE=MinSizeRel \
&& emmake make -C build-wasm massif-style && cp build-wasm/massif-style.{mjs,wasm} ../../../tools/style-cli/wasm/)
cd styles/massif
node ../../tools/style-sprite/build.mjs sprite-src sprite sprite # after an SVG change
node ../../tools/style-sprite/iconotype-project.mjs sprite-src/poi sprite-src/MassifIcons.iconotype.json \
--badge 10.5,10.5,27,27 # after a POI SVG change
python3 build.py # the MapLibre variants
python3 build.py --convert # and the SDK project into carto/, for the style preview
The flavours
python3 release/release.py <version> [--only FLAVOUR]... [--screenshots] writes dist/: one folder
and one massif-<flavour>-<version>.zip per flavour, dist/npm/ (the npm package), and with
--screenshots one JPEG per variant.
maplibre— the committed variants, with the sources that have no public host (bathymap,contours,routes,satellite) swapped for empty placeholders of the same name. MapLibre refuses a style whose layer names a missing source, so the layers stay and the source is empty GeoJSON — or, for the raster, one transparentdata:tile at z0: a raster source with no URL throws, and a raster layer reading GeoJSON stops the whole map drawing.spriteis made absolute, the website'sv<version>/folder by default (--base-urlto change it): MapLibre resolves a relative sprite against the page, not the style, and draws nothing at all when the sprite fails. Minified;metadata["massif:version"]and["massif:placeholder-sources"]added.cartocss—build.convert()into the flavour folder, as--convertdoes intocarto/.cartocss-iconfont— the same conversion with--icon-font MassifIcons --icon-font-map <map> --icon-font-size 27 --fonts. The font is iconotype's (@iconotype/cli build) from the committed projectsprite-src/MassifIcons.iconotype.json, whichtools/style-sprite/iconotype-project.mjswrites fromsprite-src/poi/: each badge SVG loses its plate (the first<circle>), its glyph box (--badge 10.5,10.5,27,27of the 48 px badge) becomes the em, and iconotype's own fixer (init) makes the paths font-ready. Every name is mapped as each sprite the sheet bakes from it (restaurant,restaurant-poi,restaurant-mono). 27 is that box's height, soicon-sizescales a glyph exactly as it scaled the sprite; the converter still measures the sheet's disc once for the plate the SDK draws under the glyph. A codepoint is a contract: FNV-1a of the name into U+E000–U+F8FF, the next free slot on a collision, and the existing project's codes kept first, so adding or removing an icon moves no other, and an app's own font built from another folder lands each name on Massif's character. An icon whose SVG is removed stays in the project, unselected, holding its code. The flavour ships the project and the script iniconfont/(your own POI icons); the compiled one does not.*-compiled—massif-style css2xmlof every<name>.jsonof the folder, beside itsicons/,fonts/andlegend.json. The XML keeps the parameters live ([param::variant]).
Checking a build
gl-style-validate(@maplibre/maplibre-gl-style-spec) overdist/maplibre/*.json— CI runs it. It is what caughtroad_osm_low's["config", …]reaching MapLibre paint: MapLibre has noconfigexpression and the whole style failed to load.build.maplibre_stylefolds everyconfigto the variant's default (lib.fold_config), keeping it only inmassif:*metadata.build.convertfails on anywhen()in the CartoCSS (per-feature, blocks rule pruning); the compiled flavours are the real compiler's output, so a CartoCSS that does not compile fails.- Look at it: run the style preview server, then
/styles/massif/demo/?from=dist— the MapLibre flavour ofdist/, variant by variant; its SDK links open the style preview with the build's CartoCSS and icon-font flavours in the compare pane (?compare=/styles/massif/dist/cartocss-iconfont);?from=npm&version=<v>— the same for a published package, through unpkg;?from=site/site-v— the website's copy, once deployed.
Releasing from a machine
To try the npm package before an official release — publish a prerelease under the next
dist-tag, which npm install @massif-maps/styles does not pick up:
npm login # once; an account with publish rights on @massif-maps
cd styles/massif
python3 release/release.py 1.0.0-rc.1 --screenshots --npm next --dry-run # everything but the upload
python3 release/release.py 1.0.0-rc.1 --screenshots --npm next # publish the prerelease
python3 release/release.py 1.0.0-rc.1 --screenshots --npm next --github # and a GitHub prerelease
Then demo/?from=npm&version=1.0.0-rc.1 draws it from unpkg. --github makes the
massif-styles-v<version> release with every zip (gh, logged in; a version with - is marked a
prerelease), and the website picks it up on its next deploy. A prerelease's MapLibre JSON names the
website's v<version>/ sprite, which exists only once the site has deployed that release: until
then load it with the demo's sprite beside the JSON.
An official release from a machine is the same with --npm latest --github; prefer CI, which adds
npm provenance.
Releasing from CI
- On a pull request touching
styles/massif,tools/style-spriteor the converter: builds the wasm, every flavour and the screenshots, validates, uploads it all as an artefact. Nothing is published. - Actions → Release → Run workflow with
stylesset topatch,minor,major,autoor a version, andpublishon (Cutting a release, which also releases the SDK or the style tools in the same run). It callsrelease-styles.ymlwith the versionplanworked out, and:- npm
@massif-maps/styles@<version>(dist/npm, provenance, trusted publishing — no token); - GitHub release
massif-styles-v<version>with every zip andmassif-screenshots-<version>.zip, its notes the commits touching the styles since the last finalmassif-styles-v*(which commits); docs.ymldispatched, since a release made withGITHUB_TOKENtriggers no workflow.
- npm
Versions are the style's own semver, never the SDK's: a change that moves what a variant draws is a
minor, a renamed or removed parameter or variant a major. auto suggests from the commit titles; the
run summary shows what it picked, and an explicit bump overrides it.
The SDK a release needs
compat.json holds minSdk, the oldest SDK the styles work with. Raise it in the PR that makes
a style use something newer (a new massif:sdk-* key, a converter flag such as --live-light).
release.py writes it to the npm package.json (massif.minSdk), to every MapLibre style
(metadata["massif:min-sdk"]), to the release notes and to versions.json on the website.
- A number above the latest SDK release needs that SDK in the same run:
planfails otherwise. "next"means "the SDK released together with these styles", for a PR that cannot know the number.planresolves it to the SDK version of the run and fails when the run has none; the release then commits the number back tocompat.json.
The website
docs.yml runs styles/massif/release/site.py website/static/styles/massif: every non-draft
massif-styles-v* release's MapLibre zip and screenshots unpacked under v<version>/, the newest
also copied to the root (so …/styles/massif/streets.json is the latest), and versions.json.
With no release yet it builds the root from the checkout.
The doc page's live map and screenshot grid (website/src/components/MassifStyleMap.js) read those
paths, load the sprite from the site's own copy, and draw hybrid over EOX's
Sentinel-2 cloudless 2016 mosaic (CC BY 4.0, credited in the map), as the
screenshots do.