Formatting, Images, Links, and Tables

Formatting, images, links, and tables

Formatting should make a chapter easier to read. Use headings to divide longer scenes, lists for genuinely ordered or grouped information, tables for comparisons, and links or images only when they add something the prose cannot provide by itself.

Choose rich text or Markdown

Open Settings and find Reading and editor preferences. The option Use the rich text editor to create and edit chapters chooses how the chapter content field works.

With the rich text editor enabled, select text and use the toolbar for:

• bold, italic, and underline;
• links;
• level-two and level-three headings;
• numbered and bulleted lists;
• horizontal dividers;
• quotations.

With it disabled, enter Markdown punctuation directly. Both choices produce the same finished chapter, and you can change the preference later.

Raw HTML is not a supported way to format chapters. Use the editor controls, Markdown, or supported CHYOA chapter syntax instead.

Common Markdown

Put a space after heading, list, and quotation markers. Leave a blank line before and after a list, table, divider, or fenced example so it stays separate from the surrounding paragraph.

The story and chapter titles already identify the page. Begin chapter sections with ## and use ### beneath them instead of adding another main page title.

CHYOA keeps ordinary line breaks in chapter prose. Check the saved chapter for accidental breaks copied from another document.

Show literal chapter syntax

Supported CHYOA tags normally turn into reader values or interactive elements. Put a short tag in backticks when readers should see the tag itself:

Use `{reader:name}` to show the saved name.

Use a fenced block for a complete example:

```text
{if game:has_key = true}
The door opens.
{endif}
```

Fenced examples keep braces, comparison symbols, and forms such as R<n> visible rather than activating them.

Add a link

Write the visible label in square brackets and the destination in parentheses:

[Read the CHYOA Guide](/story/CHYOA-Guide.6006)

Links to CHYOA can use a relative address beginning with /. They stay in the same browser tab. Links to other websites open separately.

Use meaningful link text. “Read the variable guide” tells a reader more than “click here,” especially when links are read out of context. Check the destination before publishing and revisit external links occasionally because other sites can move or remove pages.

A Markdown link inside chapter prose is different from a Link Chapter. A prose link opens the address you provide; a Link Chapter is a follow-up choice that redirects readers to another chapter in the same story and participates in the branch structure.

Add an image

Chapter images use a direct image URL:

![A moonlit path through the forest](https://example.com/moonlit-path.jpg)

The words in square brackets are alternative text. Describe the useful content of the image rather than writing “image” or repeating the file name. Use empty brackets only for a purely decorative image:

![](https://example.com/decorative-divider.png)

CHYOA does not upload images placed inside chapter content. Host the file at a stable address that permits external display, and use an image you have permission to publish. If the host removes the file or blocks outside use, it disappears from the chapter too.

Do not paste an image as embedded image data. Uploading a story cover and displaying an image inside chapter prose are separate features.

Before publishing, check the image at narrow and wide screen sizes. Avoid essential text inside an image; it may be difficult to read, resize poorly, and be unavailable to readers who rely on alternative text.

Add a table

Use a table for repeated fields or comparisons, not as a substitute for page layout. A header row, separator row, and at least one body row are easiest to understand:

| Route | Requirement | Result |
| --- | --- | --- |
| Forest | A lantern | The trail is visible |
| Cave | A key | The iron gate opens |

This displays as:

The first and last | on each row make the columns easier to see, although the table meaning comes from the separators between cells. Keep the same number of cells in each row.

Wide tables can be scrolled horizontally on smaller screens. Keep headings short, move long explanations below the table, and split a complicated table when readers would otherwise have to compare too many columns.

Tables follow the story's Element Theme and also remain readable in each reader's White, Black, or Sepia site appearance.

Combine formatting carefully

Markdown may be used inside chat bubbles and the hidden parts of reveals and locks. Keep the opening and closing syntax intact while formatting the content between them.

Interactive tags placed inside a Markdown link are shown as link text rather than becoming working controls. Put the link and the interactive element in separate parts of the chapter.

Nested formatting is easiest to maintain when it is simple. For example, bold text inside a list is clearer than a heading, quotation, list, and table all nested together.

Make the chapter easy to read

• Keep paragraphs focused and leave breathing room between sections.
• Use headings in order: ## followed by ### when needed.
• Use bold for emphasis, not for every sentence.
• Write descriptive link labels and image alternative text.
• Use table headers that explain what each column contains.
• Do not communicate an important result through color or an image alone.
• View the saved draft in White, Black, and Sepia appearance when formatting is central to the chapter.

Before publishing

Save the chapter as a draft and check that:

1. headings form a clear outline;
2. lists and tables have blank lines around them;
3. every link reaches the intended page;
4. every image loads and has useful alternative text;
5. wide tables can be read on a narrow screen;
6. literal CHYOA examples remain visible instead of turning into controls;
7. the chosen Element Theme works with the chapter content.

Related Guide chapters

• Write and Publish Chapters
• Reader and Game Variables
• Conditional Text with If Statements
• Random Values, Rolls, Reveals, and Actions