Start Here

What is Downstage?

Downstage is a plain-text format for stage plays with a few small tools around it. You write one .ds file, and the same file can be checked for mistakes, rendered to PDF, turned into HTML, and edited with writing-aware assistance in supported editors.

It stays readable

The source still looks like a script, not a word processor export or a wall of tags.

It understands theatre

Acts, scenes, cues, stage directions, character lists, songs, and verse are native ideas.

It gives you manuscripts

You can render a manuscript, preview as HTML, and use editor support without rewriting the document.

It keeps revision history clean

Plain text makes it easy to compare drafts, review changes, and keep a readable history in Git.

Plain-English version: if you want a dead-simple, intuitive format but still want beautifully-rendered manuscript and acting edition PDFs and helpful tooling, Downstage is for you.

Back to top

File Format

What is a .ds file?

A .ds file is a plain text file. Open it in any text editor — even Notepad or TextEdit — and you can read and change your script directly. There is no proprietary document format, no hidden layout metadata, and no vendor lock-in.

Downstage tools such as the Web Editor read that same text file and turn it into a beautifully rendered manuscript or acting edition PDF, so you never have to fuss with page layout yourself.

Back to top

Why

Why use this instead of a word processor?

If word processors keep nudging you into layout work, and screenwriting-focused text formats such as Fountain are not quite the right shape, Downstage gives you a plain-text workflow built for plays.

Less formatting drift

You are writing the play, not wrestling with invisible spacing rules and style menus.

More durable files

Plain text travels well, works with version history, and does not trap your script in one app.

Theatre-first, not screenplay-first

Downstage is built for stage writing, so common playwriting structures do not feel bolted on.

Portable

It works on macOS, Windows, Linux, and in the Web Editor without locking your script to one device.

Back to top

How

Try a tiny script

You do not need the whole spec before you begin. Start with a tiny script, then keep the docs open for the parts you actually need.

1

Use the Web Editor

If you want the shortest path to a real script page, start in the Web Editor. It runs in the browser and gives you live preview plus PDF export.

downstage 
# My Play
Author: You

JANE
I finally started the draft.

Paste that into the Web Editor, make a small change, then export a PDF.

Start Writing
2

Use Visual Studio Code

If you already write code in Visual Studio Code, install the Downstage extension and stay in the editor you know. Not a developer? You can skip this one; the Web Editor has everything you need.

first session 
1. Install the Downstage extension
2. Open or create a .ds file
3. Draft a scene
4. Use live preview or render to PDF
Get Extension
3

Use the command line

If you prefer terminal workflows, install Downstage and render from the command line.

shell 
brew tap jscaltreto/tap
brew install downstage

# Go users can install with:
# go install github.com/jscaltreto/downstage@latest

downstage render my-play.ds
New here? Use Start Here if you want a quick overview of the Web Editor, plus the Visual Studio Code extension and command-line tools for folks who want them, before you dig into the syntax guide.

Back to top

First Pass

From draft to PDF

A typical workflow is simple: write in plain text, preview when you want feedback, and export when you want pages.

Draft

Write cues, dialogue, headings, and stage directions in a single file.

Preview

Use the Web Editor's live preview to see your pages update as you draft.

Export

Export a PDF manuscript or acting edition from the same draft when it is ready to read or share.

Back to top

Acknowledgements

Inspiration and prior art

Downstage is inspired by Fountain, which showed the value of a readable plaintext format for scripts, and by the archived TheatreScript specification, which explored theatre-native structure directly.

This project builds on those ideas with a more complete toolchain for stage writing: rendering, validation, and editor support around the same readable source format.

Downstage was created by Jake Scaltreto, a software developer and playwright who wanted to stop fighting a word processor and focus on writing plays.

Back to top