Root document (pages)
A root document: global config, shared named layers and sources, and a pages: list whose blocks are content, map, scrollytelling, or mixed blocks. Framework integrations render it; it is never the src of <ml-map>. For narrative see Root Configuration and Pages & Blocks.
config
Section titled “config”Type: object
Global configuration
Path: config.title · Type: string
Application title
description
Section titled “description”Path: config.description · Type: string
Application description
defaultMapStyle
Section titled “defaultMapStyle”Path: config.defaultMapStyle · Type: string (URL)
Default map style URL
Path: config.theme · Type: "light" | "dark" · Default: "light"
Default theme
defaultZoom
Section titled “defaultZoom”Path: config.defaultZoom · Type: number · Range: 0 to 24
Default zoom level for all maps
defaultCenter
Section titled “defaultCenter”Path: config.defaultCenter · Type: [number, number]
Default center [lng, lat] for all maps
dataFetching
Section titled “dataFetching”Path: config.dataFetching · Type: object
Data fetching configuration
defaultStrategy
Section titled “defaultStrategy”Path: config.dataFetching.defaultStrategy · Type: "runtime" | "build" | "hybrid" · Default: "runtime"
Default fetch strategy
timeout
Section titled “timeout”Path: config.dataFetching.timeout · Type: number · Default: 30000 · Minimum: 1000
Default timeout in milliseconds
retryAttempts
Section titled “retryAttempts”Path: config.dataFetching.retryAttempts · Type: integer · Default: 3 · Minimum: 0
Default retry attempts
layers
Section titled “layers”Type: map of object
Named layer definitions for reuse
<layer-id>
Section titled “<layer-id>”Path: layers.<layer-id> · Type: object
Same shape as layers[].
sources
Section titled “sources”Type: map of object
Named source definitions for reuse
<source-id>
Section titled “<source-id>”Path: sources.<source-id> · Type: object
See the Sources reference.
Type: object[] · Required · Min items: 1
Page definitions
Path: pages[].path · Type: string · Required
URL path (e.g., ”/”, “/about”)
Path: pages[].title · Type: string · Required
Page title
description
Section titled “description”Path: pages[].description · Type: string
Page description for SEO
blocks
Section titled “blocks”Path: pages[].blocks · Type: object[] · Required
Page content blocks
One of 5 variants, selected by type: content, map, map-fullpage, scrollytelling, mixed.
type: content
Section titled “type: content”Content block for rich text and media
Path: pages[].blocks[].type · Type: "content" · Required
Block type
Path: pages[].blocks[].id · Type: string
Unique block identifier
className
Section titled “className”Path: pages[].blocks[].className · Type: string
CSS class name for the block container
Path: pages[].blocks[].style · Type: string
Inline CSS styles for the block container
content
Section titled “content”Path: pages[].blocks[].content · Type: (map of object[])[] · Required
Array of content items to render
Path: pages[].blocks[].content[].<tag> · Type: object[]
Path: pages[].blocks[].content[].<tag>[].str · Type: string
Static text string
property
Section titled “property”Path: pages[].blocks[].content[].<tag>[].property · Type: string
Dynamic property from context
Path: pages[].blocks[].content[].<tag>[].else · Type: string
Fallback value if property missing
classList
Section titled “classList”Path: pages[].blocks[].content[].<tag>[].classList · Type: string | string[]
CSS class names (space-separated string or array)
Path: pages[].blocks[].content[].<tag>[].id · Type: string
Element ID attribute
Path: pages[].blocks[].content[].<tag>[].style · Type: string
Inline CSS styles
Path: pages[].blocks[].content[].<tag>[].href · Type: string (URL)
Link URL
target
Section titled “target”Path: pages[].blocks[].content[].<tag>[].target · Type: string
Link target (_blank, _self, _parent, _top)
Path: pages[].blocks[].content[].<tag>[].src · Type: string (URL)
Source URL for img or iframe
Path: pages[].blocks[].content[].<tag>[].alt · Type: string
Alternative text for images
Path: pages[].blocks[].content[].<tag>[].width · Type: string | number
Width (pixels or %)
height
Section titled “height”Path: pages[].blocks[].content[].<tag>[].height · Type: string | number
Height (pixels or %)
type: map
Section titled “type: map”Standard map block
See the Map block (v1) reference.
type: map-fullpage
Section titled “type: map-fullpage”Full-page map block
Path: pages[].blocks[].type · Type: "map-fullpage" · Required
Block type
Path: pages[].blocks[].id · Type: string · Required
Unique block identifier
className
Section titled “className”Path: pages[].blocks[].className · Type: string
CSS class name for container
Path: pages[].blocks[].style · Type: string
Inline CSS styles for container
config
Section titled “config”Path: pages[].blocks[].config · Type: object · Required
Map configuration with MapLibre options
Same shape as config.
sources
Section titled “sources”Path: pages[].blocks[].sources · Type: map of object
Map sources
<source-id>
Section titled “<source-id>”Path: pages[].blocks[].sources.<source-id> · Type: object
See the Sources reference.
layers
Section titled “layers”Path: pages[].blocks[].layers · Type: object[] · Default: []
Map layers
Each entry: see the Layers reference.
controls
Section titled “controls”Path: pages[].blocks[].controls · Type: object
Map controls
Same shape as controls.
legend
Section titled “legend”Path: pages[].blocks[].legend · Type: object
Legend configuration
Same shape as legend.
Path: pages[].blocks[].state · Type: map of object
Runtime-tunable values, readable from expressions via global-state
Same shape as state.
parameters
Section titled “parameters”Path: pages[].blocks[].parameters · Type: map of object
Presentation metadata for state keys — label, type, range
Same shape as parameters.
markers
Section titled “markers”Path: pages[].blocks[].markers · Type: object[]
Standalone markers — DOM pins live, symbol layers + sprite on export
Same shape as markers.
popups
Section titled “popups”Path: pages[].blocks[].popups · Type: object[]
Standalone popups open at a coordinate — no layer, no marker
Same shape as popups.
images
Section titled “images”Path: pages[].blocks[].images · Type: map of string | object
Named images for symbol layers and patterns — loaded live, merged into the sprite on export
Same shape as images.
terrain
Section titled “terrain”Path: pages[].blocks[].terrain · Type: object
3D terrain from a raster-dem source — setTerrain live, style.json terrain on export
Same shape as terrain.
Path: pages[].blocks[].sky · Type: object
Sky, fog, and globe atmosphere — setSky live (maplibre-gl >= 4.5), style.json sky on export
Same shape as sky.
projection
Section titled “projection”Path: pages[].blocks[].projection · Type: object
Map projection (globe needs maplibre-gl >= 5) — style.json projection on export
Same shape as projection.
Path: pages[].blocks[].light · Type: object
The style-spec light shading fill-extrusion faces — map.setLight live, style.json light on export
Same shape as light.
type: scrollytelling
Section titled “type: scrollytelling”Scrollytelling block for narrative map stories
See the Scrollytelling block reference.
type: mixed
Section titled “type: mixed”Mixed block for combining multiple block types
Path: pages[].blocks[].type · Type: "mixed" · Required
Block type
Path: pages[].blocks[].id · Type: string
Unique block identifier
className
Section titled “className”Path: pages[].blocks[].className · Type: string
CSS class name for container
Path: pages[].blocks[].style · Type: string
Inline CSS styles for container
layout
Section titled “layout”Path: pages[].blocks[].layout · Type: "row" | "column" | "grid" · Default: "row"
Layout direction
Path: pages[].blocks[].gap · Type: string
Gap between blocks (CSS gap property)
blocks
Section titled “blocks”Path: pages[].blocks[].blocks · Type: object[] · Required
Child blocks
Each entry has the same shape as pages[].blocks[].