Your first storymap

Page content:

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:

sh
npx postdoc create page --name /guide/harbours
npm start

The 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:

docs/guide/harbours.mdmd
::: 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:

docs/guide/harbours.mdmd
::: 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:

md
### 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.

Edit this page on GitHub