Skip to content

Formatting descriptions

A story's Description can carry a little formatting — bold words, a heading, a short list — so a longer text is easier to read. You do this by typing simple markers around your words; the app and the browser console both turn them into formatting when the story is shown. A description with no markers in it looks exactly as it always has.

When visitors see it

Formatting shows in the visitor app from the release that includes it; until your visitors update, they see the markers as typed.

In the app

On the Add New Story and Edit Story screens, three buttons sit above the Description field:

  • Bold — wraps the selected words in bold. Select some text and tap it; tap it again on the same words to take the bold off.
  • Heading — turns each selected line into a heading. With several lines selected it applies to every one of them; tap it again to turn them back into ordinary lines.
  • List item — turns each selected line into a bullet. It works across several selected lines the same way, and tapping it again removes the bullets.

Tap Preview to show the description under the field as visitors will see it. It updates as you type, and the field stays editable the whole time; tap Preview again to hide it. A short hint line under the field lists the markers if you would rather type them yourself.

In the browser console

The console has no buttons — you type the markers. The hint under the Description field lists the common ones, and the Preview section under the field shows the result as you type. It is closed until you open it; opening it doesn't change the story or count as an edit.

What to type

You type Visitors see
**bold** bold text
*italic* or _italic_ italic text
## Heading a heading line, in bold
- item (or * item, + item) a bullet point
> quotation an indented quotation
--- on a line by itself a thin dividing line

Leave blank lines

Put a blank line between paragraphs, and before and after a heading or a list. A single line break inside a paragraph stays a line break — you don't need to do anything special to keep it.

All heading levels look the same, so there is no need to choose between them: use ##.

Typing a literal asterisk or hash

If you want a * or # to appear as itself, put a backslash in front of it: \* or \#. Typing \*\*not bold\*\* shows **not bold**, asterisks and all, unformatted.

One thing catches people out because it was already a valid marker: a line that starts with # and a space becomes a heading. To start a line with a number sign — for example # of works — write \# of works.

Numbers and dates

There are no numbered lists. A line that starts with a number and a full stop — 1853. Born in Zundert. — is shown exactly as you typed it, number and full stop included, so dates and timelines come out right:

1853. Born in Zundert.

1886. Moves to Paris.

1888. Arrives in Arles.

Each year stays the year you typed. Bold and italic still work inside such a line, and a single line break is still a line break. If you want a list, use bullets (- item).

Good to know

  • Read-aloud and screen readers never speak the markers. The Listen button reads the words only, and headings are announced as headings.
  • Links aren't tappable. Web addresses and links written in the description show as their text only.
  • Some markup is left as typed. Lines underlined with ===, ~~~ fences, raw HTML tags and [1]: https://… reference lines all show up as the ordinary text you wrote. A line followed by --- keeps its words, but the --- line itself becomes a dividing line. Either way, your words are never lost.
  • Indented lines and code fences lose their special meaning, not their words. A line indented by four spaces or a tab is ordinary text: bold and italic still work in it, but a -, # or > at the start of it shows as typed instead of making a list, heading or quotation. A closed ``` fence turns into plain text too — the backticks go and its lines are joined into one.
  • A description of only markers counts as empty. Something like ---, ** ** or a lone # has no words in it, so it doesn't satisfy the required Description.
  • The markers count toward the limit. In the app the Description is limited to 1,000 characters, and ** and ## count like any other characters.

Existing descriptions

Descriptions written before formatting existed need no changes. Only text that happens to contain markers — for instance a line that starts with - or # — will look different.

See also Adding a story and AI descriptions & audio.