Cómo crear tu OpenClass

Tu ruta de trabajo

El proceso recomendado: crear un curso, editar sus semanas en Markdown y comprobar el resultado en el navegador.

Requisitos de instalación

Solo necesitas Node.js (incluye npm), un editor de texto y un navegador moderno. No hace falta saber React.

• Node.js 20.19 o posterior (recomendado: la versión LTS de nodejs.org). npm se instala junto con Node.js.
• Editor: Visual Studio Code u otro editor de texto plano.
• Navegador: Chrome, Edge o Firefox actualizados.
• Git (opcional): solo para publicar en GitHub Pages.

node -v    # debe mostrar v20.19.0 o superior
npm -v

Instalación y creación de un curso

Un único comando descarga el generador desde npm y crea una carpeta nueva con el curso completo. No crees cursos dentro de otro proyecto.

npm create openclass-uniminuto-revealjs@latest mi-curso
cd mi-curso
npm install
npm run dev

npm run dev abre el portal en http://localhost:8600/. Si ese puerto está ocupado, usa npm run dev -- --port 8610.

Con los fondos y logotipos institucionales

El paquete público trae un tema neutro con la misma composición. Si tu institución te entregó la carpeta de recursos institucionales, aplícala al crear el curso (o después, con --update-theme):

npm create openclass-uniminuto-revealjs@latest mi-curso -- --assets "RUTA\recursos-institucionales"

--assets solo copia imágenes (png, jpg, webp, svg) sobre public/, con los mismos nombres de archivo. No publiques esos recursos si no tienes autorización.

Otras opciones del generador

npx create-openclass-uniminuto-revealjs@latest --help          # ayuda
npx create-openclass-uniminuto-revealjs@latest mi-curso --iot  # nombre inicial «Introducción a Internet de las Cosas»
npx create-openclass-uniminuto-revealjs@latest mi-curso --install  # crea e instala dependencias

¿Qué encontrarás al abrir el portal?

Acceso a la presentación general, semanas activas, demostración de layouts, laboratorio y esta guía. Las semanas se muestran según generation.activeWeeks.

Carpetas y archivos que sí debes editar

El contenido académico permanece separado del código React y de los fondos institucionales.

mi-curso-iot/
├── openclass.config.json          # Datos del curso y semanas activas
├── slides.md                      # Presentación general
├── semanas/
│   └── micursoiot_semana1.md      # Contenido de Semana 1
├── plantillas/semana.md           # Base para semanas nuevas
├── demo-completa.md               # Demostración «TEMÁTICA DE PRUEBA» (referencia)
├── docs/
│   ├── GUIA-DOCENTE.md            # Resumen de esta guía
│   └── IA/                        # Instrucciones, plantilla y prompt para IA
├── public/
│   ├── imagenes/                 # Fotografías y diagramas
│   ├── videos/                   # Vídeos locales y subtítulos .vtt
│   ├── actividades/              # Microactividad, quiz y simuladores HTML
│   ├── galeria/                  # Vistas previas de los 13 layouts
│   └── fondos/                   # Fondos de portada, internas y cierre
├── src/theme.css                  # Tema aprobado (evita modificarlo)
├── guia/index.html                # Esta página
├── galeria/                       # Galería de layouts (/galeria/)
└── dist/                          # Se genera después del build

Los proyectos de Slidev y openclass-prueba-reveal son independientes. No copies node_modules ni dist desde ellos.

Configura nombre, periodo y semanas

Edita openclass.config.json con un editor de texto como VS Code. No elimines claves existentes.

{
  "course": {
    "shortName": "micursoiot",
    "fullName": "Internet de las Cosas",
    "year": "2026",
    "description": "OpenClass de sensores, conectividad y aplicaciones"
  },
  "generation": {
    "weeksTotal": 8,
    "activeWeeks": [1, 2],
    "overwriteWeekContent": false
  }
}

Modifica weeks[n].title, date, centralTheme y activity para ajustar la semana correspondiente.

Al portal publicado solo llegan course.fullName, description, year y el título y el tema de las semanas activas; las semanas que no están en activeWeeks no se publican. La activación de cada semana se define en weeks[].opening (ver Diseñar la semana).

Activa y desarrolla las ocho semanas

Cada semana usa un Markdown propio y una ruta dentro del portal. Tus cambios académicos no se sobrescriben al regenerar los accesos.

npm run semana -- 2 --title "Sensores y actuadores" --date "2026-11-04" --theme "Medición y control"
npm run config
npm run dev -- --port 8610

El comando crea (si no existe) semanas/micursoiot_semana2.md y activa su enlace en el portal. Edita allí el contenido. Para una semana ya existente, evita --force-content: esa opción sí puede reemplazar el Markdown.

npm run semana -- 3 --title "Comunicación IoT" --date "2026-11-11"
# Abrir luego /semanas/micursoiot_semana3/

Modificar una semana existente

Abre semanas/<curso>_semanaN.md en VS Code, edita y guarda: con npm run dev abierto, el navegador se actualiza solo. Para cambiar el título o la fecha que muestra el portal, edita weeks[N-1] en openclass.config.json o vuelve a ejecutar npm run semana -- N --title "…" (el Markdown se conserva).

Modificar la presentación general

La presentación general del curso está en slides.md y se abre en /general/. Sigue las mismas reglas de Markdown y layouts que las semanas; preséntala en la primera sesión (objetivos, metodología, evaluación).

Diseña la semana: apertura, recorridos y continuidad

Antes de redactar las diapositivas, define qué aprenderán los estudiantes, cómo participarán en cada recorrido y qué evidencias mostrarán. Este capítulo resume el contrato pedagógico que también siguen los archivos de docs/IA/.

1. Ruta de la semana

El portal muestra solo las semanas publicadas (generation.activeWeeks), en orden, con su número, título y tema. Dentro de cada presentación, después de la activación, incluye una diapositiva oc-l-text «Ruta de la semana» que responda:

• Qué se aprenderá: el tema y los resultados de aprendizaje que tú defines (no inventes resultados institucionales).
• Cómo se relaciona con las semanas anteriores.
• Qué conceptos y problemas se abordarán: el caso conductor.
• Cómo participar en cada recorrido.
• Qué podrá demostrar el estudiante al finalizar.
• Cómo consultar la presentación después: queda publicada en el portal del curso.

## Ruta de la semana
<!-- .slide: class="oc-demo oc-l-text" data-background-image="{{BASE_URL}}fondos/slide-05-template.png" data-background-size="cover" -->

Esta semana estudiamos la comunicación entre servicios a partir de un caso de pagos en línea.

- **Venimos de:** la semana 2, donde definimos qué es un servicio.
- **Problema:** ¿qué pasa si un servicio deja de responder?
- **Cómo participar:** sesión por Zoom o Teams, recorrido guiado o estudio autónomo.
- **Al finalizar podrás:** explicar cuándo conviene un mensaje síncrono o uno asíncrono.
- **Para repasar:** esta presentación sigue disponible en el portal del curso.

Notes:
Propósito: ubicar la semana en la ruta del curso. Tiempo: 2 minutos. Transición: presentar el caso.

2. Portada, tema y dinámica de apertura

npm run semana -- N genera las tres primeras diapositivas desde openclass.config.json: portada (course.fullName, «SEMANA N», título y fecha), tema central (centralTheme) y activación. Define la activación en weeks[].opening antes de generar la semana:

{
  "number": 3,
  "title": "Comunicación entre servicios",
  "centralTheme": "Mensajes, colas y eventos",
  "opening": {
    "question": "¿Qué ocurre en una tienda en línea si el servicio de pagos tarda un minuto en responder?",
    "participation": "hipotesis-grupal",
    "durationMinutes": 2
  }
}

durationMinutes es un número entre 1 y 3, y question es texto sin enlaces ni etiquetas. Sin opening, la pregunta es «¿Qué sabes ya sobre …?» con el tema central (individual, 2 minutos). Si algún opening es inválido, el comando no genera ninguna semana y explica el error.

3. Actividades para Zoom o Teams

• Toda instrucción se realiza dentro de la reunión: chat, micrófono, reacciones o salas de grupos.
• Cada función opcional (reacciones, salas de grupos) lleva una alternativa por chat u oral.
• Indica la duración y cómo cierras: recoge dos o tres respuestas y conéctalas con el tema.
• Las actividades HTML locales se comparten en pantalla o cada estudiante las abre desde el portal; no envían resultados a Moodle ni a ningún servidor.

4. Tres recorridos complementarios

Los tres comparten resultados de aprendizaje y continuidad semanal; resúmelos en una diapositiva oc-l-two-cols. El portal los presenta como sugerencias de estudio: no los describas como modalidades institucionales oficiales. La modalidad registrada del programa es la que indica la institución.

5. Conceptos con fuentes verificables

Presenta cada concepto a partir de un problema o ejemplo, con descubrimiento progresivo (preguntas y fragmentos), y después formaliza: definición, modelo, fórmula o procedimiento. Usa fuentes oficiales, académicas y actuales, y anota en las Notes la fecha de consulta y la versión. Lo que no puedas verificar queda como «PENDIENTE DE VERIFICAR» y no se incrusta.

6. Videos: de cero a tres por semana

• Cada video dura de 5 a 10 minutos, preferiblemente en español, y ocupa su propia diapositiva oc-l-multimedia (sintaxis en Imágenes y video).
• Verifica título, canal, duración, idioma, disponibilidad y URL.
• Antes, una pregunta; durante, qué observar; después, una actividad de recuperación. Prevé una alternativa si el video no está disponible.
• Los videos no ocupan la sesión: la mayor parte del tiempo es explicación, práctica y evaluación.

7. Elaborar y verificar actividades

Incluye una microactividad de 5 a 10 minutos (ver Actividades) y una evaluación formativa: pregunta de repaso, ticket de salida o cuestionario breve. Antes de la clase resuélvela tú: revisa las instrucciones, la retroalimentación de cada opción, el uso con teclado y el tiempo real.

8. Notes: guion docente público

Las Notes son tu guion: propósito, pregunta guía, tiempo, transición, explicación académica, ejemplos adicionales y errores frecuentes. Se ven con la tecla S, pero viajan en el mismo archivo que la presentación publicada: cualquiera puede leerlas.

9. Compilar, probar y preparar el material para estudiantes

npm run test:estructura
npm run build:all
npm run preview:pages

Recorre la semana completa en la vista previa, revisa la consola del navegador, abre cada enlace y cada video y atiende cada «PENDIENTE». Después publica (ver Validar, compilar y publicar) y comparte con los estudiantes el enlace del portal: entrarán por «Comenzar aquí» y seguirán la ruta de semanas publicadas.

Escribe las diapositivas con Markdown

Cada bloque entre separadores --- es una diapositiva. El comentario .slide: asigna el layout y el fondo.

# Internet de las Cosas
<!-- .slide: class="oc-demo oc-l-cover" data-background-image="{{BASE_URL}}fondos/slide-01-portada.png" data-background-size="cover" -->

**SEMANA 1**

2026

---

## Resultados de aprendizaje
<!-- .slide: class="oc-demo oc-l-objectives" data-background-image="{{BASE_URL}}fondos/slide-05-template.png" data-background-size="cover" -->

1. Reconocer sensores y actuadores.
2. Explicar una red de objetos conectados.
3. Proponer una solución aplicada.

Notes:
Dar un ejemplo contextualizado antes de comenzar.

Reglas útiles

• # se usa como título principal; ##, para los demás.
• **texto** pone énfasis; - elemento crea viñetas; 1. crea listas numeradas.
• Notes: introduce notas privadas para la vista del presentador.
• Los fondos y rutas de recursos deben utilizar {{BASE_URL}} para funcionar en subcarpetas de despliegue.

Los 13 layouts institucionales

Selecciona el layout según el contenido, sin cambiar la tipografía ni las franjas aprobadas. Cada miniatura es una captura real; ábrela para ver su ficha y copiar el código.

PortadaSeparadorResultadosImagen izquierdaImagen derechaSuperior derechoSuperior izquierdoTextoDos columnasDos títulosMultimediaCódigoCierre

## Arquitectura de un sistema IoT
<!-- .slide: class="oc-demo oc-l-image-right" data-background-image="{{BASE_URL}}fondos/slide-05-template.png" data-background-size="cover" -->

![Arquitectura de IoT]({{BASE_URL}}imagenes/arquitectura-iot.png)

- Percepción: sensores.
- Conectividad: Wi-Fi o LoRaWAN.
- Aplicaciones: visualización y alertas.

Imágenes, videos y recursos institucionales

Los recursos locales se copian a public/ y se referencian desde Markdown. Así pueden publicarse junto al curso.

![Sensor de temperatura]({{BASE_URL}}imagenes/sensor-dht22.png)

<video controls preload="metadata" src="{{BASE_URL}}videos/demostracion.mp4">
  <track kind="captions" src="{{BASE_URL}}videos/demostracion.vtt" srclang="es" label="Español" default>
</video>

Imágenes paso a paso

1. Copia el archivo a public/imagenes/ con un nombre sin espacios ni tildes (sensor-dht22.png).
2. Usa un layout de imagen (oc-l-image-left, oc-l-image-right, oc-l-top-left u oc-l-top-right).
3. Escribe la imagen antes de la lista, con un texto alternativo que describa lo que muestra.

Video

El video va solo en una diapositiva oc-l-multimedia y ocupa toda el área útil sin recortarse. Prefiere WebM o MP4 de menos de 50 MB y agrega subtítulos .vtt. Para YouTube usa la dirección de inserción:

<iframe title="Video de la clase" src="https://www.youtube-nocookie.com/embed/ID_DEL_VIDEO" allowfullscreen style="width:100%;height:100%;border:0"></iframe>

Incluir un iframe

Cualquier página que permita incrustarse puede mostrarse en oc-l-multimedia con un <iframe> de width:100%;height:100%. Para HTML propios en public/actividades/ añade sandbox="allow-scripts allow-forms". Si el sitio bloquea la incrustación verás un recuadro vacío: enlázalo con target="_blank".

Fondos y logotipos

No renombres los fondos: la portada usa slide-01-portada.png, las internas slide-05-template.png y el cierre slide-06-cierre.png; el bloque inferior derecho de la portada usa imagenes/acreditacion-openclass.png. El paquete público incluye versiones neutras con esos nombres; los recursos institucionales se aplican con --assets y solo deben publicarse con autorización.

Mostrar código: scroll o paginado

El layout oc-l-code resalta la sintaxis, conserva sangrías y añade el botón Copiar código. Tiene dos modos.

## Programa completo (scroll)
<!-- .slide: class="oc-demo oc-l-code" data-background-image="{{BASE_URL}}fondos/slide-05-template.png" data-background-size="cover" -->

```python
# … tantas líneas como necesites …
```

---

## Programa por partes (paginado)
<!-- .slide: class="oc-demo oc-l-code" data-background-image="{{BASE_URL}}fondos/slide-05-template.png" data-background-size="cover" data-oc-paginate="code" -->

```javascript
// … programa extenso …
```

Resaltar por pasos: escribe los rangos después del lenguaje, por ejemplo ```python [1-3|5-8]; cada avance ilumina un grupo de líneas. La paginación de código no afecta al texto: para listas largas existe data-oc-paginate="auto".

Inserta actividades, simuladores y cuestionarios

El layout multimedia muestra actividades a gran tamaño. Los HTML locales se ejecutan dentro de un iframe aislado.

## Pregunta de repaso
<!-- .slide: class="oc-demo oc-l-multimedia" data-background-image="{{BASE_URL}}fondos/slide-05-template.png" data-background-size="cover" -->

<iframe title="Pregunta de repaso" src="{{BASE_URL}}actividades/quiz-iot.html"
        loading="lazy" sandbox="allow-scripts allow-forms"
        style="width:100%;height:100%;border:0"></iframe>

Microactividad de 5 a 10 minutos

En public/actividades/microactividad/ hay una actividad de clasificación con objetivo, instrucciones, validación, retroalimentación por respuesta, resultado observable, reinicio, cronómetro orientativo y acceso por teclado. Para cambiar el tema:

1. Copia la carpeta con otro nombre, por ejemplo public/actividades/clasificar-sensores/.
2. Edita solo datos.js: título, objetivo, minutos, categorías (2 a 5) y elementos con su explicación.
3. Insértala con un iframe en oc-l-multimedia:

<iframe title="Clasificar sensores" src="{{BASE_URL}}actividades/clasificar-sensores/index.html" loading="lazy" sandbox="allow-scripts allow-forms" style="width:100%;height:100%;border:0"></iframe>

Alternativas

Diagramas, gráficos y fórmulas

Utiliza los lenguajes y componentes ya incluidos en la plantilla, en lugar de capturas de pantalla de baja resolución.

Mermaid

```mermaid
flowchart LR
  S[Sensor] --> C[ESP32]
  C --> N[(Nube)]
  N --> D[Dashboard]
```

Chart.js

<div class="oc-chart"><canvas data-chart="bar">
Lectura,Lun,Mar,Mié,Jue,Vie
Temperatura (°C),21,23,26,24,22
Humedad (%),60,58,65,70,66
</canvas></div>

KaTeX

Fórmula en línea: $V = I \cdot R$

$$F = \frac{9}{5}C + 32$$

Construir una semana con IA

Cada curso incluye tres archivos en docs/IA/ para que ChatGPT, Claude, Codex u otra IA redacten una semana compatible con OpenClass, sin inventar clases ni recursos.

1. Completa docs/IA/PLANTILLA-SEMANAL.md con tu material (pega textos o adjunta documentos).
2. Copia el prompt de PROMPT-CREAR-SEMANA.md en la IA y adjunta las instrucciones, la plantilla y el material.
3. Si la IA propone un bloque opening, cópialo en weeks[] de openclass.config.json.
4. Crea la semana: npm run semana -- 3 --title "Sensores". Si el archivo ya existía, aún sin contenido elaborado, y cambiaste opening, añade --force-content (reemplaza el archivo completo de la semana 3).
5. Conserva las tres diapositivas generadas y pega desde la cuarta el Markdown de la IA; los solucionarios van a docente/solucionarios/.
6. Ejecuta npm run dev, revisa cada «PENDIENTE» y verifica cada enlace y video (ver Diseñar la semana).

Barra docente y atajos de presentación

Las herramientas están integradas al pie institucional, con acceso a pizarra, anotaciones y navegación.

El logotipo central del pie funciona como botón Volver al inicio y presenta una animación discreta. En portada se ocultan Home y este botón para respetar la composición. Utiliza las flechas, la barra espaciadora o un control remoto para avanzar o retroceder.

Vista del presentador: Build Tech

El botón del presentador ofrece dos vistas. Build Tech (T) abre una cabina privada en otra ventana, para tu segundo monitor: tus notas (Notes:) en letra grande con el punto de lectura resaltado, la diapositiva actual y la siguiente, la hora, el tiempo de clase (45, 60, 90 minutos o el que elijas; al terminar solo avisa), los controles de video y audio, la solución privada de cada pregunta y, si usas OpenClass Live, la votación y las preguntas de los estudiantes. Todo se ejecuta en la presentación compartida; Build Tech nunca se proyecta. Las notas clásicas de Reveal.js (S) siguen disponibles. Si la ventana no se abre, permite las ventanas emergentes para el sitio. Comparte en la videollamada solo la pestaña de la presentación.

En las notas puedes marcar el punto de lectura con [[0]], [[1]]… (fragmentos mostrados) y anclar una nota a un elemento con data-oc-nota="mapa" y [[#mapa]]; con [[#video:reproducir]] la nota ofrece un botón para ese video. Nada se ejecuta solo: tú pulsas.

Exportar a PDF

Reveal.js genera una página horizontal 16:9 por diapositiva desde el propio navegador, sin notas, soluciones, QR ni controles.

1. Pulsa el botón de impresora Exportar a PDF del pie azul: se abre una pestaña con todas las diapositivas de la semana (equivale a añadir ?print-pdf a la dirección).
2. Cuando termina de prepararse se abre el diálogo de impresión (o pulsa Ctrl + P en Chrome o Edge).
3. Destino: Guardar como PDF; márgenes: Ninguno; activa Gráficos de fondo. El navegador decide dónde se guarda.

Validar, compilar y publicar

El sitio se compila como HTML/CSS/JS estático. Publica dist/, nunca el servidor de desarrollo Vite.

npm run test:estructura
npm run pages:check
npm run pages:build
npm run preview:pages

Publicar en GitHub Pages

1. Crea un repositorio en GitHub y sube el curso (sin node_modules ni dist; el .gitignore incluido ya los excluye).
2. En el repositorio: Settings → Pages → Source: GitHub Actions.
3. Cada push a main ejecuta .github/workflows/deploy.yml: instala, compila con la base /<nombre-del-repositorio>/ y publica dist/.
4. Abre https://<usuario>.github.io/<repositorio>/ y comprueba portal, semanas, imágenes y actividades.

La variable SITE_BASE determina el prefijo de ruta; los ejemplos de Markdown usan {{BASE_URL}} precisamente para respetarlo.

El comando npm run publicar ejecuta Git (add, commit y push): no lo ejecutes hasta revisar el repositorio y confirmar que quieres publicar esos cambios.

Actualizar sin perder las clases redactadas

El generador rechaza carpetas no vacías. Para actualizar infraestructura, utiliza únicamente su opción segura sobre cursos OpenClass Reveal.js reconocidos.

# Desde la carpeta que contiene el curso:
npx create-openclass-uniminuto-revealjs@latest mi-curso-iot --update-theme
# (añade --assets "RUTA\recursos-institucionales" para reaplicar los recursos locales)

# Luego entra al curso y comprueba:
Set-Location '..\mi-curso-iot'
npm install
npm run test:estructura
npm run pages:build

Graphify es opcional para el mantenimiento técnico; no forma parte del flujo obligatorio para redactar semanas.

Errores comunes y cómo resolverlos

Estas son las incidencias que más se repiten al crear una OpenClass.

Encuestas, preguntas y participación en vivo

La estructura incluye Seminar, Poll y Questions, pero permanecen desactivados para no simular interacción multiusuario inexistente.

Para activarlos se necesita un servidor de tiempo real compatible, conexiones seguras HTTPS/WSS, salas, autenticación o tokens, moderación y protección contra abuso. Zoom puede funcionar como canal de videollamada mientras OpenClass se abre como web interactiva, pero una integración embebida en Zoom requiere un proyecto y validación propios.

OpenClass 1.2.0: Build Tech permite notas, relojes y controles multimedia; la exportación PDF se abre desde el pie de la presentación. El adaptador OpenClass Live v0.2 permanece apagado por defecto y exige un servicio separado con protocolo v2. No activarlo contra un servidor v0.1. Al crear encuestas solo se envían enunciado, código, tipo y opciones; las respuestas correctas y la explicación permanecen locales hasta la revelación explícita. Zoom embebido sigue pendiente.