Reference
Syntax guide
This is the language reference. Use it when you need to look up how a specific feature is written. If you are brand new to Downstage, start with the FAQ for an overview, then come back here for the syntax.
Each section below covers one feature — document structure, title pages, dialogue, and so on. Sections that need extra context call it out inline.
1
Document Structure
A Downstage document has an optional title page and then the play body. The
body can contain a character list, acts, scenes, prose sections, dialogue,
songs, comments, and page breaks. Multi-play compilations use one
top-level # per play; numbering and Dramatis Personae are scoped per play,
not per file.
A minimal file is valid. No title page or headings required.
ALICE
Hello, world!A full play opens with a # heading. Metadata, Dramatis Personae, and acts/scenes are scoped to that section.
# The Last Curtain Call
Author: Eleanor Vance
## Dramatis Personae
MARGARET - An aging actress
JAMES - Her son
## ACT I
### SCENE 1
MARGARET
They used to fill every seat.A compilation gathers multiple plays in a single file. Each play is its own # section, with independent metadata, Dramatis Personae, and act numbering. A leading # section that has metadata but no body acts as the collection's title page.
# Short Plays
Author: Various
# Waiting
Author: A. Writer
## SCENE 1
ALICE
Is this it?
# Departure
Author: B. Writer
## SCENE 1
BOB
It's time.2
Title Page
Title-page metadata lives directly under a top-level # heading as
Key: Value pairs. Any key name is accepted. Indented lines continue the
previous value.
The # heading owns the metadata scope. The metadata block ends at the first
blank line, the next heading, a page break, or a non-indented line that is not
a metadata pair.
# The Last Curtain Call
Subtitle: A Drama in Two Acts
Author: Eleanor Vance
Date: 2025
Notes: Inspired by true events
and several missed cues.Title: entry, it overrides the # heading text in rendered output — handy when your working file name and the published title differ.
3
Dramatis Personae
The character list is a dedicated section. Entries can include descriptions, aliases, and optional subgroup headings.
# The Play
## Dramatis Personae
MARGARET - An aging actress
JAMES/JIM - Her estranged son
### The Crew
STAGEHAND 1 - Quiet, efficient
STAGEHAND 2 - Nervous and chattyNAMEorNAME - Descriptionare both valid.NAME/ALIASdefines a shorter dialogue alias inline.
## Dramatis Personae, ## Cast of Characters, and ## Characters all start the same section type inside the enclosing play.
4
Acts and Scenes
If you do not need acts or scenes, skip them. Downstage does not force a structure you are not using.
Acts are usually written as ## headings.
## ACT I
## ACT 2
## ACT: FinaleScenes are usually written as ### headings when they belong to an act.
## ACT I
### SCENE 1
### SCENE 1: The Palace
### A Bare StageOne-acts and short-form pieces often skip acts entirely. Write scenes as ## headings and Downstage treats them as direct children of the play.
## SCENE 1: Opening
ALICE
Hello.
## SCENE 2: Closing
ALICE
Goodbye.5
Dialogue
Dialogue starts with a character name on its own line, followed by an optional parenthetical and one or more speech lines.
Character names are uppercase and may contain spaces, punctuation like periods and apostrophes, digits, and slashes for alias-aware names.
HAMLET
(aside)
To be, or not to be, that is the question.
MARGARET
They used to fill every seat, you know.
Every last one.6
Dual Dialogue
To mark simultaneous speech, add ^ to the end of the second character cue.
The first cue stays normal.
The ^ must be the last character on the line, preceded by a space, and only
the second cue gets the marker. Forced character cues also work, as in
@narrator ^. If there is no previous dialogue block to pair with, the cue is
treated as normal dialogue.
HORATIO
They're here.
HAMLET ^
Then let them come.7
Stage Directions
Stage directions can stand on their own or live inside dialogue.
Standalone stage directions start with >. Use >> for bold non-structural callouts inside scene flow.
> The lights dim.
>> Midwinter. The room has not been heated for days.Inline parentheticals inside dialogue stay part of the speech block.
HAMLET
To be (pause) or not to be.8
Verse
Indent dialogue lines by two or more spaces to preserve line breaks as verse.
Prose and verse can be mixed inside the same speech block.
MARGARET
To stand upon this stage once more,
to feel the boards beneath my feet,
to hear the hush before the roar,
to know this moment, bittersweet.9
Songs
Songs wrap a block of theatrical content between SONG and SONG END.
Numbering and titles are optional. The contents can include dialogue, verse, and stage directions.
SONG 1: The Stagehand's Lament
JIM
Under the lights we never stand,
behind the curtain, close at hand.
SONG END10
Inline Formatting
Inline formatting works in dialogue, verse, and stage directions.
*text*
Italic
**text**
Bold
***text***
Bold italic
_text_
Underline
~text~
Strikethrough
11
Comments and Page Breaks
These elements affect the working file and rendered pages differently.
Comments are ignored when rendering, so they will not appear in the PDF.
// A line comment
/* A block comment
spanning multiple lines */=== inserts a page break in rendered output.
### SCENE 1
===
### SCENE 212
Forced Elements
When the parser would otherwise classify a line incorrectly, force it.
@name forces a character cue.
@horatio
My lord, I came to see your father's funeral..Heading forces a structural heading.
.The Next Evening13
Complete Example
This excerpt shows how the pieces fit together in a real script.
For the exhaustive reference, read the full spec.
# The Last Curtain Call
Author: Eleanor Vance
Draft: First
## Dramatis Personae
MARGARET - An aging actress, once famous
JAMES/JIM - Her estranged son
CLAIRE - The new director
## ACT I
### SCENE 1
> The stage is bare except for a single chair.
MARGARET
(sitting in the chair)
They used to fill every seat, you know.
JAMES
Mother, the crew is waiting.