create-openclass-uniminuto 1.6.1 → 1.6.4

package/template/README.md

@@ -1,326 +1,654 @@
-# Open Class UNIMINUTO · Slidev
+# Open Class UNIMINUTO Template
 
-Proyecto generado con `create-openclass-uniminuto` o creado desde la plantilla `openclass-uniminuto-template`.
+Plantilla base para construir presentaciones académicas tipo **Open Class** con Slidev, tema institucional UNIMINUTO, semanas independientes, portal principal, exportación a PDF/PPTX y despliegue automático en GitHub Pages.
 
-Este curso está diseñado para organizar una Open Class de **8 semanas**, con generación progresiva de cada semana, portal principal, lanzadores individuales, exportación de PDF/PPTX y publicación automática en **GitHub Pages**.
+Esta plantilla está pensada para cursos universitarios organizados por semanas. Cada semana se desarrolla como una presentación Slidev independiente, pero todas se integran en un portal principal generado automáticamente.
 
 ---
 
+## 1. ¿Qué contiene esta plantilla?
 
-## Crear el curso dentro de un repositorio ya creado en GitHub
+La estructura general del proyecto es:
 
-Si primero creaste el repositorio en GitHub, clónalo y aplica la plantilla desde npm dentro de la carpeta del repositorio:
+```text
+.
+├─ .github/
+│  └─ workflows/
+│     └─ deploy.yml
+├─ openclass.config.json
+├─ package.json
+├─ slides.md
+├─ plantillas/
+│  ├─ launcher.md
+│  └─ semana.md
+├─ public/
+│  ├─ favicon.png
+│  ├─ fondos/
+│  ├─ imagenes/
+│  ├─ descargas/
+│  └─ videos/
+├─ scripts/
+│  ├─ generar-desde-config.mjs
+│  ├─ semana.mjs
+│  ├─ decks.mjs
+│  ├─ build-site.mjs
+│  ├─ export-downloads.mjs
+│  ├─ preparar-github-pages.mjs
+│  ├─ publicar.mjs
+│  └─ nuevo-curso.mjs
+├─ semanas/
+└─ theme/
+   └─ uniminuto/
+```
 
-```bash
-git clone https://github.com/herrerawilliamh/openclass-iot.git
-cd openclass-iot
-npm create openclass-uniminuto@latest . -- --iot
-npm install
-npm run semana -- 1
-npm run dev
+---
+
+## 2. Recursos visuales obligatorios
+
+El tema institucional requiere estos archivos:
+
+```text
+public/fondos/slide-01-portada.png
+public/fondos/slide-05-template.png
+public/fondos/slide-06-cierre.png
+public/imagenes/avion.png
+public/imagenes/favicon.png
+public/favicon.png
 ```
 
-Si el repositorio ya tenía archivos iniciales y deseas reemplazarlos por los de la plantilla:
+`public/favicon.png` se usa como favicon del navegador.
 
-```bash
-npm create openclass-uniminuto@latest . -- --iot --force
+`public/imagenes/favicon.png` puede usarse como imagen institucional dentro de las diapositivas.
+
+Las imágenes académicas propias de cada curso deben ubicarse preferiblemente en:
+
+```text
+public/imagenes/
+```
+
+---
+
+## 3. Concepto general de funcionamiento
+
+La fuente principal de configuración es:
+
+```text
+openclass.config.json
 ```
 
-La sincronización con GitHub se hace después con Git:
+Desde ese archivo se definen:
+
+* Nombre corto del curso.
+* Nombre completo del curso.
+* Descripción general.
+* Número total de semanas.
+* Semanas activas.
+* Título, fecha, tema y actividad de cada semana.
+
+Las semanas activas se controlan en:
+
+```json
+"generation": {
+  "activeWeeks": [1, 2, 3]
+}
+```
+
+Solo las semanas incluidas en `activeWeeks` aparecen en el portal, se exportan y se construyen para GitHub Pages.
+
+---
+
+## 4. Archivos principales
+
+### `slides.md`
+
+Portal principal del curso. Se genera automáticamente con:
 
 ```bash
-git add -A
-git commit -m "Configura Open Class"
-git push
+npm run config
+```
+
+No se recomienda editarlo manualmente, porque puede ser reemplazado por el generador.
+
+### `curso_semanaN.md`
+
+Archivo lanzador de cada semana. Incluye la configuración global de Slidev y referencia el contenido real desde `semanas/`.
+
+Ejemplo:
+
+```text
+demo_semana1.md
+```
+
+### `semanas/curso_semanaN.md`
+
+Contenido académico real de la semana.
+
+Ejemplo:
+
+```text
+semanas/demo_semana1.md
+```
+
+Este archivo no se sobrescribe por defecto. Eso permite conservar el contenido diseñado por el docente.
+
+### `plantillas/semana.md`
+
+Plantilla base usada al crear una semana nueva. Debe incluir ejemplos de todos los layouts disponibles para que funcione como catálogo inicial.
+
+### `plantillas/launcher.md`
+
+Plantilla del archivo lanzador raíz de cada semana.
+
+---
+
+## 5. Caso de uso 1: crear un curso desde GitHub Template
+
+Este caso se recomienda cuando se quiere iniciar un curso directamente desde GitHub.
+
+### Paso 1. Crear repositorio desde la plantilla
+
+En GitHub:
+
+```text
+Use this template → Create a new repository
 ```
 
+Nombre sugerido:
 
-## 1. Primer uso
+```text
+openclass-nombrecurso
+```
 
-Instala dependencias:
+Ejemplos:
+
+```text
+openclass-iot
+openclass-bigdata
+openclass-gestionseguridad
+```
+
+### Paso 2. Clonar el repositorio
+
+```bash
+git clone https://github.com/TU_USUARIO/openclass-nombrecurso.git
+cd openclass-nombrecurso
+```
+
+### Paso 3. Instalar dependencias
 
 ```bash
 npm install
 ```
 
-Configura el curso desde consola:
+### Paso 4. Editar `openclass.config.json`
+
+Cambiar:
+
+```json
+{
+  "course": {
+    "shortName": "nombrecurso",
+    "fullName": "Nombre completo del curso",
+    "year": "2026",
+    "description": "Descripción general del curso.",
+    "openClassLabel": "Open Class"
+  }
+}
+```
+
+### Paso 5. Generar estructura del curso
 
 ```bash
-npm run nuevo
+npm run config
 ```
 
-Genera la primera semana:
+### Paso 6. Activar semanas
 
 ```bash
 npm run semana -- 1
+npm run semana -- 2
+npm run semana -- 3
 ```
 
-Ejecuta el portal principal:
+### Paso 7. Probar localmente
 
 ```bash
 npm run dev
 ```
 
-Una semana específica se abre con:
+Para una semana específica:
 
 ```bash
 npm run dev:s1
-npm run dev:s2
-npm run dev:s3
+```
+
+### Paso 8. Construir para GitHub Pages
+
+```bash
+npm run pages:build
+```
+
+### Paso 9. Publicar
+
+```bash
+git add -A
+git commit -m "Publicación inicial Open Class"
+git push
+```
+
+En GitHub:
+
+```text
+Settings → Pages → Build and deployment → Source: GitHub Actions
 ```
 
 ---
 
-## 2. Tres formas de crear este curso
+## 6. Caso de uso 2: crear un curso con npm
+
+Este caso se recomienda cuando se quiere crear el curso desde consola usando el generador publicado en npm.
 
-### Opción A · Desde npm
+### Paso 1. Crear carpeta del curso
 
 ```bash
-npm create openclass-uniminuto@latest openclass-iot -- --iot
-cd openclass-iot
-npm install
-npm run semana -- 1
-npm run dev
+mkdir openclass-nombrecurso
+cd openclass-nombrecurso
 ```
 
-### Opción B · Desde GitHub Template
+### Paso 2. Ejecutar el generador
+
+```bash
+npm create openclass-uniminuto@latest .
+```
 
-1. Entra al repositorio `openclass-uniminuto-template`.
-2. Clic en **Use this template**.
-3. Crea un repositorio nuevo, por ejemplo `openclass-iot`.
-4. Clónalo.
-5. Ejecuta los comandos del curso.
+### Paso 3. Instalar dependencias
 
 ```bash
-git clone https://github.com/herrerawilliamh/openclass-iot.git
-cd openclass-iot
 npm install
-npm run nuevo
-npm run semana -- 1
-npm run dev
 ```
 
-### Opción C · Repo creado en GitHub y curso generado en local
+### Paso 4. Configurar el curso
 
-Esta opción combina GitHub y npm.
+Puedes editar manualmente:
 
-#### Si el repositorio fue creado desde plantilla
+```text
+openclass.config.json
+```
+
+o ejecutar:
 
 ```bash
-git clone https://github.com/herrerawilliamh/openclass-iot.git
-cd openclass-iot
-npm install
 npm run nuevo
-npm run semana -- 1
-npm run dev
 ```
 
-Luego:
+### Paso 5. Generar curso
 
 ```bash
-git add -A
-git commit -m "Generar semana 1"
-git push
+npm run config
 ```
 
-#### Si el repositorio está vacío
+### Paso 6. Probar y construir
 
 ```bash
-npm create openclass-uniminuto@latest openclass-iot -- --iot
-cd openclass-iot
-npm install
-npm run semana -- 1
 npm run dev
+npm run pages:build
 ```
 
-Después conecta el remoto:
+### Paso 7. Crear repositorio remoto
 
 ```bash
 git init
 git branch -M main
+git remote add origin https://github.com/TU_USUARIO/openclass-nombrecurso.git
 git add -A
 git commit -m "Publicación inicial Open Class"
-git remote add origin https://github.com/herrerawilliamh/openclass-iot.git
 git push -u origin main
 ```
 
 ---
 
-## 3. Generar semanas una a una
+## 7. Caso de uso 3: crear desde GitHub Template y sincronizar con npm
+
+Este caso se recomienda cuando ya existe un repositorio creado desde la plantilla de GitHub, pero se quiere actualizar después con la versión más reciente publicada en npm.
+
+### Paso 1. Crear el repositorio desde GitHub Template
 
-El curso siempre se organiza en **8 semanas**. Puedes generarlas progresivamente.
+Usar:
+
+```text
+Use this template → Create a new repository
+```
+
+### Paso 2. Clonar localmente
 
 ```bash
-npm run semana -- 1
-npm run semana -- 2 --title "Título de la semana 2" --date "Junio 15 de 2026"
-npm run semana -- 3 --title "Título de la semana 3" --theme "Tema central"
+git clone https://github.com/TU_USUARIO/openclass-nombrecurso.git
+cd openclass-nombrecurso
+```
+
+### Paso 3. Instalar dependencias
+
+```bash
+npm install
+```
+
+### Paso 4. Actualizar infraestructura desde npm
+
+```bash
+npm create openclass-uniminuto@latest . -- --update-theme
 ```
 
-El comando `semana` actualiza automáticamente:
+Este comando debe actualizar:
+
+* Tema institucional.
+* Layouts.
+* Componentes.
+* Scripts.
+* Plantillas.
+* Workflow de GitHub Pages.
+
+No debe sobrescribir el contenido académico existente en:
 
 ```text
-openclass.config.json
-slides.md
-scripts/decks.mjs
-package.json
-curso_semanaN.md
-semanas/curso_semanaN.md
+semanas/
 ```
 
-El contenido ya editado dentro de `semanas/*.md` se conserva. Solo se sobrescribe si usas:
+### Paso 5. Regenerar configuración
 
 ```bash
-npm run semana -- 4 --force-content
+npm run config
 ```
 
-Para activar únicamente una semana:
+### Paso 6. Validar GitHub Pages
 
 ```bash
-npm run semana -- 4 --only
+npm run pages:check
+npm run pages:build
+```
+
+### Paso 7. Publicar cambios
+
+```bash
+git add -A
+git commit -m "Actualiza infraestructura Open Class"
+git push
 ```
 
 ---
 
-## 4. Editar contenido académico
+## 8. Comandos principales
+
+### Generar portal, lanzadores, scripts y decks
 
-El contenido real de cada presentación está en:
+```bash
+npm run config
+```
+
+### Activar una semana
+
+```bash
+npm run semana -- 4
+```
+
+### Activar una semana y cambiar metadatos
+
+```bash
+npm run semana -- 4 --title "Título de la semana" --date "Junio 20 de 2026"
+```
+
+### Forzar sobrescritura del contenido de una semana
+
+```bash
+npm run semana -- 4 --force-content
+```
+
+Usar con cuidado, porque puede reemplazar el archivo en:
 
 ```text
 semanas/
 ```
 
-Ejemplo:
+### Ver portal principal
 
-```text
-semanas/iot_semana1.md
-semanas/iot_semana2.md
-semanas/iot_semana3.md
+```bash
+npm run dev
+```
+
+### Ver una semana específica
+
+```bash
+npm run dev:s1
+```
+
+### Exportar PDF y PPTX
+
+```bash
+npm run export:downloads
+```
+
+### Construir sitio completo
+
+```bash
+npm run build:all
+```
+
+### Construir para GitHub Pages
+
+```bash
+npm run pages:build
 ```
 
-Los archivos de la raíz como `iot_semana1.md` funcionan como lanzadores. Normalmente no debes editarlos manualmente.
+### Publicar cambios en GitHub
+
+```bash
+npm run publicar
+```
 
 ---
 
-## 5. Recursos del curso
+## 9. Flujo recomendado para crear una nueva semana
 
-Usa estas carpetas:
+```bash
+npm run semana -- 5
+```
+
+Luego editar:
 
 ```text
-public/imagenes/    imágenes del curso
-public/videos/      videos y recursos audiovisuales
-public/descargas/   PDF, PPTX u otros descargables
-public/fondos/      fondos institucionales
+semanas/nombrecurso_semana5.md
 ```
 
----
+Agregar imágenes en:
 
-## 6. Construcción local
+```text
+public/imagenes/
+```
 
-Construir el portal y las semanas activas:
+Probar:
 
 ```bash
-npm run pages:build
+npm run dev:s5
 ```
 
-Previsualizar la versión estática:
+Construir:
 
 ```bash
-npm run pages:preview
+npm run pages:build
 ```
 
-Revisar configuración para GitHub Pages:
+Publicar:
 
 ```bash
-npm run pages:check
+npm run publicar
 ```
 
 ---
 
-## 7. Publicar en GitHub Pages
+## 10. Layouts disponibles
 
-Este proyecto ya incluye:
+Los layouts disponibles en el tema son:
 
 ```text
-.github/workflows/deploy.yml
+slide-01-portada
+slide-02-titulo
+slide-03-imagen-izquierda
+slide-04-imagen-derecha
+slide-05-titulo-superior-texto-derecha
+slide-06-titulo-superior-texto-izquierda
+slide-07-multimedia-con-titulo
+slide-08-titulo-texto
+slide-09-objetivos
+slide-10-titulo-dos-columnas
+slide-11-dos-titulos-dos-columnas
+slide-12-cierre
+slide-codigo
+```
+
+La plantilla:
+
+```text
+plantillas/semana.md
 ```
 
-El workflow construye el sitio y publica la carpeta `dist` en GitHub Pages.
+incluye ejemplos de uso para cada layout.
+
+---
+
+## 11. Recomendaciones de edición
 
-En GitHub configura:
+No editar manualmente estos archivos salvo que estés modificando la infraestructura:
 
 ```text
-Settings → Pages → Build and deployment → Source → GitHub Actions
+slides.md
+scripts/decks.mjs
+curso_semanaN.md
+package.json
 ```
 
-Luego sube cambios:
+Estos archivos pueden regenerarse con:
 
 ```bash
-git add -A
-git commit -m "Actualizar Open Class"
-git push
+npm run config
+```
+
+Editar principalmente:
+
+```text
+openclass.config.json
+semanas/curso_semanaN.md
+public/imagenes/
 ```
 
-Cada `push` a `main` construirá y publicará el sitio automáticamente.
+---
+
+## 12. Despliegue con GitHub Pages
 
-La URL esperada será:
+El workflow está en:
 
 ```text
-https://herrerawilliamh.github.io/NOMBRE-DEL-REPOSITORIO/
+.github/workflows/deploy.yml
 ```
 
-Ejemplo:
+Cada vez que se hace `push` a `main`, GitHub Actions ejecuta:
+
+```bash
+npm run pages:build
+```
+
+El sitio generado queda en:
 
 ```text
-https://herrerawilliamh.github.io/openclass-iot/
+dist/
 ```
 
+y se publica automáticamente con GitHub Pages.
+
 ---
 
-## 8. Flujo semanal sugerido
+## 13. Solución de problemas frecuentes
+
+### Error en `scripts/decks.mjs`
+
+Si aparece un error similar a:
+
+```text
+SyntaxError: Invalid regular expression: missing /
+```
 
-Semana 1:
+revisar que la función `withBase()` tenga esta línea:
+
+```js
+return `${SITE_BASE}${value.replace(/^[/]+/, "")}`;
+```
+
+### No aparece una semana en el portal
+
+Revisar que esté activa en:
+
+```json
+"activeWeeks": [1, 2, 3]
+```
+
+También se puede activar con:
 
 ```bash
-npm run semana -- 1 --title "Introducción al curso"
-git add -A
-git commit -m "Agregar semana 1"
-git push
+npm run semana -- N
 ```
 
-Semana 2:
+### No se ven imágenes
+
+Revisar que estén en:
+
+```text
+public/imagenes/
+```
+
+y que se referencien así:
+
+```html
+<img src="/imagenes/nombre.png" alt="Descripción de la imagen" />
+```
+
+### No se ven los fondos institucionales
+
+Verificar que existan:
+
+```text
+public/fondos/slide-01-portada.png
+public/fondos/slide-05-template.png
+public/fondos/slide-06-cierre.png
+```
+
+---
+
+## 14. Flujo de mantenimiento del template
+
+Cuando se mejore el template base:
 
 ```bash
-npm run semana -- 2 --title "Tema de la semana 2"
 git add -A
-git commit -m "Agregar semana 2"
+git commit -m "Mejora plantilla Open Class"
 git push
 ```
 
-Repite el proceso hasta la semana 8.
-
----
+Luego copiar la plantilla actualizada al paquete generador:
 
-## 9. Comandos útiles
+```bash
+robocopy D:\OpenClass\openclass-uniminuto-template D:\OpenClass\create-openclass-uniminuto\template /E /XD .git node_modules dist .slidev /XF openclass-template.zip
+```
 
-| Comando | Uso |
-|---|---|
-| `npm run nuevo` | Configura un curso desde consola |
-| `npm run semana -- 1` | Genera o activa la semana 1 |
-| `npm run dev` | Abre el portal principal |
-| `npm run dev:s1` | Abre la semana 1 |
-| `npm run pages:check` | Revisa configuración para GitHub Pages |
-| `npm run pages:build` | Construye el sitio estático y exporta descargas |
-| `npm run pages:preview` | Previsualiza la versión publicada |
-| `npm run publicar` | Ejecuta exportaciones y construcción local |
+Publicar nueva versión del paquete:
 
----
+```bash
+cd D:\OpenClass\create-openclass-uniminuto
+npm version patch
+npm publish --access public
+```
 
-## 10. Archivos clave
+Actualizar cursos existentes:
 
-```text
-openclass.config.json       configuración general del curso
-slides.md                   portal principal
-semanas/                    contenido académico real
-scripts/decks.mjs           listado de presentaciones activas
-.github/workflows/deploy.yml despliegue automático en GitHub Pages
+```bash
+npm create openclass-uniminuto@latest . -- --update-theme
+npm run config
+npm run pages:build
 ```