What is maplibre-yaml?

maplibre-yaml makes interactive web maps from YAML. You write a map document, a YAML file that names the basemap, your data, how to style it and what happens on click, and the <ml-map> element turns it into a MapLibre GL JS map on your page. You write no JavaScript.

Who it’s for

• People who want a web map without programming one: writers, journalists, researchers and anyone learning web mapping. A story map, where the map moves as the reader scrolls, is a YAML file too.
• Developers who want a map quickly, in one file that is fast to change and checked as you write it.
• People who already know MapLibre, who want the style spec they know with data loading, popups and legends in the same file.

How it works

1. You write a map document, map.yaml. Its layers: are MapLibre style layers, written in YAML; around them go the view, the basemap, the data sources, popups, a legend and controls.
2. A page shows it with <ml-map src="map.yaml"></ml-map>. The element comes from one script, loaded from a CDN or installed from npm, next to MapLibre GL JS, which your page loads too (maplibre-yaml uses your copy rather than bundling its own).
3. When the page opens, the element fetches the document, checks it, and builds the MapLibre map: it adds the sources and layers, fetches your data, and wires up the popups, hover and controls. A document with a mistake shows a card naming the line and the fix instead of a blank map.

Because the data is fetched when the page opens, a map of a live feed is current every time it is opened. Here is one map written both ways, first with MapLibre’s JavaScript API, then as a map document:

const map = new maplibregl.Map({
  container: "map",
  style: "https://tiles.openfreemap.org/styles/liberty",
  center: [-120, 37],
  zoom: 4,
});

map.on("load", () => {
  map.addSource("earthquakes", {
    type: "geojson",
    data: "https://earthquake.usgs.gov/earthquakes/feed/v1.0/summary/all_week.geojson",
  });
  map.addLayer({
    id: "earthquakes",
    type: "circle",
    source: "earthquakes",
    paint: { "circle-radius": 6, "circle-color": "#e74c3c" },
  });
  map.on("click", "earthquakes", (e) => {
    new maplibregl.Popup()
      .setLngLat(e.lngLat)
      .setHTML(`<h3>${e.features[0].properties.title}</h3>`)
      .addTo(map);
  });
});

type: map
id: earthquake-map
config:
  center: [-120, 37]
  zoom: 4
  mapStyle: "https://tiles.openfreemap.org/styles/liberty"
layers:
  - id: earthquakes
    type: circle
    source:
      type: geojson
      url: "https://earthquake.usgs.gov/earthquakes/feed/v1.0/summary/all_week.geojson"
    paint:
      circle-radius: 6
      circle-color: "#e74c3c"
    interactive:
      click:
        popup:
          - h3:
              - property: title

What you can make

Feature	Where to read about it
Points, lines and polygons from GeoJSON files, inline data or tiles	Loading data, Layers & styling
Popups, hover and map controls	Popups, hover & controls
Data that updates by polling, server-sent events or WebSockets	Live data & streaming
Choropleths and graduated symbols with a legend made for you	Thematic maps & legends
PMTiles, FlatGeobuf, GeoParquet and COG files from a static host	Large data
Story maps (scrollytelling)	Story maps in plain HTML
A map title and description for screen readers, and translations	Accessibility & languages
Checking a document in your editor or on the command line	Editor setup, The CLI
Exporting a map to a plain MapLibre style.json	Export to style.json

The packages

Package	What it is	When you need it
@maplibre-yaml/core	The <ml-map> and <ml-scrollytelling> elements, the parser and the JavaScript API	Always. On a plain HTML page it is the one script you load from the CDN
@maplibre-yaml/astro	Astro components (<Map>, <FullPageMap>, <Scrollytelling>) built on core	For an Astro site
@maplibre-yaml/cli	The maplibre-yaml command: validate, preview, start a project, export	Optional: to check documents on the command line or in CI

When to use something else

maplibre-yaml covers maps you can describe: layers, data, popups, legends, camera moves. Use MapLibre GL JS directly when:

• the map’s behaviour is your application’s logic: custom interactions beyond popups and hover, animation driven by code, or drawing and editing tools;
• you need custom WebGL layers;
• your code builds the whole map at run time anyway, so a document adds a step without saving one.

You don’t have to choose all at once. Page scripts can reach the MapLibre map an <ml-map> draws and add to it (JavaScript API), and mlym emit exports a document to a plain style.json that MapLibre loads on its own.

It is not a hosted map editor, a data-analysis tool or a visual style editor: you write the YAML in a text editor.

Next steps

Choose your path: a map in an HTML page, an Astro site, an app with a bundler, a story map, a thematic map or large data, with where to start and what to read next for each.