Stagistic syntax

01 The core idea

Two things decide what every line is: where it sits and its letter case. A blank line ends a speech, so the parser knows whether it is waiting for a new character or reading the lines under one.

• Right after a blank line, an UPPERCASE line is a character cue.
• Inside a speech, an UPPERCASE line is lyrics (sung); a normal-case line is dialogue (spoken).
• A line in normal case at the start of a block is a stage direction.

So ANNA on its own line after a blank line is a cue, while PASS ME THE SUGAR inside a speech is a lyric — identical casing, the position decides. To shout, use bold (**Stop!**); caps inside a speech always mean singing.

To make an uppercase line a stage direction, force it with !.

02 Frontmatter

Optional. If the file opens with a --- line, everything up to the next --- is a YAML metadata block. The script begins after it.

The supported fields mirror the title page: title, subtitle, credits, source, draftDate, contact, and copyright. A credit always contains an authors list, even for one author. Draft dates use YYYY-MM-DD.

---
title: When Night Falls
subtitle: A musical in two acts
credits:
  - credit: Book
    authors:
      - Jane Smith
  - credit: Music
    authors:
      - Peter Gray
  - credit: Lyrics
    authors:
      - Jane Smith
      - Alex Green
source: Based on the novel by Sam Gray
draftDate: 2026-07-01
contact: jane@example.com
copyright: © 2026 Jane Smith
---

03 Acts & scenes

Markdown-style headings: # is an act, ## is a scene. The text after the marker is free — location, time, anything; the editor handles numbering.

Scenes are the base unit; acts are an optional layer above. If a script has no ## anywhere, a # is treated as a scene — so a one-act play just uses # per scene.

# Act One

## 1 — A garden. Dusk.

04 Character cues & dialogue

A character cue is the name in caps on its own line; the lines below it, up to the next blank line, are that character's speech.

PETER
(from the doorway)
Sorry I'm late.

ANNA
It's fine. I was waiting.

For two characters speaking or singing the same words at once, join the names with / (spaces optional). The shared content follows once.

ANNA / PETER
AND THE WORLD WILL STOP

As a convenience the parser also accepts inline dialogue — NAME: text on one line — but the editor always writes it back out stacked, with the cue on its own line.

JANE: I told you already.

05 Asides

A short parenthetical delivery note inside a speech — (quietly), (to himself). It can sit on the name line, on its own line under the cue, or between lines, and may appear more than once in a speech.

ANNA
(quietly)
You shouldn't have come.
(she turns away)
Not tonight.

A (...) line at the start of a block — not inside a speech — is a parenthetical stage direction instead. Position tells them apart.

06 Lyrics

Inside a speech, an uppercase line is sung. Set the section level with leading tabs: no tab is the A-section, one tab the B-section, two the C-section, and so on.

ANNA
WHEN NIGHT FALLS AND THE LIGHTS GO DOWN
	AND I'LL BE STANDING HERE

07 Soft breaks

A real blank line ends a speech. For a breathing gap inside one — between verses of a song, or in a long spoken passage — use a ~ alone on its line. It adds the gap without starting a new character.

PETER
FIRST LINE OF THE SONG
SECOND LINE OF THE SONG
~
A LATER LINE — STILL PETER, NOT A NEW CHARACTER

08 Stage directions

Any normal-case line at the start of a block is a stage direction. To mark the character performing the action, tag them with @ — it is capitalised and linked to the cast. Only the actor is tagged, never the recipient, so it is always explicit.

Anna stands at the window. @Peter enters quietly from behind.

The force prefix also resolves a tag-only stage direction. @MICHAEL alone is a forced character cue; !@MICHAEL is a stage direction containing one character tag. Write !! to preserve a literal leading exclamation point.

!ALL LIGHTS SNAP OUT

!@MICHAEL

Inside a speech there is no implicit form for a stage direction — normal case is always dialogue, UPPERCASE is always lyrics — so !text is the only way to write one there. Like a soft break, it does not end the speech.

MICHAEL
!He pauses, listening.
AND THEN HE SINGS AGAIN

09 Music

A music item marks a song or instrumental passage for actors and directors. Write it inline inside a stage direction: @@music N "title" to start it and @@out N to end it. The number ties the two together. With no @@out, the music runs to the end of the scene.

The lights slowly fade. @@music 1 "When Night Falls"

ANNA
WHEN NIGHT FALLS AND THE LIGHTS GO DOWN

The lights come up. @@out 1

10 The quoting rule

Double quotes delimit a literal name or title anywhere a space, period, or special character (@, /) would otherwise break parsing. A bare @Name tags only one word — once a name has a space or a dot, quote it.

Inside quotes, use \" for a literal double quote and \\ for a literal backslash.

"Mrs. Washington"
@"Mrs. Washington"
@@music 1 "She Said \"Yes\""

11 Inline marks & notes

Emphasis carries over from Fountain: *italic*, **bold**, _underline_. A note in [[ double brackets ]] is for you only — it never prints.

*italic*  **bold**  _underline_

[[ a note to self — never printed ]]

12 A full example

Everything together: frontmatter, an act and scene, a stage direction with a tagged character, spoken dialogue, a sung number bracketed by music markers, unison singing, and an author note.

---
title: When Night Falls
credits:
  - credit: Book
    authors:
      - Jane Smith
  - credit: Music
    authors:
      - Peter Gray
draftDate: 2026-07-01
---

# Act One

## 1 — A garden. Dusk.

Anna stands at the window. @Peter enters quietly from behind.

PETER
(from the doorway)
Sorry I'm late.

ANNA
It's fine. I was waiting.

The lights slowly fade. @@music 1 "When Night Falls"

ANNA
WHEN NIGHT FALLS AND THE LIGHTS GO DOWN
	AND I'LL BE STANDING HERE

PETER
SO I'LL COME CLOSER

ANNA / PETER
AND THE WORLD WILL STOP

The lights come up. @@out 1

[[ still need to reconsider the transition into scene 2 ]]

13 Marker reference

The complete set of explicit markers. Everything else is implicit, by position and letter case.