Introducción a Asciidoc y Asciidoctor (4): crear una presentacion
Tags: asciidoc, documentation, write
Published: 2020-01-27 14:11:17

---
title: Introducción a Asciidoc y Asciidoctor (4): crear una presentacion
published: true
date: 2020-01-25 00:00:00 UTC
tags: asciidoc,documentation,write
canonical_url: https://jorge.aguilera.soy/blog/2020/intro-asciidoctor-4.html
---

| | Este post es la continuación a [intro-asciidoctor-3.html](https://jorge.aguilera.soy/blog/2020/intro-asciidoctor-3.html) |

## Objetivo

En este post veremos cómo crear una presentación usando sólo un editor de texto (y asciidoctorpor supuesto).

| | El objetivo es poder exponer de forma rápida y sencilla cualquier idea que tengasy quieras transmitir, tanto a un público "cercano", como compañeros, tu jefe, tu profesor, etco publicarlo en Internet bien como un documento HTML o incluso como un pdf en Slides o similar. |

| | [Aquí](https://jorge.aguilera.soy/blog/2020/revealjs/charla.html) para ver la versión HTML y aquípuedes ver [aquí](https://jorge.aguilera.soy/blog/2020/revealjs/charla.adoc) el fichero para construirlo (texto plano) |

## Instalación (sólo 1 vez)

En el primer post indicamos algunas de las formas que puedes usar para ejecutar asciidoctor,bien sea usando la versión `ruby` (la más popular), bien usando la versión `java` (que puedes integraren tu aplicación como librería), etc.

Para este ejemplo vamos a usar la versión `ruby` por lo que tendrás que tener instalada esta versión.Por ejemplo si usas una distribución Linux con apt puedes ejecutar:

`$ sudo apt-get install asciidoctor`

Lo siguiente, en el directorio que reservemos para nuestras presentaciones crearemos un fichero `Gemfile`para descargar las dependencias necesarias para poder crear presentaciones:

Gemfile

```
source 'https://rubygems.org'

gem 'asciidoctor-revealjs'
```

y preparemos nuestro directorio

```
$ bundle config --local github.https true
$ bundle --path=.bundle/gems --binstubs=.bundle/.bin
```

| | Si por ejemplo optas por usar AsciidoctorJ (Java), existe un plugin para Maven y otro para Gradleque hace que todo esto sea innecesario y mucho más sencillo. |

| | Aún más sencillo. Aunque no tengas conocimientos de programación, si tienes java instalado en tu máquina,puedes descargarte esta plantilla con todo lo necesario para empezar a crear tus presentaciones:[https://gitlab.com/jorge-aguilera/presentation-template](https://gitlab.com/jorge-aguilera/presentation-template) |

## Reveal JS

El backend de presentaciones revealjs, como su nombre indica, lo que va a usar es este famoso framework Javascript para, partiendo de un documento .adoc, generar un .html con el javascript necesario incluido en él, pero sin necesidadde tener ningún conocimiento de maquetación, html, css o javascript. Simplemente escribiendo en un fichero de textoy usando los atributos asciidoctor del documento, podremos configurar el resultado, etc

## Estructura

La idea básica del backend revealjs es que cada sección del documento corresponderá a una slide y el contenido decada sección será renderizado en esta, siendo la primera sección reservada a la slide de presentación

| | Recuerda que una sección se crea comenzando una línea con '=' tantas veces repetidos como nivel de profundidadqueramos |

Básicamente en una slide insertaremos:

- Párrafos de textos

- Listas ordenadas o desordenadas de items

- image, video

- tabla con datos

- una imagen de fondo

Así mismo querremos que nuestra presentación sea un poco amena y que las transiciones entre slides tengan algún efecto

A continuación vamos a ir viendo cada uno de estos elementos paso a paso.

| | Según vayas practicando a crear presentaciones irás descubriendo que cada vez pierdes menos tiempo en "cómo queda" ymás en estructurar y mejorar el contenido. |

## Primera iteración, la portada

Lo primero que vamos a hacer es crear la primera slide de presentación. Nuestra charla va a ser sobre XXXXXX por loque crearemos al inicio del documento la primera sección:

```
= XXXXX : YYYYY
jorge.aguilera@puravida-software.com
#elije uno de: beige, black, league, night, serif, simple, sky, solarized, white
:revealjs_theme: league
```

y generamos nuestra primera iteración:

`bundle exec asciidoctor-revealjs -a revealjsdir=https://cdnjs.cloudflare.com/ajax/libs/reveal.js/3.7.0 charla.adoc`

(donde charla.adoc es el nombre del fichero que estés creando para tu charla)

Si todo ha ido bien tendrás un fichero HTML que puedes abrir con el navegador, y ver algo así[https://jorge.aguilera.soy/blog/2020/revealjs/uno.html](revealjs/uno.html)

Prueba a cambiar el atributo `revealjs_theme` del documento con alguno de los valores indicados y vuelve a generarla presentación. Verás que el tema se aplica y siendo la misma presentación el diseño cambia

## Slides y "subslides"

Como hemos mencionado antes, cada slide se define por una sección con '=='. Además RevealJS nos permite crear"subslides", o slides verticales, usando subsecciones con '==='. De esta forma podemos organizar los conceptosa exponer de forma anidada, navegando entre los conceptos principales con las flechas derecha-izquierda ylos subconceptos con las flechas arriba-abajo.

```
= Titulo : subtitulo
:stem:

== Introducción

aqui la introducción

== Concepto 1

Concepto1 lo podemos explicar en subslides

=== Primera parte

Primera parte de concepto 1

- planificar
- definir
- revisar
- morir de inanicción

=== Segunda parte

Segunda parte de concepto 1

stem:[x^2=y^2]

== Concepto 2

.Una tabla
|===
|Column heading 1 |Column heading 2

| Un texto
a|latexmath:[a^2+b^2=c^2].

| Otro texto
a|latexmath:[k_{n+1} = n^2 + k_n^2 - k_{n-1}].
|===
```

Aquí como se vería esta presentación [https://jorge.aguilera.soy/blog/2020/revealjs/dos.html](https://jorge.aguilera.soy/blog/2020/revealjs/dos.html)

| | prueba a pulsar _Esc_ en la presentación y verás lo que pretendo transmitirte |

El contenido de las slides puede ser muy variado. Desde párrafos de textos, listas,tablas, imágenes, e incluso fórmulas matemáticas, como puedes ver en el ejemplo anterior

## Funcionalidades

Una vez vista la idea principal de cómo generar slides con asciidoctor + revealjs vamos a enumeraralguna de las funcionalidades que se pueden hacer

### Notas para el orador

Podemos añadir notas visibles en una ventana aparte mediante un bloque `.notes`

```
== Concepto
Este concepto es muy denso para explicarlo

[.notes]
--
Lo que va entre estos guiones solo lo ve el orador en una venta aparte
--
```

### Slides sin título

Algunas veces queremos que la slide no contenga título, tal vez porque queremos poner una fotoa pantalla completa.

Simplemente etiquetamos el título con `%notitle`

```
[%notitle]
== Esta slide va sin titulo
```

### Listas animadas

Muchas veces queremos mostrar una lista de pasos a ejecutar, ideas, etc pero queremos ir explicandouna a una para que el público nos preste atención y no se pongan a leer todas de una vez. Para ellousaremos `%step`

```
== Mis ideas para el 2020
[%step]
- Aparece la primera y no se ven las siguientes
- Al pulsar una tecla aparezco con una animación
- Si sigues pulsando teclas aparezco yo
```

### Más funcionalidades

En esta página encontrarás todas las funcionalidades posibles con este backend:[https://asciidoctor.org/docs/asciidoctor-revealjs/#syntax-examples](https://asciidoctor.org/docs/asciidoctor-revealjs/#syntax-examples)

## Ejemplos completos

En esta presentación puedes encontrar (casi) todos los elementos y efectos que puedes hacer conuna presentación Asciidoctor (lo cual no quiero decir que haya que hacerlo. Ya sabes, a veces menos, es más):

[https://bentolor.github.io/java9to13/#/](https://bentolor.github.io/java9to13/#/)

O esta otra más minimalista:

[https://puravida-software.gitlab.io/slides/doc-as-code.html#/](https://puravida-software.gitlab.io/slides/doc-as-code.html#/)