Telar: Docs Telar: Documentación

CSV Column Reference

Complete reference for all CSV columns in Telar with bilingual column name support.

Overview

Telar v0.6.0+ supports CSV columns in both English and Spanish. You can use either language consistently, mix them, or include dual headers for bilingual reference.

Column Normalization

All column names are normalized during processing:

Dual Header Support

Include both English and Spanish headers for bilingual teams:

order,story_id,title,subtitle,byline
orden,id_historia,titulo,subtitulo,firma
1,colonial-textiles,Colonial Textiles,Weaving traditions,by Dr. Smith
2,textiles-coloniales,Textiles Coloniales,Tradiciones textiles,por Dra. García

Telar automatically detects and skips the second header row.

Project CSV (project.csv / proyecto.csv)

Defines stories and their display order on the homepage.

Location: components/structures/project.csv or components/structures/proyecto.csv

Columns

English Spanish Required Description
order orden Yes Display order on homepage (1, 2, 3…)
story_id id_historia No Semantic identifier (e.g., colonial-textiles). If omitted, uses story-{order}
title titulo Yes Story title shown on homepage and story page
subtitle subtitulo Yes Brief description shown on story cards
byline firma No Author attribution; supports markdown for links and formatting

Example

English:

order,story_id,title,subtitle,byline
1,colonial-textiles,Colonial Textiles,Weaving traditions of the Americas,by Dr. Jane Smith
2,trade-routes,Trade Routes,Following the threads of commerce,based on [original research](https://example.com)

Spanish:

orden,id_historia,titulo,subtitulo,firma
1,textiles-coloniales,Textiles Coloniales,Tradiciones de tejido de las Américas,por Dra. María García
2,rutas-comerciales,Rutas Comerciales,Siguiendo los hilos del comercio,basado en [investigación original](https://ejemplo.com)

Field Notes

order

story_id

title

subtitle

byline

Objects CSV (objects.csv / objetos.csv)

Catalogs all objects used in stories.

Location: components/structures/objects.csv or components/structures/objetos.csv

Columns

English Spanish Required Description
object_id objeto Yes Unique identifier (lowercase, hyphens, underscores)
title titulo Yes Object title
description descripcion No Long-form description (markdown supported)
creator creador No Creator or artist name
date fecha / periodo No Creation date or period
medium medio No Material or medium
dimensions dimensiones No Physical dimensions
location ubicacion / locacion No Current location or repository
credit credito No Attribution or credit line
thumbnail miniatura No Path to thumbnail image
iiif_manifest manifiesto_iiif No URL to external IIIF manifest
source_url url_fuente No IIIF image info.json URL

Example

English:

object_id,title,description,creator,date,medium,dimensions,location,credit,thumbnail,source_url
textile-001,Colonial Textile,A woven fragment showing complex patterns...,Unknown,circa 1650,Wool,45 x 60 cm,National Museum,Public Domain,,
map-lima,Map of Lima,Early colonial map showing city layout,Juan de Cuellar,1685,Ink on paper,30 x 40 cm,,,map-thumb.jpg,https://example.org/iiif/map/info.json

Spanish:

objeto,titulo,descripcion,creador,periodo,medio,dimensiones,ubicacion,credito,miniatura,url_fuente
textil-001,Textil Colonial,Un fragmento tejido con patrones complejos...,Desconocido,circa 1650,Lana,45 x 60 cm,Museo Nacional,Dominio Público,,
mapa-lima,Mapa de Lima,Mapa colonial temprano mostrando el diseño de la ciudad,Juan de Cuellar,1685,Tinta sobre papel,30 x 40 cm,,,mapa-miniatura.jpg,https://ejemplo.org/iiif/mapa/info.json

Field Notes

object_id / objeto

description / descripcion

date / fecha / periodo

credit / credito

iiif_manifest / manifiesto_iiif

source_url / url_fuente

Story CSV (story-{id}.csv / historia-{id}.csv)

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

Location: components/structures/{story_id}.csv or components/structures/historia-{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 (0-1 normalized)
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_file archivo_capa1 Yes Path to layer 1 markdown file
layer2_button boton_capa2 No Custom button text (empty = “Go deeper”)
layer2_file archivo_capa2 No Path to layer 2 markdown file
layer3_button boton_capa3 No Custom button text (empty = default)
layer3_file archivo_capa3 No Path to layer 3 markdown file

Example

English:

step,object,x,y,zoom,question,answer,layer1_button,layer1_file,layer2_button,layer2_file
1,textile-001,0.5,0.5,1.0,What is this?,A colonial textile fragment,"",colonial-textiles/step1-layer1.md,"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:

paso,objeto,x,y,zoom,pregunta,respuesta,boton_capa1,archivo_capa1,boton_capa2,archivo_capa2
1,textil-001,0.5,0.5,1.0,¿Qué es esto?,Un fragmento de textil colonial,"",textiles-coloniales/paso1-capa1.md,"Aprende 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

Field Notes

step / paso

object / objeto

x, y, zoom

question / pregunta

answer / respuesta

layer buttons / botones de capa

layer files / archivos de capa

Alternative Column Names

Complete mappings of all accepted column names.

Project CSV Aliases

Normalized Accepts
order order, orden, number, numero, num
story_id story_id, id_historia, story-id, story
title title, titulo, name, nombre
subtitle subtitle, subtitulo, description, descripcion, desc
byline byline, firma, author, autor, attribution, atribucion

Objects CSV Aliases

Normalized Accepts
object_id object_id, objeto, object, id
title title, titulo, name, nombre
description description, descripcion, desc
creator creator, creador, artist, artista, author, autor
date date, fecha, period, periodo
medium medium, medio, material
dimensions dimensions, dimensiones, size, tamaño
location location, ubicacion, locacion, repository, repositorio
credit credit, credito, attribution, atribucion
thumbnail thumbnail, miniatura, thumb
iiif_manifest iiif_manifest, manifiesto_iiif, manifest, manifiesto
source_url source_url, url_fuente, iiif_source_url, iiif_url

Story CSV Aliases

Normalized Accepts
step step, paso, number, numero, num
object object, objeto, object_id
x x, horizontal, left
y y, vertical, top
zoom zoom, z, scale
question question, pregunta, heading, encabezado
answer answer, respuesta, response
layer1_button layer1_button, boton_capa1, button1, btn1
layer1_file layer1_file, archivo_capa1, file1, layer1
layer2_button layer2_button, boton_capa2, button2, btn2
layer2_file layer2_file, archivo_capa2, file2, layer2
layer3_button layer3_button, boton_capa3, button3, btn3
layer3_file layer3_file, archivo_capa3, file3, layer3

Best Practices

Choosing Column Names

Monolingual sites: Use your preferred language consistently

# English site
order,story_id,title,subtitle,byline

# Spanish site
orden,id_historia,titulo,subtitulo,firma

Bilingual teams: Use dual headers

order,story_id,title,subtitle,byline
orden,id_historia,titulo,subtitulo,firma

Mixed environments: Mix is supported but not recommended

order,id_historia,title,subtitulo,byline  # Works but confusing

File Organization

Recommended structure:

components/structures/
├── project.csv              # English
├── objects.csv
├── colonial-textiles.csv    # Using story_id
└── trade-routes.csv

# OR

components/structures/
├── proyecto.csv             # Spanish
├── objetos.csv
├── textiles-coloniales.csv
└── rutas-comerciales.csv

story_id naming:

Data Entry Tips

Coordinates:

  1. Use coordinate tool on object pages
  2. Click to identify x, y, zoom values
  3. Copy values directly into CSV
  4. Test in story viewer

Markdown in fields:

File references:

Validation

Telar validates CSV data during build:

Errors (build fails):

Warnings (build succeeds):

Check build output for validation messages.

Migration from Previous Versions

From v0.5.x to v0.6.0

New features:

Breaking changes: None. All v0.5.x CSVs work without modification.

Recommended updates:

  1. Add story_id to project.csv for semantic naming
  2. Rename story CSVs to match story_id
  3. Consider using Spanish column names if appropriate
  4. Add markdown links to bylines if desired

From v0.4.x to v0.6.0

Additional changes:

Troubleshooting

“Column not found” errors

Cause: Column name not recognized Solution: Check spelling, use names from reference above

“Duplicate object_id” errors

Cause: Same object_id used twice in objects.csv Solution: Make each object_id unique

“Invalid step sequence” errors

Cause: Steps not sequential (1, 2, 4) or duplicate steps Solution: Ensure steps are 1, 2, 3, 4… without gaps

“File not found” errors

Cause: Markdown file referenced but doesn’t exist Solution: Create file or remove file reference from CSV

Coordinates not working

Cause: Values outside 0-1 range or incorrect object_id Solution: Use coordinate tool, verify object exists

See Also

New in v0.6.0: Bilingual CSV support with Spanish column names and dual headers.