docs(guides): add story-authoring guide; list it in the README index
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Claude Opus 5
@@ -27,7 +27,7 @@ Two git repos:
|
|||||||
| `tests/` | Playwright suite — see [`docs/reference/testing.md`](docs/reference/testing.md) |
|
| `tests/` | Playwright suite — see [`docs/reference/testing.md`](docs/reference/testing.md) |
|
||||||
| `php/` | Local PHP ini overrides |
|
| `php/` | Local PHP ini overrides |
|
||||||
| `docs/` | All project documentation — start at [`docs/README.md`](docs/README.md) |
|
| `docs/` | All project documentation — start at [`docs/README.md`](docs/README.md) |
|
||||||
| `docs/guides/` | Operational how-tos (posting, GPX, trip switching, setup, deploy cycle) |
|
| `docs/guides/` | Operational how-tos (posting, story authoring, GPX, trip switching, setup, deploy cycle) |
|
||||||
| `docs/reference/` | Stable facts: architecture, design system, testing |
|
| `docs/reference/` | Stable facts: architecture, design system, testing |
|
||||||
| `docs/solutions/` | Write-ups of bugs and workflow traps already hit, with YAML frontmatter (`module`, `tags`, `problem_type`) |
|
| `docs/solutions/` | Write-ups of bugs and workflow traps already hit, with YAML frontmatter (`module`, `tags`, `problem_type`) |
|
||||||
| `docs/working/` | Specs, plans, backlog, QA — work in flight |
|
| `docs/working/` | Specs, plans, backlog, QA — work in flight |
|
||||||
|
|||||||
@@ -0,0 +1,228 @@
|
|||||||
|
# Writing a Story
|
||||||
|
|
||||||
|
A Story is a long-form, hand-crafted piece with an immersive layout — distinct from an Entry, which is a quick dated post from the road (see [`CONCEPTS.md`](../../CONCEPTS.md)). Stories get a Ken Burns hero, scroll-driven sections, galleries and pull quotes.
|
||||||
|
|
||||||
|
The admin editor gives you a **plain markdown textarea** for the body. There is no block picker — the layout vocabulary is a set of shortcodes you type by hand. This guide is that vocabulary; the story edit form also carries a condensed copy of it on its **Blocks** tab, so you don't need this file open while writing.
|
||||||
|
|
||||||
|
Admin lives at **`/admin`** (the plugin slug is `admin2`, but the route is `/admin`). A story's edit URL looks like `/admin/pages/edit/trips/<trip>/stories/<slug>`.
|
||||||
|
|
||||||
|
Stories live at:
|
||||||
|
|
||||||
|
```
|
||||||
|
user/pages/01.trips/<trip>/04.stories/<slug>/story.md
|
||||||
|
```
|
||||||
|
|
||||||
|
`04.stories/stories.md` is a `routable: false` container — its children are aggregated onto the trip page. There is no standalone `/stories` view; don't create one.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. Create the page
|
||||||
|
|
||||||
|
1. Admin → **Pages** → add a page under the trip's **Stories** folder
|
||||||
|
2. Set page template to **story** — this loads [`user/themes/intotheeast/blueprints/story.yaml`](../../user/themes/intotheeast/blueprints/story.yaml). You get the story-specific **Content / Blocks / Location / Publishing** tabs plus the inherited **Options / Advanced / Security** tabs
|
||||||
|
3. Fill in Title and Start Date (both required)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. Upload the images first
|
||||||
|
|
||||||
|
Upload every image the story needs via the **Images** field at the bottom of the Content tab, before writing the body.
|
||||||
|
|
||||||
|
> There is no separate *Media* tab — the uploader is a field on the Content tab, labelled **Images**. It arrives via inheritance: `story.yaml` declares `'@extends': {type: default, context: blueprints://pages}`, which merges in Grav's default page form. `story.yaml` and `trip.yaml` did not originally extend it, so neither form could upload anything, which is why the demo story images had to be placed on the filesystem. Both now inherit, matching [`entry.yaml`](../../user/themes/intotheeast/blueprints/entry.yaml). `home.yaml` is still standalone, deliberately — the home page has no per-page media.
|
||||||
|
|
||||||
|
Every shortcode refers to images by **bare filename** — the `story-blocks` plugin prefixes the page URL at render time ([`story-blocks.php:22`](../../user/plugins/story-blocks/story-blocks.php)), so you write:
|
||||||
|
|
||||||
|
```
|
||||||
|
image="photo-1.jpg" ✅
|
||||||
|
image="/images/photo-1.jpg" ❌ don't path it
|
||||||
|
```
|
||||||
|
|
||||||
|
The demo stories use a `hero.jpg` / `photo-1.jpg` / `photo-2.jpg` naming convention. Worth copying — it keeps the shortcodes readable.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. Frontmatter fields
|
||||||
|
|
||||||
|
All of these come from the form tabs, so you rarely type them by hand. Listed here because the body shortcodes are *not* the whole story — the hero in particular is frontmatter, not a tag.
|
||||||
|
|
||||||
|
| Field | Tab | Notes |
|
||||||
|
|---|---|---|
|
||||||
|
| `title` | Content | Required |
|
||||||
|
| `date` | Content | Required. Start date |
|
||||||
|
| `end_date` | Content | Optional — leave blank for a single-day story |
|
||||||
|
| `hero_image` | Content | **The hero. Filename only**, from the Images field. Missing → grey placeholder, story still renders |
|
||||||
|
| `hero_alt` | Content | Falls back to the title if empty |
|
||||||
|
| `location_name`, `location_country` | Location | Shown in the hero meta line and the opener |
|
||||||
|
| `lat`, `lng` | Location | Decimal degrees — places the story marker on the trip map |
|
||||||
|
| `transport_mode` | Location | walking / bicycle / bus / train / car |
|
||||||
|
| `force_connect` | Location | Always draw a connector line from the previous marker |
|
||||||
|
| `published` | Options | Grav's standard toggle, from the inherited form |
|
||||||
|
| `featured` | Publishing | Show as a homepage highlight when not travelling |
|
||||||
|
|
||||||
|
The Ken Burns pan on the hero is automatic — no parameter for it.
|
||||||
|
|
||||||
|
If you hand-write frontmatter, use `date: '2026-09-03'`. Admin2 saves its own serialization (`29-07-2026 19:51`); both parse fine.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. The body: six shortcodes
|
||||||
|
|
||||||
|
Defined in [`user/plugins/story-blocks/shortcodes/`](../../user/plugins/story-blocks/shortcodes/). Plain prose between them renders as a normal reading column — you don't need a shortcode to write paragraphs.
|
||||||
|
|
||||||
|
### Wrapping tags
|
||||||
|
|
||||||
|
**`scrolly-section`** — text panels scroll over a pinned, slowly panning image. The centrepiece block.
|
||||||
|
|
||||||
|
```
|
||||||
|
[scrolly-section image="hero.jpg" alt="Description of the image" caption="Optional caption"]
|
||||||
|
The first panel. Scrolls into view over the image.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
The second panel. A markdown `---` starts a new panel.
|
||||||
|
[/scrolly-section]
|
||||||
|
```
|
||||||
|
|
||||||
|
Panels are split on the `<hr>` that `---` produces ([`story.html.twig:234`](../../user/themes/intotheeast/templates/story.html.twig)). `caption` is optional. Under `prefers-reduced-motion` all panels render active with no pinning.
|
||||||
|
|
||||||
|
**`pull-quote`** — large extracted quote, optionally over a background image.
|
||||||
|
|
||||||
|
```
|
||||||
|
[pull-quote image="photo-1.jpg" alt="Description of the image"]
|
||||||
|
The quote itself. Markdown works in here.
|
||||||
|
[/pull-quote]
|
||||||
|
```
|
||||||
|
|
||||||
|
Drop `image`/`alt` entirely for the plain no-image variant.
|
||||||
|
|
||||||
|
### Self-closing tags
|
||||||
|
|
||||||
|
Note the ` /]` — these take no content.
|
||||||
|
|
||||||
|
**`chapter-break`** — full-width section transition over a background image.
|
||||||
|
|
||||||
|
```
|
||||||
|
[chapter-break image="photo-1.jpg" title="After Dark" number="II" alt="Description" /]
|
||||||
|
```
|
||||||
|
|
||||||
|
`number` is optional; the demo stories use roman numerals.
|
||||||
|
|
||||||
|
**`snap-gallery`** — swipeable multi-image carousel with dots.
|
||||||
|
|
||||||
|
```
|
||||||
|
[snap-gallery images="hero.jpg,photo-1.jpg" captions="First caption,Second caption" alts="First alt,Second alt" /]
|
||||||
|
```
|
||||||
|
|
||||||
|
⚠️ See the comma gotcha below.
|
||||||
|
|
||||||
|
**`full-bleed`** — single image edge-to-edge, as a visual pause.
|
||||||
|
|
||||||
|
```
|
||||||
|
[full-bleed image="photo-2.jpg" alt="Description" caption="Optional" credit="Optional" /]
|
||||||
|
```
|
||||||
|
|
||||||
|
**`image-caption`** — photo at a chosen width with caption beneath.
|
||||||
|
|
||||||
|
```
|
||||||
|
[image-caption image="photo-2.jpg" alt="Description" caption="Optional" credit="Optional" width="column" /]
|
||||||
|
```
|
||||||
|
|
||||||
|
`width` accepts `column` (default), `full`, `bleed`. Anything else falls back to `column`.
|
||||||
|
|
||||||
|
`full-bleed` and `image-caption` are implemented but not yet used by any story — the demos only exercise the other four.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Gotchas
|
||||||
|
|
||||||
|
### snap-gallery splits on commas — captions cannot contain them
|
||||||
|
|
||||||
|
`images`, `captions` and `alts` are each split on `,` and zipped by index. **A comma inside a caption shifts every caption after it.**
|
||||||
|
|
||||||
|
This is already live in the demo content. `04.stories/04.florence-without-a-map/story.md` has:
|
||||||
|
|
||||||
|
```
|
||||||
|
captions="The Arno at noon — greener than expected, the bridges older than you remember,Via dei Servi: …"
|
||||||
|
```
|
||||||
|
|
||||||
|
Two images, but three comma-separated pieces — so slide 1 gets "The Arno at noon — greener than expected", slide 2 gets " the bridges older than you remember", and the Via dei Servi text is silently dropped.
|
||||||
|
|
||||||
|
Use em dashes or semicolons in gallery captions. There is no escaping mechanism.
|
||||||
|
|
||||||
|
### Self-closing tags need the space before `/]`
|
||||||
|
|
||||||
|
`[chapter-break … /]` — not `[chapter-break …/]` or `[chapter-break …]`.
|
||||||
|
|
||||||
|
### A typo'd shortcode fails silently
|
||||||
|
|
||||||
|
An unrecognised tag name or a malformed parameter list renders as literal text or vanishes — no error, no warning. Preview the page after every block; there is no in-editor validation.
|
||||||
|
|
||||||
|
### `---` outside a scrolly-section is just a horizontal rule
|
||||||
|
|
||||||
|
The panel-splitting behaviour only applies *inside* `[scrolly-section]`.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Worked example
|
||||||
|
|
||||||
|
The best reference to copy from is [`user/pages/01.trips/italy-2026-demo/04.stories/01.sorano-rock-and-time/story.md`](../../user/pages/01.trips/italy-2026-demo/04.stories/01.sorano-rock-and-time/story.md) — it combines `scrolly-section`, `chapter-break` and `pull-quote` in one story.
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
---
|
||||||
|
title: 'Sorano: Rock and Time'
|
||||||
|
date: '2026-09-03'
|
||||||
|
location_name: Sorano
|
||||||
|
location_country: Italy
|
||||||
|
lat: 42.683
|
||||||
|
lng: 11.715
|
||||||
|
hero_image: hero.jpg
|
||||||
|
hero_alt: Medieval town of Sorano clinging to pale tufa cliffs at dusk
|
||||||
|
published: true
|
||||||
|
---
|
||||||
|
|
||||||
|
Opening prose. Renders as a normal reading column.
|
||||||
|
|
||||||
|
[scrolly-section image="hero.jpg" alt="Sorano seen from the approach road" caption="Sorano — tufa cliff town"]
|
||||||
|
First panel over the pinned image.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
Second panel.
|
||||||
|
[/scrolly-section]
|
||||||
|
|
||||||
|
More prose between blocks.
|
||||||
|
|
||||||
|
[chapter-break image="photo-1.jpg" title="After Dark" number="II" alt="Narrow medieval alley at dusk" /]
|
||||||
|
|
||||||
|
[pull-quote image="photo-1.jpg" alt="Stone alley lit by a single lantern"]
|
||||||
|
A town built on rock, carved from rock, returning slowly to rock.
|
||||||
|
[/pull-quote]
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Publish
|
||||||
|
|
||||||
|
1. Set **Published** on the Publishing tab
|
||||||
|
2. Optionally set **Featured highlight** to surface it on the homepage between trips
|
||||||
|
3. Push the content:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
make content-push
|
||||||
|
```
|
||||||
|
|
||||||
|
That commits and pushes `user/` to Gitea, which triggers the production pull. See [`deploy-cycle.md`](deploy-cycle.md).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## The Blocks tab
|
||||||
|
|
||||||
|
The story edit form has a **Blocks** tab holding a paste-ready example of each shortcode plus the comma warning. It's built from `type: spacer` fields in `story.yaml`, whose `text` admin2 renders as HTML (confirmed against admin2 2.0.12 — see its CHANGELOG entry for issue #91).
|
||||||
|
|
||||||
|
If you edit those fields, note two things: the `text` values are YAML double-quoted scalars, so HTML attribute quotes must be escaped (`\"`) — and `<h4>` is flattened by admin2's CSS reset, which is why the headings use `<strong>` in a styled `<p>` instead. Long `<pre>` content needs `white-space:pre-wrap`, or it overflows underneath the Page Info sidebar.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Why it's a raw textarea
|
||||||
|
|
||||||
|
The admin2 story editor is a plain markdown field by design-so-far, not by limitation. Background and the options considered: [`docs/research/story-editing.md`](../research/story-editing.md). Note that its conclusion that admin2 cannot host a custom editor is **out of date** — admin-next ships a plugin field-component surface (`admin-next/fields/{type}.js` + `onApiBlueprintResolved`) that the installed api 1.0.9 / admin2 2.0.12 support. Nobody has built it yet.
|
||||||
Reference in New Issue
Block a user