Como crear tutoriales web con Reveal.js y Git

Ya sea que estés aprendiendo o seas un maestro, probablemente reconozcas el valor de los talleres en línea organizados como presentaciones de diapositivas para comunicar conocimiento. Si alguna vez te encontraste con uno de estos tutoriales bien organizados que se configuran página por página. Asimismo, tutoriales capítulo por capítulo, es posible que te hayas preguntado qué tan difícil fue crear un sitio web de este tipo.

Bueno, estamos aquí para mostrarte lo fácil que es generar este tipo de trabajos utilizando un proceso totalmente automatizado.

Introducción

Cuando comencé a poner mi contenido de aprendizaje en línea, no fue una experiencia agradable y perfecta. Entonces, quería algo repetible y consistente que también fuera fácil de mantener, ya que mi contenido cambia a medida que avanza la tecnología que enseño.

Probé muchos modelos de entrega, desde generadores de código de bajo nivel, como Asciidoctor, hasta diseñar un taller en un solo archivo PDF. Todos fallaron en satisfacerme. Cuando realizo talleres en vivo en el sitio, me gusta usar presentaciones de diapositivas. Por lo tanto, me pregunté si podría hacer lo mismo para mis experiencias de seminarios en línea y a su propio ritmo.

Después de investigar un poco, construí una base para crear sitios web de talleres indoloros. Me ayudó que ya estaba usando un framework de generación de presentaciones que resultó en un formato amigable para el sitio web (HTML).

Configuración

Aquí los componentes básicos que necesitas para este proyecto:

  • Idea del taller (este es tu problema, no puedo ayudarte aquí)
  • Reveal.js para las diapositivas del taller
  • Repositorio de proyectos GitLab
  • Tu editor de código HTML favorito
  • Navegador web
  • Git instalado en tu máquina

Si esta lista parece intimidante, hay una manera rápida de comenzar que no implica unir todas las piezas una por una. Puedes usar este proyecto de plantilla para darte un impulso inicial con las diapositivas y la configuración del proyecto.

Este artículo asume que estás familiarizado con Git y los proyectos alojados en una plataforma Git como GitLab. Si necesitas un repaso o tutorial, consulta nuestra serie introductoria de Git.

Debes comenzar clonando el proyecto de plantilla en tu máquina local:

Debes configurar un nuevo proyecto de GitLab para esto e importar el proyecto de plantilla como la importación inicial.

Hay varios archivos importantes para el sitio web del taller. En el directorio root, encontrarás un archivo llamado .gitlab-ci.yml, que se utiliza como desencadenante cuando confirmas los cambios en la rama maestra. Es decir, combina las solicitudes de extracción con el master. Debes activar una copia de los contenidos completos del directorio de slides en la carpeta del sitio web del proyecto GitLab.

Esto está alojado como un proyecto llamado beginners-guide-automated-workshops en unacuenta de GitLab. Cuando se despliega, puedes ver el contenido del directorio slides en tu navegador desplazándote a:

Para tu cuenta de usuario y proyecto, la URL se vería así:

Estos son los materiales básicos que necesitas para comenzar a crear el contenido de tu sitio web. Cuando envíes los cambios, generarán automáticamente tu sitio web actualizado del taller.

Plantilla

Ten en cuenta que la plantilla predeterminada contiene varias diapositivas de ejemplo, que serán tu primer sitio web del taller después de completar el registro en tu repositorio.

La plantilla del taller da como resultado una presentación de diapositivas revelar.js que puede ejecutarse en cualquier navegador. Debe ejecutarse con cambio de tamaño automático que permite que sea vista por casi cualquier persona, en cualquier lugar, en cualquier dispositivo.

¿Cómo funciona esto para crear talleres prácticos y accesibles?

Cómo funciona

Con estos antecedentes, estás listo para explorar los materiales del taller y comenzar a armar tu contenido. Todo lo que necesitas se puede encontrar en el directorio slides del proyecto. Aquí es donde ocurre toda la magia con revelar.js para crear la presentación de diapositivas del taller en un navegador.

Los archivos y directorios con los que trabajarás para crear tu taller son:

  • El archivo default.css
  • El directorio de images
  • El archivo index.html

Abre cada uno en tu editor HTML/CSS favorito y realiza los cambios que se describen a continuación. No importa qué editor uses.

Yo Prefiero RubyMine IDE porque ofrece una vista previa de la página en el navegador local. Esto ayuda cuando estoy probando contenido antes de ponerlo en línea en el sitio web del taller.

Archivo default.css

El archivo css/theme/default.css es el archivo base donde establecerás configuraciones globales importantes para las diapositivas de tu taller. Los dos elementos principales de interés son la fuente predeterminada y la imagen de fondo para todas las diapositivas.

En default.css, observa la sección llamada GLOBAL STYLES. La fuente predeterminada actual aparece en la línea:

Si estás utilizando un tipo de fuente no estándar, debes importarlo (como se hizo para el tipo de fuente Overpass) en la línea:

El background es la imagen predeterminada para cada diapositiva que crees. Se almacena en el directorio images(ver a continuación) y se establece en la línea a continuación (centrarse en la ruta de la imagen):

Para establecer un fondo predeterminado, solo apunta esta línea a la imagen que deseas usar.

Directorio images

Como su nombre lo indica, el directorio de imágenes se utiliza para almacenar las imágenes que deseas utilizar en las diapositivas de tu taller. Por ejemplo, generalmente pongo capturas de pantalla que demuestran el progreso del tema del taller en mis diapositivas individuales.

Por ahora, solo debes saber que necesitas almacenar las imágenes de fondo en un subdirectorio (background). También las imágenes que planeas usar en tus diapositivas en el directorio Images.

Archivo Index.html

Ahora que tienes esos dos archivos ordenados, pasarás el resto del tiempo creando diapositivas en los archivos HTML, comenzando con index.html. Para que el sitio web de tu taller comience a tomar forma, presta atención a las siguientes tres secciones en este archivo:

  • La sección de head, donde estableces el título, el autor y la descripción
  • La sección del body, donde encontrarás las diapositivas individuales para diseñar
  • Section, donde defines el contenido de diapositivas individuales

Comienza con la sección de la head, ya que está en la parte superior. El proyecto de plantilla tiene tres líneas de marcador de posición para que actualices:

La etiqueta del title contiene el texto que aparece en la pestaña del navegador cuando el archivo está abierto. Debes cambiarla a algo relevante para el título de tu taller (o tal vez una sección de tu taller). Pero, recuerda que debe ser breve ya que el espacio del título de la pestaña es limitado.

La metaetiqueta description contiene una breve descripción de tu taller. Finalmente, la metaetiqueta del autor es donde debes poner tu nombre (o el nombre del creador del taller, si estás haciendo esto por otra persona).

Body

Ahora pasa a la sección del body. Notarás que está dividido en varias etiquetas de section. La apertura del body contiene un comentario que explica que estás creando diapositivas para cada section abierta y cerrada etiquetada como etiqueta:

Luego, debes crear tus diapositivas individuales, con cada diapositiva encerrada en etiquetas section. La plantilla incluye algunas diapositivas para ayudarte a comenzar. Por ejemplo, aquí está la primera diapositiva:

Esta diapositiva tiene dos áreas divididas con etiquetas div. El espaciado separa el título y el autor.

Suponiendo que tienes algún conocimiento sobre el uso de HTML, prueba varias cosas para desarrollar tu taller. Es realmente útil usar un navegador a medida que avanzas para obtener una vista previa de los resultados.

Algunos IDE´s proporcionan una visualización local de los cambios, pero también puedes abrir el archivo index.html y ver los cambios antes de enviarlos al repositorio.

Una vez que estés satisfecho con tu taller, envía tus cambios y espera a que pasen por la canalización de integración continua. Se alojarán como el proyecto de plantilla en https://eschabell.gitlab.io/beginners-guide-automated-workshops.

Conclusión

Esperamos que esta guía para principiantes te muestre lo fácil e indoloro que puede ser desarrollar y mantener sitios web de talleres de manera consistente.

También esperamos que este aporte brinde a tus audiencias acceso completo al contenido en casi cualquier dispositivo para que puedan aprender del conocimiento que compartes.