Your first storymap
This page builds a small storymap from nothing: three harbours of Hawaiʻi on a map that moves from one to the next. It takes four steps, and the result is at the end.
1. Start a page
A storymap goes in any Markdown page. Make one, and start the dev server:
npx postdoc create page --name /guide/harbours
npm startThe command also writes a page test for it in test/pages. To keep the page out of builds while you write it, add --draft.
2. Write the steps
Put the story between ::: storymap and :::. Each heading starts a step, and the braces after it say where the map goes:
::: storymap
### Honolulu {center="-157.87,21.3" zoom=9}
Honolulu Harbor is on the south shore of Oʻahu.
### Kahului {center="-156.47,20.9" zoom=9}
Kahului Harbor is on the north shore of Maui.
### Hilo {center="-155.07,19.73" zoom=9}
Hilo Harbor is on the east side of the island of Hawaiʻi.
:::That's a storymap already. A base map appears beside the steps and flies from harbour to harbour as you scroll. center is a longitude and a latitude, in that order, and zoom is how close the map is.
3. Add your data
The map settings go first in the storymap, in a YAML block. sources holds your data and layers says how to draw it, both written as MapLibre takes them. Here the data is three points, written straight into the settings as GeoJSON, with a circle and a name for each:
::: storymap
```yaml
sources:
harbours:
type: geojson
data:
type: FeatureCollection
features:
- { type: Feature, properties: { name: Honolulu }, geometry: { type: Point, coordinates: [-157.87, 21.3] } }
- { type: Feature, properties: { name: Kahului }, geometry: { type: Point, coordinates: [-156.47, 20.9] } }
- { type: Feature, properties: { name: Hilo }, geometry: { type: Point, coordinates: [-155.07, 19.73] } }
layers:
- id: harbours
type: circle
source: harbours
paint: { circle-radius: 6, circle-color: '#ffffff', circle-stroke-width: 2.5, circle-stroke-color: '#1b1f24' }
- id: names
type: symbol
source: harbours
layout: { text-field: [get, name], text-font: ['Noto Sans Regular'], text-size: 13, text-anchor: left, text-offset: [1, 0] }
paint: { text-color: '#1b1f24', text-halo-color: '#ffffff', text-halo-width: 1.5 }
```
### Honolulu {center="-157.87,21.3" zoom=9}Data in a file works the same way. Put harbours.geojson in your public folder, under data/, and write data: /data/harbours.geojson.
Tip
A label needs a font that the base map has. The default base maps have Noto Sans Regular, Noto Sans Bold and Noto Sans Italic.
4. Show an area, and pick a layout
A step can fit an area instead of centring on a point. bounds is its west, south, east and north. A last step shows all three harbours at once:
### All three {bounds="-158.4,19.4,-154.6,21.8"}
From Honolulu to Hilo is about 340 km.The steps are docked beside the map. To have the map fill the storymap, with the steps as cards that scroll over it, add layout: floating to the settings.
The result
Honolulu
Honolulu Harbor is on the south shore of Oʻahu.
Kahului
Kahului Harbor is on the north shore of Maui.
Hilo
Hilo Harbor is on the east side of the island of Hawaiʻi.
All three
From Honolulu to Hilo is about 340 km.
The base map here is the one this site sets for all its storymaps, a chart of the depth of the sea. Yours is a street map until you choose another.
Where to go from here
- Pictures instead of a map: give each step an
image, as the Postdoc story does. - A page of its own, with the map filling the window: Story pages.
- A track that draws itself, colours that follow the data, a legend, a globe: Mapping a mission.
- Every attribute and setting: the reference.