Didacta
Plataforma de contenido docente. Se escribe el material una vez y se genera
cada PDF que haga falta: diapositivas, apuntes, handouts, hojas de problemas,
copias del profesor y exámenes, en castellano, valenciano e inglés.
Documentación y descargas ·
software libre bajo la GPL-3.0.
Esta carpeta es la plataforma. El material docente vive en repositorios de
contenido separados que Didacta compila.
El principio
EL CONTENIDO SE ESCRIBE UNA VEZ.
LAS ASIGNATURAS SON COMPOSICIONES.
LOS IDIOMAS SON VARIANTES DE LA MISMA ENTIDAD.
LAS SALIDAS SE GENERAN.
Un fichero de contenido no sabe a qué salida va. Los interruptores deciden:
\begin{frame}
\didactatitle{Definición de espacio normado}
La métrica usual en $\mathbb{R}$ es $d(x,y) = |x-y|$.
\onlynotes{La idea es generalizar las propiedades útiles de esa distancia.}
\begin{definition}[Espacio normado]
Un par $(E, \|\cdot\|)$ tal que...
\end{definition}
\begin{teaching}[Ritmo]
Quince minutos. Detente en la homogeneidad.
\end{teaching}
\end{frame}
Y de ese único fichero:
didacta build tema-1
ok tema-1 slides va 7 pp
ok tema-1 slides-flat va 6 pp
ok tema-1 notes va 4 pp
ok tema-1 slides-teacher va 6 pp
ok tema-1 notes-teacher va 4 pp
Las 15 salidas
$ didacta profiles
| id | clase | medio | soluciones | audiencia | pausas |
|---|
slides | beamer | diapositivas | — | alumno | sí |
slides-flat | beamer | diapositivas | — | alumno | no |
slides-teacher | beamer | diapositivas | todas | profesor | no |
notes | article | documento | — | alumno | — |
notes-solutions | article | documento | todas | alumno | — |
notes-teacher | article | documento | todas | profesor | — |
book | book | documento | — | alumno | — |
handout | article | documento | — | alumno | — |
handout-answers | article | documento | resultados | alumno | — |
handout-teacher | article | documento | todas | profesor | — |
problems | article | documento | — | alumno | — |
problems-answers | article | documento | resultados | alumno | — |
problems-teacher | article | documento | todas | profesor | — |
exam | article | documento | — | alumno | — |
exam-marking | article | documento | todas | profesor | — |
Un perfil no es una plantilla: es un preajuste sobre cinco ejes
independientes — medio, detalle, audiencia, soluciones y pausas. Añadir una
salida es una línea en latex/didacta-profiles.tex, y nada más en el
sistema necesita saberlo.
Las tres versiones de un problema
Un problema es un fichero con tres campos —enunciado, resultado y solución
detallada— y tres versiones que los revelan por niveles: la versión n
enseña los campos 1 a n. La del profesor añade encima la corrección.
| hint | answer | solution | marking |
|---|
problems · alumnos, solo enunciados | ✓ | | | |
problems-answers · alumnos, con resultados | ✓ | ✓ | | |
problems-teacher · profesor, todo | ✓ | ✓ | ✓ | ✓ |
exam | | | | |
Lo mismo, con handout-*, para un guion de prácticas: un documento con
ejercicios dentro se reparte, se corrige y se entrega igual venga de donde
venga.
answer el resultado, una línea, para que el alumno se corrijasolution el desarrollomarking qué buscar al corregir y cuánto vale cada parte
Cómo se organiza el contenido
<repositorio-de-contenido>/
didacta.yaml ajustes del repositorio
content/<área>/<tema>/<unidad>/
unit.yaml título, etiquetas, idiomas, estado
es.tex va.tex en.tex el mismo contenido, un fichero por idioma
figures/ sus imágenes
problems/<área>/<tema>/<unidad>/
unit.yaml
es.tex va.tex en.tex enunciado + respuesta + solución + corrección
courses/<asignatura>/
course.yaml lo que no cambia entre cursos
<curso>/
year.yaml selección, orden, estructura
<documento>.tex la composición
Una unidad es un directorio. Sus idiomas, sus metadatos y sus figuras se
mueven juntos.
El idioma es el nombre del fichero, no una convención: va.tex, no
03VAL-espacios-normados.tex. El ordinal que antes llevaba el orden vive ahora
en la composición, que es donde el orden pertenece — reordenar un tema ya no
implica renombrar ficheros.
Un curso guarda selección y orden, nunca contenido. Duplicar un curso copia
un fichero de estructura:
didacta new year am-iii 2026-2027
Compilar la aplicación
Doble clic en Compilar Didacta.app, en esta misma carpeta: abre un menú en
Terminal con lo que se puede compilar y lo hace. El primer objetivo --compilar
e instalar en ~/Applications-- es el de todos los días.
También sirve desde la terminal, que es el mismo programa:
./build.command # el menú
./build.command instalar # compilar, instalar y abrir
./build.command todo # los tests del motor y los de la aplicación
./build.command --list # qué objetivos hay
Solo ofrece lo que esta máquina puede hacer. Flutter compila para el
escritorio en el que corre, así que Linux y Windows no salen en un Mac: de
eso se encarga la integración continua.
Empezar
# Qué hay en este repositorio
didacta status
# La biblioteca, con el estado de traducción de cada unidad
didacta units
didacta units --category analysis --missing va
# Qué falta traducir, ordenado por cuánto se usa cada unidad
didacta translations
# Validar: referencias que no resuelven, perfiles inexistentes,
# documentos que compilan en un idioma que su contenido no tiene
didacta check
didacta check --in am-iii@2025-2026 # solo lo de ese curso
didacta check --with formulas,unused --json # más comprobaciones, en JSON
didacta check --strict # los avisos también fallan
# Compilar
didacta build tema-1
didacta build tema-1 -p slides -l va
didacta build --all
didacta build --all --list # qué haría, sin hacerlo
didacta preview analysis/normed/definition # una unidad suelta
didacta clean --size # cuánto ocupa lo compilado
# Repartir: los PDF de un curso a una carpeta, o una web para GitHub Pages
didacta export am-iii@2025-2026 --to ~/Aula
didacta site am-iii@2025-2026
# Crear
didacta new unit analysis/normed-spaces/dual-space
didacta new unit analysis/series/convergence --kind problem
didacta new year am-iii 2026-2027
# El catálogo que lee la interfaz. Datos derivados: regenerarlos da los
# mismos bytes, y --check falla si están desincronizados (para CI)
didacta index
didacta index --check
# Traer material del sistema LaTeX anterior. Sin --apply no escribe nada,
# y no toca el repositorio de origen en ningún caso
didacta migrate ~/Teaching ~/didacta-content
didacta migrate ~/Teaching ~/didacta-content --year 2025-2026 --apply
# --verify compila además cada documento migrado y lista en el informe los
# que no salen, con fichero, línea y la macro culpable
didacta migrate ~/Teaching ~/didacta-content --year 2025-2026 --apply --verify
Hay más --congelar un curso, dar un tema en otro, mover una lección, el
servidor MCP--, y didacta --help las lista todas. Cada una, con ejemplos, en
la página de la herramienta.
Se ejecuta desde cualquier sitio dentro de un repositorio de contenido: la raíz
se localiza subiendo hasta encontrar didacta.yaml, como hace git con .git.
Hay un repositorio de ejemplo completo en examples/demo-course:
cd examples/demo-course
../../cli/didacta status
../../cli/didacta build --all
La aplicación
Flutter Web, en app/. La biblioteca ya funciona sobre el material
real: las 2147 unidades con filtros por árbol, categoría, tipo, etiqueta y
estado de traducción, búsqueda por palabras y cuatro órdenes.
didacta index # en el repositorio de contenido
cd app && flutter run -d chrome --dart-define=DIDACTA_INDEX=/ruta/generated
No habla con el repositorio: lee tres JSON estáticos que pesan 77 KB
comprimidos para la biblioteca entera, así que se puede publicar en GitHub
Pages sin ningún servidor detrás.
Dos cosas que muestra y que el repositorio no puede contestar solo:
- en qué documentos se usa cada unidad — la respuesta a «¿puedo cambiar
esto?», que exige recorrer todas las composiciones;
- qué unidades no usa nadie — después de una migración, material que llegó
y no se está dando.
En escritorio hace bastante más: edita, traduce, reclasifica y recompone
sobre clones locales de varios repositorios a la vez, con la identidad de
GitHub. Escribir exige un token, y un token exige un sitio donde guardarlo que
un navegador no tiene; en macOS, Windows y Linux ese sitio es el llavero del
sistema.
Instalar Didacta
No hace falta compilarla: las versiones se publican en
Releases, y la página de
descarga con los checksums está en
la web.
| Sistema | Qué se descarga |
|---|
| macOS | Un .dmg, arrastrar a Aplicaciones |
| Windows | Un instalador, sin administrador |
| Linux | Un AppImage: chmod +x y abrir |
La primera vez, Didacta abre con una presentación que deja la configuración
hecha: entrar en GitHub, abrir el primer repositorio y descargar el motor. La
contraseña no se teclea nunca dentro de Didacta -- se autoriza en github.com
con un código corto. A partir de ahí se actualiza sola, una vez por semana y
preguntando.
Publicar una versión
- escribir arriba de
CHANGELOG.md lo que trae, bajo
## Próxima si todavía no sabes el número;
python3 packaging/publish.py.
Pregunta si es grande, mediana o pequeña --1.0.0, 0.2.0 o 0.1.1 desde la
0.1.0-- y si se publica o se ensaya; le pone el número a la sección, avisa de
lo que no va a entrar, hace el commit, lo sube y lanza Publish Didacta
Release en GitHub. Lo que elige lo deja en release.yaml,
que también se puede editar a mano y pulsar el botón en Actions. Con
--prueba sale una versión de prueba --1.5.0-rc.1-- que solo reciben
quienes las piden en Ajustes → Actualizaciones.
Compila macOS, Windows y Linux, calcula los SHA-256, publica el release aquí
mismo y dispara el despliegue de la web, que reescribe su página de descarga
leyendo lo publicado. El detalle está en
docs/DISTRIBUTION.md.
Qué hay aquí
didacta/
├── latex/ el sistema LaTeX
│ ├── didacta-bootstrap.tex elige la clase según el perfil
│ ├── didacta-profiles.tex ← el registro de salidas
│ ├── didacta.sty el paquete principal
│ ├── didacta-formats.sty \onlyslides / \onlynotes / \onlyteacher
│ ├── didacta-theorems.sty teoremas, dos aspectos según el medio
│ ├── didacta-problems.sty ejercicios y los cuatro niveles
│ ├── didacta-theme.sty el tema beamer
│ ├── didacta-page.sty maquetación de documento
│ ├── didacta-colours.sty la paleta
│ ├── didacta-bibliography.sty las citas, con biblatex si hay .bib
│ ├── didacta-legacy.sty las macros del sistema anterior
│ └── lang/ es · va · en
├── engine/didacta/ Python: modelo, perfiles, compilación
├── cli/didacta la herramienta
├── examples/demo-course/ repositorio de contenido de ejemplo
├── web/ la web de documentación (MkDocs Material)
├── packaging/ publicar una versión
├── docs/
│ ├── AUTHORING.md ← referencia de escritura
│ └── ...
├── tests/ los del motor y la herramienta
├── app/ la aplicación (Flutter), con sus tests
└── ARCHITECTURE.md
Documentación
- La web — la documentación de uso,
con capturas: instalar, empezar, y la aplicación pantalla por pantalla. Se
construye desde
web/.
- docs/AUTHORING.md — todo lo que se puede escribir en
un fichero de contenido. Es la referencia que se usa a diario.
- ARCHITECTURE.md — el diseño y por qué está así.
- docs/DISTRIBUTION.md — cómo se reparte la
aplicación, cómo se actualiza sola, qué secretos hacen falta y cómo dar o
quitar el acceso a alguien.
- latex/didacta-profiles.tex — las salidas,
documentadas en el propio registro.
Requisitos
| |
|---|
| TeX Live | 2023 o posterior, con latexmk |
| Python | 3.9 o posterior, sin dependencias |
latexindent | opcional |
Todos los paquetes LaTeX que Didacta usa están en CTAN: una TeX Live estándar
basta, sin instalar nada más. El sistema anterior arrastraba seis .sty
no-CTAN y una fuente empaquetada en el repositorio, lo que hacía imposible
compilar en una máquina limpia.
La aplicación comprueba las cuatro cosas que necesita --git, Python 3,
LaTeX y su propio motor-- la primera vez que se abre y siempre que se mire en
Ajustes → Herramientas. De cada una dice si está, dónde y qué versión; de
la que falte, ofrece instalarla por el camino que no pida contraseña de
administrador, y vuelve a comprobarlo después. Cuando no puede --hace falta
sudo, no hay gestor de paquetes, la máquina no es tuya-- enseña las órdenes
para hacerlo a mano y el enlace a la guía oficial.
latexindent es lo único opcional de la lista. Si está y funciona, es quien
ordena la sangría de un .tex al guardarlo; si no, lo hace un indentador
propio que viene dentro y hace menos. No hace falta instalar nada: viene con
TeX Live, pero es un script de Perl y MacTeX no trae sus dependencias
(File::HomeDir, Log::Log4perl, Log::Dispatch, Unicode::GCString), así
que en la mayoría de los Mac el fichero está y no arranca. Quien las quiera,
cpan File::HomeDir Log::Log4perl Log::Dispatch Unicode::GCString; quien no,
no pierde nada que se note.
Sirve cualquiera de las tres, y la aplicación no obliga a configurar nada:
busca latexmk donde cada una se instala.
| |
|---|
| macOS | MacTeX, o BasicTeX si importa el disco (brew install --cask basictex) |
| Windows | TeX Live o MiKTeX |
| Linux | el texlive de la distribución |
| las tres | TinyTeX, ~100 MB y ampliable con tlmgr |
Didacta no lleva una distribución dentro, y es deliberado: la completa son
varios gigas, la versión de cada paquete la tiene que poder elegir quien
compila, y las actualizaciones de CTAN no pueden depender de que se publique
una versión de esta aplicación. Lo que sí hace es encontrar la que haya y
decir dónde ha mirado cuando no encuentra ninguna; si está en un sitio raro,
se le dice en Ajustes.
Y sabe bajar la que le digas: en Ajustes → Herramientas se elige entre las de
la tabla de arriba con su tamaño al lado, porque entre cien megas y seis gigas
la decisión depende del disco y de la conexión de cada uno, no de lo que la
aplicación prefiera. La ligera se instala sin contraseña de administrador y
Didacta le añade después, con tlmgr, los paquetes que el preámbulo usa.
Que la aplicación de escritorio busque en lugar de preguntar al PATH no es un
lujo: una app no hereda el PATH del terminal. A una aplicación lanzada
desde el Finder launchd le da /usr/bin:/bin:/usr/sbin:/sbin, y en macOS
latexmk vive en /Library/TeX/texbin, que entra en el PATH por
/etc/paths.d/TeX --que solo lee un shell de login--. Didacta decía
«necesita una distribución de TeX» con TeX Live 2026 instalada y compilando
en el terminal.
PyYAML se usa si está instalado; si no, el motor trae su propio lector del
subconjunto que los esquemas necesitan. Es deliberado: la plataforma tiene que
funcionar en un runner de CI sin un paso de pip.
Estado
Lo que funciona hoy, verificado compilando de verdad:
- las 15 salidas, desde un único origen;
- los tres idiomas, con nombres de entorno y cadenas fijas traducidos;
- los cuatro niveles de un problema, cada uno en su perfil;
- el canal del profesor, distinto del canal de apuntes;
- respaldo al idioma de referencia cuando falta una traducción, con aviso;
- inyección de metadatos desde
course.yaml y year.yaml;
- compilación fuera del árbol, con SyncTeX;
- las citas con biblatex, desde un
.bib del repositorio;
didacta, con treinta órdenes: de status, check y build a freeze,
export, site y mcp;- la aplicación entera sobre el material migrado de verdad: la biblioteca,
editar y traducir, recomponer, compilar y repartir.
La migración del sistema anterior está hecha y medida sobre el material real:
2147 unidades a partir de 2438 ficheros, y 784 documentos en 17 asignaturas y
30 cursos académicos, con 6137 referencias a unidades de las que 4 no
resuelven. De una muestra de 194 unidades migradas repartidas por las 51
categorías, las 194 compilan; el Tema 1 de 2025-2026 sale de su composición
migrada en los 7 perfiles que le corresponden.
Dos cosas que la migración no hace: escribir en el repositorio de origen —
comprobado con un test que compara cada fichero seguido por git antes y después
— e inventar los metadatos que el material anterior no guardaba.
MIGRATION-REPORT.md dice qué falta y dónde.
Unos 800 tests de Python y unos 2100 de Dart, en Linux, macOS y Windows en cada
push; ./build.command todo los pasa en local.
Lo que queda está en NEXT.md, y con detalle en
PLAN-DE-MEJORAS.md.
Licencia
Didacta es software libre bajo la GPL-3.0: se puede usar,
estudiar, modificar y redistribuir, y quien distribuya una versión modificada
tiene que publicar su código con la misma licencia.
La licencia cubre Didacta --el código, el motor y el sistema LaTeX--. El
material que se escriba con ella es de quien lo escriba, vive en sus
repositorios y lleva la licencia que le ponga, o ninguna.
Cómo contribuir: CONTRIBUTING.md.
