Docs Documentación

Columnas de historias

Referencia completa de las columnas del CSV de historia con soporte bilingüe de nombres de columnas. Para la normalización de columnas y soporte de encabezados dobles, consulta Columnas del proyecto.

CSV de historia (story-{id}.csv)

Define la navegación paso a paso y el contenido de paneles para cada historia.

Ubicación: telar-content/spreadsheets/{story_id}.csv

Nomenclatura:

Columnas

Inglés Español Requerido Descripción
step paso Sí Número de paso (1, 2, 3…)
object objeto Sí ID de objeto del objects.csv
x x Sí Coordenada horizontal (0-1 normalizada)
y y Sí Coordenada vertical (0-1 normalizada)
zoom zoom Sí Nivel de zoom: con 1 se ve el objeto completo; con valores mayores, la vista se acerca
page pagina No Página que se muestra en este paso, en objetos de múltiples páginas (la primera es 1)
question pregunta Sí Encabezado mostrado en el panel de la historia
answer respuesta Sí Texto de respuesta breve
layer1_button boton_capa1 No Texto personalizado del botón (vacío = “Saber más”)
layer1_content contenido_capa1 No Contenido del panel: texto en línea o ruta a archivo .md
layer2_button boton_capa2 No Texto personalizado del botón (vacío = “Profundizar más”)
layer2_content contenido_capa2 No Contenido del panel: texto en línea o ruta a archivo .md
layer3_button boton_capa3 No Texto personalizado del botón (vacío = predeterminado)
layer3_content contenido_capa3 No Contenido del panel: texto en línea o ruta a archivo .md
clip_start inicio_clip No Inicio del clip en segundos (ej., 12.5)
clip_end fin_clip No Fin del clip en segundos
loop bucle No Reproducción en bucle (true, false, yes, no, sí). Predeterminado: false
alt_text texto_alt No Texto alternativo por paso para accesibilidad

Ejemplo

Inglés (con contenido en línea):

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

Español (con contenido en línea):

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

El paso 1 usa contenido en línea para la capa 1, mientras que el paso 2 usa una referencia a archivo. Ambos enfoques funcionan y se pueden mezclar libremente.

Notas de los campos

step / paso

object / objeto

x, y, zoom

page / pagina

question / pregunta

answer / respuesta

Botones de las capas

Contenido de las capas

El contenido del panel se puede proporcionar de tres maneras:

Método 1: Introducir texto directamente

Escribe el texto del panel directamente en la celda de la hoja de cálculo. Es el enfoque más sencillo para paneles cortos.

contenido_capa1
Este textil muestra técnicas avanzadas de tejido del periodo colonial.

Para crear saltos de párrafo dentro de una celda:

Entorno Cómo crear saltos de línea
Google Sheets Presiona Ctrl+Enter (Windows/Linux) u Option+Enter (macOS)
Archivos CSV Usa saltos de línea reales dentro de texto entre comillas
Alternativa Usa HTML: <br> para saltos de línea, <p>...</p> para párrafos

Puedes usar formato básico: **negrita**, *cursiva*, [texto del enlace](url), y enlaces de glosario ([[term-id]]).

Método 2: Pegar texto Markdown

Pega texto escrito en un editor de texto plano. Esto admite la gama completa de características de formato, incluyendo encabezados, widgets (acordeón, carrusel, pestañas), controles de tamaño de imagen y un título de panel personalizado usando frontmatter YAML.

Si copias y pegas desde Microsoft Word, Google Docs o aplicaciones similares, el formato no se preservará. Escribe con sintaxis Markdown en su lugar — consulta la Guía de Sintaxis Markdown.

Método 3: Indicar un archivo Markdown

Indica la ruta a un archivo Markdown en tu repositorio. Esto se recomienda para paneles complejos, especialmente aquellos con widgets o contenido que quieras reutilizar.

contenido_capa1
textiles-coloniales/step1-layer1.md

Guarda los archivos Markdown en telar-content/texts/stories/. En tu hoja de cálculo, ingresa solo el nombre del archivo — o si organizaste los archivos en subcarpetas, incluye el nombre de la subcarpeta.

Cómo decide Telar: Si lo que ingresas termina en .md y el archivo existe, lo carga. De lo contrario, trata el valor como contenido.

clip_start, clip_end / inicio_clip, fin_clip

loop / bucle

alt_text / texto_alt

Elegir el método correcto

Escenario Método recomendado
Explicación corta (1-2 párrafos) Método 1: Introducir directamente
Panel con título personalizado o widgets Método 2: Pegar, o Método 3: Archivo
Contenido con widgets (acordeón, pestañas, carrusel) Método 3: Archivo
Mismo contenido usado en varios lugares Método 3: Archivo
Ediciones rápidas sin salir de la hoja de cálculo Método 1 o 2

Alias del CSV de historia

Normalizado Acepta
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

Los nombres de columna layer_file / archivo_capa son alias heredados de antes de v0.6.3. Los nombres preferidos son layer_content / contenido_capa.

Las respuestas son texto corrido

El campo answer aparece en la tarjeta de texto, debajo de la pregunta. En pantallas de escritorio esa tarjeta tiene un tamaño fijo y no se desplaza, así que lo que se salga del borde no le llega a quien lee.

Por eso Telar deja las respuestas en texto corrido al construir el sitio, y anota cada cambio en la salida del build.

Lo que se conserva tal como lo escribiste:

Lo que conserva las palabras y pierde el formato:

Lo que desaparece por completo, junto con el texto que lleve adentro:

El límite de las respuestas

La respuesta tiene que caber entera en la tarjeta, sin que quien lee tenga que desplazarse. Por eso Telar no la mide en palabras sino en líneas: cuenta 53 caracteres por línea y dos líneas más por cada párrafo después del primero. Una respuesta puede tener hasta 18 líneas y cinco párrafos. En un solo párrafo, eso da para unas 150 palabras; si la divides en párrafos, para menos. Si pasa de 15 líneas, se muestra con letra un poco más pequeña.

Telar recorta toda respuesta que pase del límite y lo anota en la salida del build. El corte cae entre palabras y nunca parte un enlace, un término del glosario, un fragmento de código ni una fórmula LaTeX. El texto que sobra no aparece en la historia.

Escribe una o dos oraciones. Cuando necesites más espacio, pasa el detalle a un panel: los paneles admiten todo lo que describe la Referencia de sintaxis de Markdown, incluidas las notas al pie, las tablas, las imágenes y los widgets.

Consejos para la entrada de datos

Coordenadas: Usa el selector de coordenadas en las páginas de objetos para encontrar los valores x, y y zoom, y cópialos directamente a tu CSV.

Markdown en los campos:

Contenido de paneles: Usa referencias a archivos (Método 3) para contenido complejo con widgets. Usa texto en línea (Método 1) para paneles cortos.

Validación

Telar valida los datos CSV de historias durante el build:

Errores de historias (el build falla):

Advertencias de historias (el build continúa):

Véase también