Letters

Letters

Letters turn chapter prose into a styled sheet of correspondence. By default, readers see the letter paper immediately. Add envelope when readers should first see a closed envelope and choose whether to open it.

For fictional email with From, optional To, and Subject details, use Email Cards.

A letter is part of the story page. It does not send a message, change Game State, or add a saved game step.

Preview

This signed letter appears directly on themed paper:

{letter signed "Mara"}
Dear Rowan,

The spare key is beneath the third planter.

{endletter}

The paper is visible immediately, and Mara's name appears at the end in flowing handwriting.

This second letter begins as a closed envelope:

{letter envelope "Open Mara's letter" signed "Mara"}
Dear Rowan,

The spare key is beneath the third planter.

{endletter}

The reader sees the quoted label on the envelope with Open. Selecting the envelope displays the signed paper and changes the control to Close.

Copy the basic syntax

Write {letter}, add a non-empty body, and close the letter with {endletter}:

{letter}
The brass key is beneath the third planter.
{endletter}

Without any options, the paper is visible as soon as the reader reaches it. You do not need to write a label for directly displayed paper; CHYOA supplies its accessible Letter name automatically.

Put the opening and closing tags on their own lines.

Add a signature

Add signed "Name" when the paper should end with a handwritten name:

{letter signed "Mara"}
Dear Rowan,

Meet me beneath the clock tower.
{endletter}

The signature is fixed authored text. Use matching straight single or double quotation marks, and do not put reader values, Game State values, conditional tags, or other chapter syntax inside it. Put changing information in the letter body instead.

Format the letter body

The body supports ordinary Markdown, including paragraphs, emphasis, lists, and links. It may also use supported reader values, Game State values, conditional text, and compatible chapter elements.

For example:

{letter signed "Mara"}
Dear **{reader:name}**,

Take the [marked route](https://example.com/route).

{if game:has_key = true}
Bring the brass key.
{else}
Find the key before midnight.
{endif}
{endletter}

The body must contain visible content. Close any compatible inner block before {endletter}.

Put the letter in an envelope

Add envelope "Label" immediately after letter when readers should choose whether to open and close the paper:

{letter envelope "Sealed letter from Mara" signed "Mara"}
Dear Rowan,

The spare key is beneath the third planter.
{endletter}

The reader initially sees a proportioned closed envelope carrying the quoted label. Open reveals the paper, and Close hides it again.

An envelope needs a non-empty quoted label containing visible plain text. Put the optional signed "Name" after that label. The envelope label and signature are fixed authored text: use matching straight single or double quotation marks, and keep reader values, Game State values, conditional tags, and other chapter syntax in the letter body instead.

Opening and closing the envelope does not change Game State, create a saved step, or remember its state after the page is reloaded.

Appearance and behavior

Letter paper, envelopes, text, and signatures follow the story's Element Theme. They adapt to the reader's White, Black, or Sepia appearance.

A letter is a presentation device. Do not use an envelope to hide private or sensitive information that readers must not access.

Limits and combinations

• Use {letter} or {letter signed "Name"} for directly displayed paper.
• Use {letter envelope "Label"} or {letter envelope "Label" signed "Name"} for a letter readers can open and close.
• Put the opening tag and {endletter} on their own lines, and include a non-empty body.
• Letter blocks cannot be nested inside other letter blocks.
• Close compatible inner elements before {endletter}.
• Keep essential information outside an envelope when every reader must see it immediately.
• Put literal Letter examples in backticks or a fenced block so CHYOA does not turn them into styled correspondence.

Before publishing

Save a draft and check that:

1. the opening tag, body, and {endletter} are in the correct order and on separate lines;
2. the body is not empty and its Markdown, values, conditions, and compatible elements display correctly;
3. envelope "Label" comes immediately after letter, and its label uses matching straight quotation marks with useful visible text;
4. the intended handwritten name appears when signed "Name" is used after letter or after the envelope label;
5. directly displayed paper does not include an envelope label;
6. Open and Close work with keyboard controls as well as a pointer;
7. reloading the page returns an envelope to its closed state;
8. the letter remains readable in White, Black, and Sepia appearance and on a narrow screen.