Storymap reference
Everything a storymap understands: the attributes of a step, the settings of a map, and what a theme can style. Your first storymap and Mapping a mission show them at work.
The container
A storymap is what's between ::: storymap and :::. It starts with the map settings, in a YAML or JSON code block, which can be left out. Each heading of the first heading level after them starts a step, and the step lasts until the next one. Text before the first heading is a step too, which shows the starting view.
::: storymap
```yaml
center: [-157.86, 21.3]
zoom: 6
```
### A step {zoom=9}
The text of the step.
:::When a step contains other blocks that use :::, such as a callout, open and close the storymap with four colons, ::::.
Step attributes
The attributes go in braces after a step's heading, separated by spaces. A value with a space or a comma in it goes in quotes.
The view
| Attribute | What it sets |
|---|---|
center |
The longitude and latitude to centre on: center="-157.86,21.3" |
zoom |
The zoom level |
bounds |
An area to fit, instead of a centre and a zoom: west, south, east and north, bounds="-160,0,-150,22" |
bearing |
The direction that's up, in degrees clockwise from north |
pitch |
The tilt, in degrees: 0 looks straight down |
duration |
How long the move to the step takes, in milliseconds. A timeline runs for the same time. duration=0 cuts to the step. |
speed |
How fast the map flies, where 1.2 is MapLibre's own speed. Less is slower. |
A step with none of these keeps the whole view of the step before it. With some of them, center and zoom carry over when they're left out, while bearing and pitch go back to north up, seen from above. So a view never depends on the way the reader came: scrolling back up shows what they saw on the way down.
Without a duration or a speed, MapLibre times a flight by its length.
Time and layers
| Attribute | What it sets |
|---|---|
until |
Shows the timeline layers up to this date or time: until="2023-07-17" or until="2023-07-17T18:00:00Z". A date includes the whole day. |
from |
Shows them from this date or time on, for a window on the timeline |
show and hide |
Layers to show or hide for this step, by their ids: show="ports,routes" |
date |
The day that dated sources show: date="2023-07-17". Without it, the day of the step's until. |
from, until, show and hide aren't carried over. A step shows the layers as the settings define them, apart from its own show and hide, and the whole timeline unless it has a from or an until. A step without a date or an until keeps the date of the step before it.
Pictures
| Attribute | What it sets |
|---|---|
image |
A picture for the step. When any step has one, the storymap shows pictures instead of a map. |
figure |
A picture over the map, beside the step: figure="/charts/equator.webp" |
alt |
The text alternative of the step's image or figure. Leave it out for a picture that's only decoration. |
A step without an image keeps the picture of the step before it. Without JavaScript, each picture shows in its step, after the heading. When the steps float over the pictures, as on a story page, the pictures are fitted beside them.
A figure is for what goes with the map, not in place of it: a chart of what was measured where the map is, or a photograph of the place.
### On the equator {bounds="-155,-1,-152,3" figure="/charts/equator.webp" alt="The layer rises at dusk and sinks at dawn."}It shows in a panel at the bottom of the map, under a row of the step's legends, and the view of the step leaves room for it. A step without a figure shows none. A figure is loaded when the reader comes near its step. On a narrow page, where a map has no room for a panel, a figure shows in its step, after the heading, as it does without JavaScript.
The steps of a storymap have either images or figures.
Map settings
| Setting | What it sets |
|---|---|
style |
The base map: a MapLibre style URL, a light and a dark one, which follow the site's colour scheme, or the style itself. By default, the free OpenFreeMap styles. |
sources |
The data, as MapLibre sources: GeoJSON, in a file or written in the settings, vector or raster tiles, or a PMTiles file, with a pmtiles:// URL. A source with {date} in its address is dated. |
layers |
How to draw the data, as MapLibre layers. A layer with visibility: none in its layout is hidden until a step shows it. |
timeline |
The layers whose features hold a time |
legend |
What the colours of a layer mean |
popups |
What to show for the feature under the pointer |
projection |
mercator, a flat map, or globe, which shows the Earth as a sphere when the map is zoomed out. Flat by default. |
controls |
The buttons and the scale on the map |
map |
Other options of the MapLibre map, such as minZoom, maxZoom or maxBounds |
layout |
docked, the steps beside the map, or above it on a narrow page, or floating: the map fills the storymap, and the steps scroll over it as cards. Docked by default, and floating on a story page. |
center, zoom, bearing, pitch, bounds |
The view before the first step that sets one |
A URL that starts with / is a file of the site, in its public folder. Postdoc adds the site's base path to it.
timeline
timeline:
property: time
layers: [track, positions]
marker: true| Key | What it sets |
|---|---|
layers |
The ids of the layers that from and until apply to |
property |
The property of their features that holds the time, as an ISO 8601 time in UTC, such as 2023-07-17T18:00:00Z. time by default. |
marker |
true puts a marker where the timeline has got to: the end of its latest feature. To follow another source than that of the first timeline layer, give its id. For a marker with a label or a colour, or for several markers, give their settings. |
animate |
false shows each step's time at once |
Between two steps the time runs from the one to the other, so a track draws itself. It does so when the timeline's sources are GeoJSON, which Postdoc reads the times and the positions from. With another kind of source, such as vector tiles, each step still shows its part of the timeline, at once.
A track is usually many short lines, one for each leg. When a map is zoomed far out, MapLibre leaves out the lines that are shorter than a pixel or so, which would leave gaps where a vessel was slow. Postdoc turns that off for the GeoJSON sources of timeline layers. For a source of short lines that isn't on a timeline, set tolerance: 0 on it yourself.
Several markers
When several vessels share a timeline, each can have a marker of its own, which follows the features that are its own:
timeline:
layers: [tracks]
marker:
- { where: { drone: SD1030 }, label: SD1030, color: '#ffb000', side: left }
- { where: { drone: SD1033 }, label: SD1033, color: '#ff7ac1' }| Key | What it sets |
|---|---|
where |
The properties that the marker's features have, and their values. Without it, the marker follows every feature of its source. |
source |
The id of the GeoJSON source that the marker follows. By default, that of the first timeline layer. |
label |
A name beside the marker |
side |
The side of the marker that the label is on: left, right, top or bottom. On the right by default. Give the markers of vessels that sail together different sides, so their labels don't cover each other. |
color |
The colour of the marker. By default, --storymap-marker. |
The markers move on one clock. Each is at the end of its own latest feature, and stays at the end of its track when the others go on.
legend
legend:
title: Sea surface temperature, °C
layer: temperature
stops:
- [25.5, '#fff3b2']
- [30, '#b5174b']| Key | What it sets |
|---|---|
title |
A line above the colours. It can have line breaks, and {date|date} in it shows the step's date, for the legend of a dated source. |
stops |
A colour ramp: values and their colours, from the lowest to the highest. Each colour is drawn where its value lies between the two ends. |
scale |
log places each colour by the logarithm of its value, for what is measured over orders of magnitude, such as chlorophyll. linear by default. |
items |
A list of colours and what they stand for: { label: Moorings, color: '#1b1f24' } |
layer |
The id of the layer that the legend shows with. Without it, the legend shows with every step. |
For several legends, give a list of them. They're at the bottom right of the map, or in a row at the top of a narrow floating one, and a step's view leaves room for them.
popups
popups:
track: "{time|datetime} UTC\n{temperature|2} °C"Each key is the id of a layer, and its value the text to show for the feature under the pointer, or under a tap. In the text:
| Placeholder | Shows |
|---|---|
{name} |
The property as it is |
{time|date} |
A date, such as Jun 30, 2023 |
{time|datetime} |
A date and a time. Both are in UTC, in the language of the page. |
{depth|1} |
A number with that many decimals |
A property that the feature doesn't have shows as a dash. The text is shown as text, so the properties of a feature can't add markup. A layer that a step hides has no popup.
Dated sources
Some maps come one for each day, such as a satellite's picture of the sea. Put {date} in the address of such a source, in its tiles, its url or its data, and each step shows it for its own day:
sources:
sea-temperature:
type: raster
tiles: ['https://tiles.example.org/sst/{date}/{z}/{x}/{y}.png']
tileSize: 256
layers:
- { id: sea-temperature, type: raster, source: sea-temperature }
legend:
title: "Sea surface temperature, °C\n{date|date}"
layer: sea-temperature### On the equator {until="2023-07-17"}
### Two months later {until="2023-09-12"}
### The whole voyage {date="2023-11-05"}The day is the step's date, written as 2023-07-17, or else the day of its until, so a track and the sea under it move through time together. A step with neither keeps the date of the step before it, and the steps before the first date have that one.
When the date changes, the new day's raster is drawn over the old one, which stays until the new tiles have loaded, so one day fades into the next. Layers of other kinds change at once.
controls
controls:
compass: true
scale: nautical| Key | What it sets |
|---|---|
zoom |
The zoom buttons. On unless it's false. |
compass |
A button that shows where north is and how far the map is tilted. Pressing it puts north back up. |
scale |
A scale bar: true or metric for kilometres, imperial for miles, nautical for nautical miles. It's hidden while a globe is seen whole, where no one length is right. |
Settings for the whole site
The settings every storymap starts with go in the storymap section of postdoc.config.js, so a story only writes what is its own. This is where the base map usually belongs:
export default {
storymap: {
style: {
light: '/map-styles/emodnet-bathymetry.json',
dark: '/map-styles/emodnet-bathymetry-dark.json'
},
controls: { scale: true }
}
};Any map setting can go there. A storymap's own settings replace them key by key: one that sets its own controls gets those, and still takes the style from the configuration.
Styling
A theme styles storymaps with these custom properties, set on .storymap or on anything around it:
| Property | What it sets |
|---|---|
--storymap-sticky-top |
How far from the top of the window the map stays, such as under a sticky header |
--storymap-bottom-gap |
The room under a floating map |
--storymap-radius |
The corners of the map and of the floating steps |
--storymap-accent |
The edge of the active step, and the focus ring of the map |
--storymap-border |
The edge of the other steps |
--storymap-step-width |
The width of the floating steps |
--storymap-steps-inset |
The room beside the floating steps |
--storymap-panel-background and --storymap-panel-color |
The colours of the floating steps, the legends, the popups and the labels of markers |
--storymap-marker |
The colour of a timeline's markers, apart from those that set their own |
--storymap-figure-width |
The most that a figure is wide. 46rem by default. |
--storymap-sky |
What shows around a globe |
These classes are there to style as well:
| Class | Where |
|---|---|
.storymap |
The storymap, with .has-map once its map or its pictures are in place, .has-pictures, .has-figures, .is-floating and .is-globe |
.storymap-map |
The map, or the pictures |
.storymap-step |
A step, with .is-active while the map shows it |
.storymap-legend, .storymap-popup |
The legends and the popup |
.storymap-marker, .storymap-marker-label |
A marker of the timeline, and its label |
.storymap-figure-panel, .storymap-figure |
The panel that a step's figure shows in, and the picture |