Docs Documentación

Story Columns

Complete reference for story CSV columns with bilingual column name support. For column normalization and dual header support, see Project Columns.

Story CSV (story-{id}.csv)

Defines step-by-step navigation and panel content for each story.

Location: telar-content/spreadsheets/{story_id}.csv

Naming:

Columns

English Spanish Required Description
step paso Yes Step number (1, 2, 3…)
object objeto Yes Object ID from objects.csv
x x Yes Horizontal coordinate (0-1 normalized)
y y Yes Vertical coordinate (0-1 normalized)
zoom zoom Yes Zoom level: 1 shows the whole object; higher values move closer
page pagina No Which page of a multi-page object this step shows (the first page is 1)
question pregunta Yes Heading displayed in story panel
answer respuesta Yes Brief answer text
layer1_button boton_capa1 No Custom button text (empty = “Learn more”)
layer1_content contenido_capa1 No Panel content: inline text or path to .md file
layer2_button boton_capa2 No Custom button text (empty = “Go deeper”)
layer2_content contenido_capa2 No Panel content: inline text or path to .md file
layer3_button boton_capa3 No Custom button text (empty = default)
layer3_content contenido_capa3 No Panel content: inline text or path to .md file
clip_start inicio_clip No Clip start time in seconds (e.g., 12.5)
clip_end fin_clip No Clip end time in seconds
loop bucle No Loop playback (true, false, yes, no). Defaults to false
alt_text texto_alt No Per-step alt text for accessibility

Example

English (with inline content):

step,object,x,y,zoom,question,answer,layer1_button,layer1_content,layer2_button,layer2_content
1,textile-001,0.5,0.5,1.0,What is this?,A colonial textile fragment,"",This fragment shows **advanced weaving techniques** from the colonial period.,"Learn More",colonial-textiles/step1-layer2.md
2,textile-001,0.3,0.7,0.5,What is this pattern?,An interlocking warp design,"",colonial-textiles/step2-layer1.md,"",colonial-textiles/step2-layer2.md

Spanish (with inline content):

paso,objeto,x,y,zoom,pregunta,respuesta,boton_capa1,contenido_capa1,boton_capa2,contenido_capa2
1,textil-001,0.5,0.5,1.0,¿Qué es esto?,Un fragmento de textil colonial,"",Este fragmento muestra **técnicas avanzadas de tejido** del período colonial.,"Saber más",textiles-coloniales/paso1-capa2.md
2,textil-001,0.3,0.7,0.5,¿Qué es este patrón?,Un diseño de urdimbre entrelazada,"",textiles-coloniales/paso2-capa1.md,"",textiles-coloniales/paso2-capa2.md

Step 1 uses inline content for layer 1, while step 2 uses a file reference. Both approaches work and can be mixed freely.

Field Notes

step / paso

object / objeto

x, y, zoom

page / pagina

question / pregunta

answer / respuesta

Layer buttons

Layer content

Panel content can be provided in three ways:

Method 1: Enter text directly

Type your panel text directly in the spreadsheet cell. This is the simplest approach for short panels.

layer1_content
This textile shows advanced weaving techniques from the colonial period.

To create paragraph breaks within a cell:

Environment How to create line breaks
Google Sheets Press Ctrl+Enter (Windows/Linux) or Option+Enter (macOS)
CSV files Use actual newlines inside quoted text
Alternative Use HTML: <br> for line breaks, <p>...</p> for paragraphs

You can use basic formatting: **bold**, *italic*, [link text](url), and glossary links ([[term-id]]).

Method 2: Paste markdown text

Paste text written in a plain text editor. This supports the full range of formatting features including headings, widgets (accordion, carousel, tabs), images with size controls, and a custom panel title using YAML frontmatter.

If you copy and paste from Microsoft Word, Google Docs, or similar applications, formatting will not be preserved. Write in markdown syntax instead — see the Markdown Syntax Guide.

Method 3: Reference a markdown file

Point to a markdown file in your repository. This is recommended for complex panels, especially those with widgets or content you want to reuse.

layer1_content
colonial-textiles/step1-layer1.md

Save markdown files in telar-content/texts/stories/. In your spreadsheet, enter just the filename — or if you’ve organized files into subfolders, include the subfolder name.

How Telar decides: If what you enter ends in .md and the file exists, it loads the file. Otherwise, it treats the value as content.

clip_start, clip_end / inicio_clip, fin_clip

loop / bucle

alt_text / texto_alt

Choosing the Right Method

Scenario Recommended method
Short explanation (1-2 paragraphs) Method 1: Enter directly
Panel with custom title or widgets Method 2: Paste, or Method 3: File reference
Content with widgets (accordion, tabs, carousel) Method 3: File reference
Same content used in multiple places Method 3: File reference
Quick edits without leaving the spreadsheet Method 1 or 2

Column Aliases

Normalized Accepts
step step, paso
object object, objeto, object_id
x x
y y
zoom zoom
page page, pagina, página
question question, pregunta
answer answer, respuesta
layer1_button layer1_button, boton_capa1
layer1_content layer1_content, contenido_capa1, layer1_file, archivo_capa1
layer2_button layer2_button, boton_capa2
layer2_content layer2_content, contenido_capa2, layer2_file, archivo_capa2
layer3_button layer3_button, boton_capa3
layer3_content layer3_content, contenido_capa3, layer3_file, archivo_capa3
clip_start clip_start, inicio_clip
clip_end clip_end, fin_clip
loop loop, bucle
alt_text alt_text, texto_alt

The layer_file / archivo_capa column names are backward-compatible aliases from before v0.6.3. The preferred names are layer_content / contenido_capa.

Answers Are Plain Prose

The answer field appears in the text card beside your object, under the question. On desktop that card is a fixed size and does not scroll, so anything past its edge never reaches your readers.

To keep answers readable, Telar reduces every answer to plain prose during the build, and reports each change it makes in the build log.

These work in an answer and appear as you wrote them:

Telar keeps the words of these but drops the formatting:

Telar removes these completely, along with any text inside them:

The Answer Limit

An answer has to fit on its card without scrolling. Telar therefore measures it in lines rather than words, counting 53 characters to a line and two lines for each paragraph after the first. An answer can have up to 18 lines and five paragraphs: roughly 150 words in a single paragraph, fewer when you split it into paragraphs. An answer longer than 15 lines is set in slightly smaller type.

Telar cuts any answer over the limit and reports the cut in the build log. The cut falls on a word boundary, never inside a link, a glossary term, a code span or a LaTeX expression, so your markup never breaks. Text past the cut does not appear on your site.

Aim for 1-2 sentences. When you need more room, move the detail into a layer panel: panels take the full markdown of the Markdown Syntax Reference, footnotes, tables, images and widgets included.

Data Entry Tips

Coordinates: Use the coordinate picker on object pages to find x, y, zoom values and copy them directly into your CSV.

Markdown in fields:

Panel content: Use file references (Method 3) for complex content with widgets. Use inline text (Method 1) for short panels.

Validation

Telar validates story CSV data during build:

Errors (build fails):

Warnings (build succeeds):

Check build output for validation messages.

See Also