Stagistic syntax

01The core idea

Two things decide what every line is: where it sitsand 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, anUPPERCASEline is a character cue.
• Inside a speech, anUPPERCASEline 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, whilePASS ME THE SUGARinside 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!.

02Frontmatter

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, andcopyright. A credit always contains anauthorslist, even for one author. Draft dates useYYYY-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
---

03Acts & 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.

04Character 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: texton one line — but the editor always writes it back out stacked, with the cue on its own line.

JANE: I told you already.

05Asides

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.

06Lyrics

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

07Soft 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

08Stage directions

Any normal-case line at the start of a block is a stage direction. To mark the character performingthe 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. @MICHAELalone is a forced character cue;!@MICHAELis 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!textis 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

09Music

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 Nto 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

10The quoting rule

Double quotes delimit a literal name or title anywhere a space, period, or special character (@,/) would otherwise break parsing. A bare @Nametags 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\""

11Inline marks & notes

Emphasis carries over from Fountain:*italic*,**bold**,_underline_. A note in[[ double brackets ]]is included in exports by default.

*italic*  **bold**  _underline_

[[ a note to self ]]

12A 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 ]]

13Marker reference

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