Story pages

Page content:

A story page tells a story on a page of its own, like a magazine feature. Its storymaps fill the window, with the steps as cards that scroll over the map, and the text between them reads in a column.

See one: a saildrone in the tropical Pacific (new tab)

Make one

A story page is a layout of the default theme, which a page picks in its front matter:

docs/stories/voyage.mdmd
---
title: The voyage
description: Ten days from Honolulu to the equator.
layout: story
---

# The voyage

The cover: this heading and the paragraph after it.

## Setting out

Text reads in a column.

::: storymap
```yaml
sources:
  track: { type: geojson, data: /data/track.geojson }
layers:
  - { id: track, type: line, source: track }
```

### Leaving port {center="-157.86,21.3" zoom=9}

The ship left Honolulu on 3 March.
:::

## The crossing

More text, and more storymaps if the story has them.

The page has a top bar with the site's name, the story's title and a switch between light and dark. Each ## heading starts a chapter. The chapters are listed in the top bar, which shows the one the reader is in.

Storymaps on a story page float unless their settings say layout: docked.

Around the maps

Between its storymaps, a story is ordinary Markdown: text, pictures, quotes, tables, code. Markdown takes HTML as well, which is how the saildrone story has a picture with a caption, and a row of numbers under its cover:

docs/stories/sd1030.mdhtml
<figure>
  <img src="/assets/sd1079-deployment.jpg" alt="An orange saildrone floats on calm water, under a rainbow." />
  <figcaption>SD1079 deploys in Hawaiʻi. Photo courtesy of Saildrone.</figcaption>
</figure>

<dl class="story-stats">
  <div><dt>Days on the track</dt><dd>144</dd></div>
  <div><dt>Positions logged</dt><dd>557</dd></div>
</dl>

The theme styles what Markdown makes. Style what you add yourself in a stylesheet of your own.

Make it yours

  • Fonts and stylesheets. An include named story_head.ejs goes in the <head> of every story page. Link your stylesheet and load your fonts there.
  • Colours. The page takes its colours from custom properties on .storyPage, which your stylesheet can set for each colour scheme: --story-background, --story-text, --story-muted, --story-border, --story-accent and --story-link. The storymaps have their own.
  • The page itself. Copy the theme's layouts/story.ejs into your layouts folder and change it. This site does, to add its own stylesheets and scripts.
postdoc/includes/story_head.ejshtml
<link rel="stylesheet" href="/css/stories.css" />

Give the stylesheet a name of its own. A file named css/story.css in your public folder would take the place of the theme's.

postdoc/public/css/stories.csscss
.storyPage {
  --story-accent: #0b6e4f;
  --story-link: #0b6e4f;
}

/* The steps over the map, as frosted glass. */
.storyPage .storymap.is-floating .storymap-step {
  border-radius: 14px;
  backdrop-filter: blur(14px);
}

The same story in a page

A storymap doesn't belong to its page. The saildrone story is told twice with the same map: docked in a page of this guide, and floating on its story page. Only the text around the map differs, and the layout that the page gives it.

Edit this page on GitHub