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:
- Fácil de leer: Incluso en su forma cruda, markdown es legible
- Fácil de escribir: Sintaxis simple que es más rápida que HTML
- Portátil: Los archivos de texto plano funcionan en cualquier lugar
- Convertible: Se convierte automáticamente a HTML para su visualización
Recursos de aprendizaje
¿Nuevo en Markdown? Estos recursos te ayudarán:
- Guía de Markdown - Guía completa para empezar
- Tutorial de CommonMark - Tutorial interactivo de 10 minutos
- Hoja de Referencia de Markdown - Referencia rápida
Telar usa el procesador Python Markdown con las extensiones extra y nl2br.
Estructura de paneles
Los archivos de las capas de la historia (referenciados en las columnas layer1_file y layer2_file) usan Markdown con YAML front matter:
---
title: "Título de Tu Panel"
---
Tu contenido va aquí con soporte completo de Markdown.
El título del front matter aparece en el encabezado del panel. El contenido del cuerpo se convierte a HTML y se muestra en el panel.
Formato básico
Encabezados
## Encabezado de Segundo Nivel
### Encabezado de Tercer Nivel
#### Encabezado de Cuarto Nivel
Consejo: No uses
# Primer nivelen 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
{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 /components/images/additional/:
{md}
→ Carga /components/images/additional/textile-closeup.jpg
Rutas absolutas (comenzando con /) cargan desde la ubicación especificada:
{sm}
URLs externas funcionan como se espera:
{lg}
Ejemplos
{small}
{md}
{large}
{full}
Tamaño Predeterminado: Las imágenes sin etiqueta de tamaño predeterminan a mediano (450px). Siempre incluye etiquetas de tamaño para claridad.
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.
Mejores prácticas
Texto alternativo para accesibilidad
Siempre proporciona texto alternativo descriptivo para las imágenes:
✅ {lg}
❌ {lg}
Organización de imágenes
Mantén las imágenes de los paneles en /components/images/additional/ para fácil referencia:
components/images/additional/
├── story1-context.jpg
├── story1-detail.jpg
├── story2-map.jpg
└── ...
Longitud del contenido
- Capa 1: 2-3 párrafos de contexto
- Capa 2: Contenido académico más extenso, citas, análisis extendido
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:
✅ {md}
❌ {md}
Limitaciones
- Sin JavaScript: Markdown se convierte a HTML estático
- Sin atributos HTML personalizados: Usa la sintaxis de tamaño proporcionada en lugar de clases personalizadas
- Procesamiento de imágenes: Solo las imágenes en
/components/images/objects/generan automáticamente tiles IIIF
Siguientes pasos
- Guía de estructura de contenido - Aprende a organizar tus archivos Markdown
- Flujo de trabajo web de GitHub - Crea y edita archivos Markdown
- Estilos avanzados - Personaliza la apariencia de los paneles