Docs Documentación

Referencia de sintaxis de Markdown

Los paneles de contenido en Telar se deben escribir utilizando el formato Markdown. Esta guía de referencia cubre cómo funciona esta sintaxis para crear contenido narrativo claro y atractivo.

¿Qué es Markdown?

Markdown es un lenguaje de marcado ligero que te permite formatear texto usando una sintaxis simple y legible. En lugar de etiquetas HTML complejas, escribes en texto plano con caracteres especiales como * para énfasis o # para encabezados. Markdown es:

Recursos de aprendizaje

¿Nuevo en Markdown? Estos recursos te ayudarán:

Telar usa el procesador Python Markdown con las extensiones extra y nl2br.

Métodos de contenido de panel

Puedes proporcionar el contenido del panel de tres maneras. Para más detalles, consulta la Referencia CSV: Historias.

Método 1: Introducir texto directamente

Escribe el texto del panel directamente en la columna contenido_capa1 de tu hoja de cálculo:

contenido_capa1
Este textil muestra técnicas avanzadas de tejido del período colonial. El patrón entrelazado indica una artesanía sofisticada.

Los saltos de línea en la celda de tu hoja de cálculo crean saltos de párrafo. El título del panel es el texto del botón de manera predeterminada.

Método 2: Pegar texto markdown

Pega texto desde un editor de texto plano. Puedes incluir encabezados, widgets y un título de panel personalizado usando frontmatter YAML:

---
title: "Técnicas de tejido"
---

El patrón de urdimbre entrelazada visible aquí indica una técnica
de tejido compleja que era común en el período colonial.

## Detalles técnicos

Estos patrones se creaban usando...

Si copias y pegas desde Microsoft Word, Google Docs o aplicaciones similares, el formato no se preservará. Escribe en sintaxis markdown.

Método 3: Indicar un archivo de texto

Para contenido complejo, indica un archivo markdown guardado en telar-content/texts/stories/:

contenido_capa1
textiles-coloniales/paso1-capa1.md

El archivo usa frontmatter para el título del panel y soporta todas las funcionalidades de markdown, incluyendo widgets.

Cuándo usar archivos de texto:

Formato básico

Encabezados

## Encabezado de segundo nivel
### Encabezado de tercer nivel
#### Encabezado de cuarto nivel

Consejo: No uses # Primer nivel en paneles; el panel ya tiene un título definido en el front matter.

Estilos de texto

**Texto en negrita** para énfasis
*Texto en cursiva* para énfasis sutil
***Negrita y cursiva*** para máximo énfasis

Listas

Listas desordenadas:

- Primer elemento
- Segundo elemento
  - Elemento anidado
  - Otro elemento anidado
- Tercer elemento

Listas ordenadas:

1. Primer paso
2. Segundo paso
3. Tercer paso

Enlaces

[Texto del enlace](https://example.com)
[Enlace interno](/objects/textile-001/)

Citas en bloque

> Esto es una cita en bloque.
> Puede abarcar múltiples líneas.

Imágenes

Telar proporciona sintaxis especial para controlar los tamaños de imagen en los paneles.

Sintaxis básica

![Texto alternativo descriptivo](ruta/a/imagen.jpg){tamaño}

Opciones de tamaño

Tamaño Palabra clave Ancho máx. Caso de uso
Pequeño {sm} o {small} 250px Miniaturas, iconos, detalles pequeños
Mediano {md} o {medium} 450px Ilustraciones estándar (predeterminado)
Grande {lg} o {large} 700px Imágenes destacadas, vistas detalladas
Completo {full} 100% Panoramas, visuales de ancho completo

Rutas de imagen

Rutas relativas (sin barra inicial) se cargan automáticamente desde /telar-content/objects/:

![Detalle de tejido](textile-closeup.jpg){md}

→ Carga /telar-content/objects/textile-closeup.jpg

Rutas absolutas (comenzando con /) cargan desde la raíz del sitio:

![Logo del sitio](/telar-content/objects/logo.png){sm}

URLs externas funcionan como se espera:

![Foto del museo](https://example.com/image.jpg){lg}

Ejemplos

![Miniatura pequeña](thumb.jpg){small}
![Ilustración mediana](diagram.jpg){md}
![Imagen destacada grande](painting.jpg){large}
![Panorama de ancho completo](landscape.jpg){full}

Tamaño Predeterminado: Las imágenes sin etiqueta de tamaño predeterminan a mediano (450px). Siempre incluye etiquetas de tamaño para claridad.

Pies de imagen

Agrega un pie de imagen colocando texto en la línea inmediatamente después de la imagen:

![Fragmento textil colonial](textile.jpg){lg}
Detalle que muestra el patrón de *urdimbre entrelazada* típico del período.

El pie de imagen aparece centrado debajo de la imagen en una fuente de peso ligero.

Prefijo opcional: Puedes usar caption: para hacer los pies más explícitos:

![Mapa de la región](map.jpg){md}
caption: Mapa de la *Recopilación de Leyes*, 1680.

El prefijo caption: se elimina del texto mostrado.

Markdown en pies de imagen: Los pies de imagen admiten formato markdown como *cursivas*, **negritas** y [enlaces](url).

Medios enriquecidos

Videos de YouTube

Inserta videos de YouTube adaptables usando un iframe HTML:

<div style="position: relative; padding-bottom: 56.25%; height: 0; overflow: hidden; max-width: 100%; margin: 1.5rem 0;">
  <iframe style="position: absolute; top: 0; left: 0; width: 100%; height: 100%;"
          src="https://www.youtube.com/embed/VIDEO_ID"
          frameborder="0"
          allowfullscreen>
  </iframe>
</div>

Reemplaza VIDEO_ID con el ID de tu video de YouTube.

El padding-bottom: 56.25% crea un contenedor con relación de aspecto 16:9.

Otros iframes

Cualquier contenido incrustable con iframe funciona:

<iframe src="https://example.com/embed"
        width="100%"
        height="400"
        frameborder="0">
</iframe>

Código

Código en línea

Usa comillas invertidas para referencias de código en línea:

El campo `object_id` debe coincidir con el nombre del archivo.

Bloques de código

Usa triple comillas invertidas para bloques de código:

```
git add .
git commit -m "Actualizar contenido"
git push
```

Con resaltado de sintaxis:

```yaml
title: Mi Historia
description: Una narrativa convincente
```

Notas al pie

Crea notas al pie con sintaxis [^1]:

El textil muestra técnicas avanzadas.[^1]

[^1]: Basado en el análisis de la Dra. Smith (2020).

Las notas al pie aparecen automáticamente al final del contenido del panel con estilo apropiado.

Notación matemática y científica (LaTeX)

Telar permite representar fórmulas matemáticas mediante KaTeX. Puedes incluir fórmulas, ecuaciones químicas y notación científica en cualquier lugar donde se use markdown: paneles de historias, definiciones del glosario, descripciones de objetos y páginas personalizadas.

Cómo funciona

Telar detecta automáticamente el LaTeX en el contenido durante la construcción del sitio. No necesitas configurar nada — si el texto contiene notación LaTeX, se representará como fórmula formateada.

Fórmulas en línea

Encierra las expresiones entre signos de dólar simples para que aparezcan en línea con el texto:

El coeficiente es $C = \frac{8}{35}$ y el polinomio es $P_4(x)$.

Se muestra así: El coeficiente es $C = \frac{8}{35}$ y el polinomio es $P_4(x)$.

Heurística del signo de dólar: para evitar falsos positivos con monedas (ej., “$50”), Telar solo trata $...$ como fórmula cuando el contenido incluye caracteres propios de LaTeX como \, ^, _ o {. Los signos dobles ($$...$$) siempre se tratan como fórmulas.

Fórmulas en bloque

Encierra las expresiones entre signos de dólar dobles para obtener ecuaciones centradas e independientes:

$$x^4 = \frac{8}{35}P_4(x) + \frac{4}{7}P_2(x) + \frac{1}{5}P_0(x)$$

Se muestra así:

$$x^4 = \frac{8}{35}P_4(x) + \frac{4}{7}P_2(x) + \frac{1}{5}P_0(x)$$

También puedes usar los delimitadores \[...\]:

\[E = mc^2\]

Ecuaciones de varias líneas

Usa \begin{align}...\end{align} para ecuaciones alineadas en varias líneas. Marca los puntos de alineación con & y los saltos de línea con \\:

$$\begin{align}
P_0(x) &= 1\\
P_1(x) &= x\\
P_2(x) &= \frac{1}{2}(3x^2 - 1)
\end{align}$$

Se muestra así:

$$\begin{align} P_0(x) &= 1\\ P_1(x) &= x\\ P_2(x) &= \frac{1}{2}(3x^2 - 1) \end{align}$$

Entornos compatibles

Entorno Propósito
align, align* Ecuaciones alineadas (con/sin numeración)
equation, equation* Ecuaciones individuales (con/sin numeración)
cases Funciones definidas por tramos
pmatrix Matrices con paréntesis
bmatrix Matrices con corchetes

Fórmulas químicas

Telar incluye la extensión mhchem para notación química:

La reacción $\ce{2H2 + O2 -> 2H2O}$ produce agua.

$$\ce{CO2 + C -> 2CO}$$

Se muestra así: La reacción $\ce{2H2 + O2 -> 2H2O}$ produce agua.

$$\ce{CO2 + C -> 2CO}$$

Dónde funciona LaTeX

Tipo de contenido Cómo se carga
Paneles de historias (capa 1 / capa 2) Automático — se detecta al construir el sitio
Texto de paso de historia Automático — se detecta al construir el sitio
Descripciones de objetos Automático — se detecta al construir el sitio
Definiciones del glosario Automático — se detecta al construir el sitio
Páginas personalizadas Siempre disponible
Historias cifradas Se carga automáticamente tras descifrar

Referencia completa de sintaxis

Para la lista completa de comandos LaTeX compatibles, consulta la tabla de funciones de KaTeX.

Mejores prácticas

Texto alternativo para accesibilidad

Siempre proporciona texto alternativo descriptivo para las imágenes:

✅ ![Vista detallada de hilos de urdimbre entrelazados](closeup.jpg){lg}
❌ ![Imagen](closeup.jpg){lg}

Organización de imágenes

Mantén las imágenes de los paneles en /telar-content/objects/ para fácil referencia:

telar-content/objects/
├── story1-context.jpg
├── story1-detail.jpg
├── story2-map.jpg
└── ...

Longitud del contenido

Divide el texto largo con encabezados, listas e imágenes para mejor legibilidad.

Nomenclatura de archivos

Usa nombres de archivo descriptivos, en minúsculas con guiones:

✅ ![Patrón de tejido colonial](colonial-textile-detail.jpg){md}
❌ ![Foto](IMG_1234.JPG){md}

Referencia rápida

Ejemplos listos para copiar y pegar de las tareas de formato más comunes:

Agregar una imagen con pie de foto

![Textil colonial con patrón entrelazado](textile-detail.jpg){lg}
Detalle de los hilos de urdimbre, circa 1650.

Agregar un video de YouTube

<div style="position: relative; padding-bottom: 56.25%; height: 0; overflow: hidden; max-width: 100%; margin: 1.5rem 0;">
  <iframe style="position: absolute; top: 0; left: 0; width: 100%; height: 100%;"
          src="https://www.youtube.com/embed/dQw4w9WgXcQ"
          frameborder="0" allowfullscreen></iframe>
</div>

Agregar una cita con nota al pie

Estudios recientes cuestionan esta interpretación.[^1]

[^1]: García, M. (2023). *Repensando los textiles coloniales*. Editorial Universitaria.

Enlazar a un término del glosario

El sistema de [[encomienda]] estructuró las relaciones tributarias coloniales.

Enlazar a otro objeto

Compara con el [textil de Lima](/objects/textile-lima/).

Agregar fórmulas en línea y en bloque

El coeficiente es $C = \frac{8}{35}$ y el resultado es:

$$x^4 = \frac{8}{35}P_4(x) + \frac{4}{7}P_2(x) + \frac{1}{5}P_0(x)$$

Crear una cita en bloque

> "Los patrones revelan una comprensión sofisticada de la geometría."
> — Autor

Limitaciones

Próximos pasos