Narration markup

If you need fine-grained, page-specific control over the text that appears in your narration, use the markup below.

Marking the same thing on most posts? Ask us to change your default instead. The markup below is for one-off exceptions. If you find yourself adding the same class to most posts, for example to narrate every appendix or every table, email us and we'll change how your site is narrated by default.

Skip content

class="t3a-do-not-narrate"

Anything inside an element with this class is removed before narration.

<div class="t3a-do-not-narrate">
  <p>Subscribe to our newsletter for weekly updates.</p>
</div>

Add audio-only notes

class="t3a-audio-note"

Anything inside an element with this class is available to the narration pipeline, but can be visually hidden from the page.

<div class="t3a-audio-note">
  <p>Audio note: there's a picture of a cat here.</p>
</div>

Your CSS must include a rule to hide the audio notes:

.t3a-audio-note {
  display: none !important;
}

Narrate content we would leave out

class="t3a-must-narrate"

By default, some parts of a page are announced rather than read in full:

  • appendices are left out, and the narration names them;
  • tables are announced with their caption or column headings, and the listener is pointed to the original text;
  • collapsed boxes (<details>) and long examples are announced without their contents.

Add t3a-must-narrate to have one of these narrated in full. Put the class on the element itself, or on a wrapper around it.

Appendices. Put the class on the appendix heading, or on a wrapper around the whole appendix: the heading and everything under it. For an appendix in a collapsed box, put it on the <details> element. Everything inside a narrated appendix is narrated in full too, including its tables and boxes.

<h2 class="t3a-must-narrate">Appendix A: Methods</h2>
<p>We recruited 16 developers…</p>

Tables. The table is read row by row, with each value introduced by its column name, so listeners can follow it. Put the class on the <table>, or on the figure or wrapper around it. Tables up to about 3,000 words of narration, roughly 20 minutes, are read in full; a longer table gets the usual announcement. A table inside an appendix that is left out is left out with it: mark the appendix instead.

<table class="t3a-must-narrate">
  <caption>Time horizons by model</caption>
  …
</table>

Collapsed boxes and examples. Put the class on the <details> element, or on a wrapper around the example.

<details class="t3a-must-narrate">
  <summary>Example transcript</summary>
  <p>…</p>
</details>

Markdown and Jekyll

If you write posts in Markdown with Jekyll (kramdown), wrap the part you want to mark in a div with the class and markdown="1". The markdown="1" attribute keeps the Markdown inside the div converted as usual. A wrapper can hold a single paragraph or table, or a whole section with its heading.

Leave a blank line after the opening <div …> line and another before </div>. Without the blank line before </div>, a table just above it is not converted.

<div class="t3a-must-narrate" markdown="1">

## Appendix A: Methods

Everything in this appendix is narrated in full, including this table:

| Model | Time horizon |
| ----- | ------------ |
| GPT-5 | 138 minutes  |

</div>

<div class="t3a-do-not-narrate" markdown="1">

Subscribe to our newsletter for weekly updates.

</div>

<div class="t3a-audio-note" markdown="1">

Audio note: the chart above shows time horizons doubling roughly every seven months.

</div>

Wrap a collapsed box in the same way:

<div class="t3a-must-narrate" markdown="1">

<details markdown="1">
<summary>Example transcript</summary>
…
</details>

</div>

WordPress

If you use the TYPE III AUDIO WordPress plugin, you do not need to write these classes by hand. Use the "Do not narrate" block control to exclude a block from audio, or insert an "Audio Note" block for narration-only text. The plugin adds the correct markup and hides audio notes on the front end.