Add an icon to the map

Replicates the MapLibre example Add an icon to the map. The upstream map.loadImage(...) + map.addImage(...) pair becomes a declarative images: entry.

The complete document

add-an-icon-to-the-map.yaml

# yaml-language-server: $schema=https://docs.maplibre-yaml.org/schema/latest/map.schema.json
# Gallery twin of https://maplibre.org/maplibre-gl-js/docs/examples/add-an-icon-to-the-map/
# images: declares named images the document's layers reference; they load
# before layers live, and merge into the emitted sprite on export.
type: map
id: add-an-icon-to-the-map
config:
  center: [0, 0]
  zoom: 1
  mapStyle: "https://demotiles.maplibre.org/style.json"
images:
  osgeo-logo: "https://maplibre.org/maplibre-gl-js/docs/assets/osgeo-logo.png"
sources:
  point:
    type: geojson
    data:
      type: FeatureCollection
      features:
        - type: Feature
          geometry: { type: Point, coordinates: [0, 0] }
          properties: {}
layers:
  - id: logo
    type: symbol
    source: point
    layout:
      icon-image: osgeo-logo

What to notice

• images: names load before layers, so icon-image: osgeo-logo resolves on first render — no styleimagemissing race.
• On export (mlym emit), the image is fetched at compile time and merged into the document sprite; the layer’s reference is rewritten to mlym:osgeo-logo. The images: construct fully compiles — class exports, so --strict accepts it.
• Options ride along per entry: { url, sdf, pixelRatio } instead of the bare URL string.