2.2. Desarrollo Local

Flujo de trabajo de desarrollo local

Previsualiza cambios localmente antes de publicar. Control total sobre el proceso de construcción.

Descripción general

Este flujo de trabajo es mejor para desarrolladores y usuarios que quieren previsualizar cambios localmente antes de publicar. Trabajarás con archivos directamente en tu computadora y ejecutarás Jekyll localmente.

Requisitos previos

Ruby 3.0+ (para Jekyll)
Bundler
Python 3.9+ (para generación IIIF)

Instalación

Instala Ruby y Bundler

macOS (usando Homebrew):

brew install ruby
gem install bundler

Ubuntu/Debian:

sudo apt-get install ruby-full build-essential
gem install bundler

Clona y configura

# Clona el repositorio
git clone https://github.com/UCSB-AMPLab/telar.git
cd telar

# Instala dependencias de Ruby
bundle install

# Instala dependencias de Python (para generación IIIF)
pip install -r requirements.txt

Configura ajustes del sitio

Edita _config.yml:

title: Título de tu Narrativa
description: Una breve descripción
baseurl: "/nombre-de-tu-repositorio"  # Para GitHub Pages, o "" para dominio raíz
url: "https://tu-usuario.github.io"
author: Tu Nombre
email: tu-email@ejemplo.com

Comandos principales

A lo largo de tu flujo de trabajo, usarás estos comandos:

# Convierte CSVs a JSON (ejecuta después de editar CSVs)
python3 scripts/csv_to_json.py

# Genera tiles IIIF (ejecuta después de agregar/actualizar imágenes)
python3 scripts/generate_iiif.py --source-dir components/images/objects --base-url http://localhost:4000

# Sirve con recarga automática
bundle exec jekyll serve --livereload

# Ver en http://localhost:4000

Flujo de trabajo paso a paso

Paso 1: reúne tus imágenes

Elige una de dos opciones:

Opción A: sube tus propias imágenes

Agrega imágenes de alta resolución al directorio components/images/objects/
Nombra archivos para que coincidan con IDs de objeto (ej., textile-001.jpg)

Genera tiles IIIF:

python3 scripts/generate_iiif.py --source-dir components/images/objects --base-url http://localhost:4000

Opción B: usa manifiestos IIIF externos

Encuentra recursos IIIF (Guía IIIF)
Copia la URL info.json
Crea un object_id (ej., museum-textile-001)
Guarda para el siguiente paso

Paso 2: escribe tu texto narrativo

Crea archivos markdown para las capas de tu historia:

Crea directorio para tu historia:

mkdir -p components/texts/stories/story1

Crea archivos markdown (ej., paso1-capa1.md, paso1-capa2.md)

Agrega frontmatter y contenido:

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

El patrón de urdimbre entrelazada visible aquí indica...

Paso 3: cataloga tus objetos

Agrega metadatos al catálogo de objetos:

Edita components/structures/objects.csv
Agrega una fila para cada objeto:

Para imágenes subidas:

textile-001,Fragmento de Textil Colonial,"Un textil tejido de...",Artista Desconocido,circa 1650-1700,Lana,45 x 60 cm,,,

Para IIIF externo:

museum-textile-001,Fragmento de Textil Colonial,"Un textil tejido de...",Artista Desconocido,circa 1650-1700,Lana,45 x 60 cm,,https://example.org/iiif/image/abc123/info.json,

Convierte a JSON:
```
python3 scripts/csv_to_json.py
```

Paso 4: previsualiza tus objetos

Construye y ve tu sitio:

bundle exec jekyll serve --livereload

Luego:

Visita http://localhost:4000
Haz clic en “Objects” en la navegación
Verifica que todas las imágenes aparezcan con sus metadatos

Paso 5: encuentra coordenadas para momentos de historia

Usa la herramienta de identificación de coordenadas:

Navega a una página de objeto: http://localhost:4000/objects/{object_id}
Haz clic en el botón Identify coordinates
Desplaza y amplía al área que quieres destacar
Haz clic en Copy entire row para plantilla CSV con coordenadas

Paso 6: construye tu historia

Conecta tu narrativa a tus objetos:

Crea archivo CSV en components/structures/ (ej., story-1.csv)

Agrega fila de encabezado:

step,question,answer,object,x,y,zoom,layer1_button,layer1_file,layer2_button,layer2_file

Agrega pasos de historia:

1,"¿Qué es este textil?","Este fragmento muestra...","textile-001",0.5,0.5,1.0,"","story1/paso1-capa1.md","",""
2,"Nota el patrón","Los motivos geométricos...","textile-001",0.3,0.4,2.5,"","story1/paso2-capa1.md","",""

Agrega a configuración del proyecto:
- Edita components/structures/project.csv
- Desplázate a la sección STORIES
- Agrega fila: 1,Título de tu Historia
Convierte a JSON:
```
python3 scripts/csv_to_json.py
```
Reconstruye y prueba:
```
bundle exec jekyll serve
```

Paso 7: agrega términos del glosario (opcional)

Mejora tu narrativa con definiciones de términos:

Crea archivo markdown en components/texts/glossary/ (ej., periodo-colonial.md)

Agrega frontmatter y definición:

---
term_id: periodo-colonial
title: "Período Colonial"
related_terms: encomienda,virreinato
---

El Período Colonial en las Américas comenzó con...

Genera colección:

python3 scripts/generate_collections.py

Construye y prueba:
```
bundle exec jekyll serve
```

Flujo de trabajo de desarrollo diario

Cuando trabajes en tu sitio:

# 1. Edita contenido
# - CSVs en components/structures/
# - Markdown en components/texts/
# - Imágenes en components/images/objects/

# 2. Convierte CSVs a JSON (después de editar CSVs)
python3 scripts/csv_to_json.py

# 3. Genera tiles IIIF (después de agregar/actualizar imágenes)
python3 scripts/generate_iiif.py --source-dir components/images/objects --base-url http://localhost:4000

# 4. Sirve con recarga automática
bundle exec jekyll serve --livereload

# Comandos adicionales:
# Construir solamente (salida a _site/)
bundle exec jekyll build

# Limpiar artefactos de construcción
bundle exec jekyll clean

Publicación en GitHub Pages

Una vez que estés satisfecho con tu sitio local:

Confirma y empuja cambios a GitHub:

git add .
git commit -m "Actualizar contenido"
git push origin main

GitHub Actions construirá y publicará automáticamente
Ve tu sitio en vivo en https://[usuario].github.io/[repositorio]/