Publicando contenido técnico en Hugo con Markdown y Blox

Markdown como lingua franca de la programación en Hugo con Blox

Pantalla con código. Imagen de John Moeses, https://unsplash.com/photos/OGZtQF8iC0g

En el campo de la creación de contenido técnico y su publicación web hay varias alternativas. Entre las más conocidas, Jupyter, RStudio o los recientes Quartz. Hugo Blox Builder se une a estas opciones con la ventaja de ser parte de Hugo, donde el contenido está creado con Markdown y Wowchemy se encarga de lo demás.

En nuestro caso, conviene recordar que llegamos a Hugo gracias a ox-hugo de Kaushalmodi, lo que permite exportar de Emacs Org-mode a Markdown Blackfriday compatible con Hugo.

Por tanto, lenguaje publicitario, tan habitual en estas aplicaciones, como el de Hugo Blox no nos sorprenden ya que “resaltar los bloques de código, tomar notas de operaciones matemáticas o dibujar diagramas desde representaciones textuales” son lo que mueven utilizar Emacs Org-mode. Hugo Blox cubre la publicación de ese contenido en una Web, que no es poco.

Veamos pues lo que se nos ofrece:

Código

Wowchemy soporta una extensión de Markdown para resaltar la sintaxis. Puedes perosnalizar el estilo en la opción syntax_highlighter en el archivo de configuración config/_default/params.yaml.

Si se escribe:

import pandas as pd
data = pd.read_csv("data.csv")
data.head()

Se importa la librería Pandas como pd y e asigna la variable data a la lectura del archivo data.csv a través de la función pd.read_csv().

Mapas mentales

La extensión para mapas mentales es markmap. Se debe incluir un bloque de código markmap y, opcionalmente, establecer la altura del mismo. Un mapa mental simple se puede definir como una lista de Markdown:


```markmap {height="200px"}
- Hugo Modules
  - wowchemy
  - blox-plugins-netlify
  - blox-plugins-netlify-cms
  - blox-plugins-reveal
```

Lo cual se muestra como:

- Hugo Modules
  - wowchemy
  - blox-plugins-netlify
  - blox-plugins-netlify-cms
  - blox-plugins-reveal

O bien, de una forma más avanzada, con formateado, bloques de código y operaciones aritméticas:


```markmap
- Mindmaps
  - Links
    - [Wowchemy Docs](https://docs.hugoblox.com/)
    - [Discord Community](https://discord.gg/z8wNYzb)
    - [GitHub](https://github.com/HugoBlox/hugo-blox-builder)
  - Features
    - Markdown formatting
    - **inline** ~~text~~ *styles*
    - multiline
      text
    - `inline code`
    -
      ```js
      console.log('hello');
      console.log('code block');
      ```
    - Math: $x = {-b \pm \sqrt{b^2-4ac} \over 2a}$
```

Lo que se muestra como:

- Mindmaps
  - Links
    - [Wowchemy Docs](https://docs.hugoblox.com/)
    - [Discord Community](https://discord.gg/z8wNYzb)
    - [GitHub](https://github.com/HugoBlox/hugo-blox-builder)
  - Features
    - Markdown formatting
    - **inline** ~~text~~ *styles*
    - multiline
      text
    - `inline code`
    -
      ```js
      console.log('hello');
      console.log('code block');
      ```
    - Math: $x = {-b \pm \sqrt{b^2-4ac} \over 2a}$

Gráficos

Otra librería que soporta Wowchemy es Plotly para gráficos interactivos. Tan solo hay que guardar el JSON de Plotly en el directorio del artículo y añadir el atajo para que se muestre.

Si el archivo fuera line-chart.json, habría que añadir la línea {{< chart data="line-chart" >}} donde se quisiera mostrar.

Por ejemplo:

Recuerda que hay un editor de Plotly JSON disponible.

Operaciones aritméticas

El soporte de operaciones aritméticas se consigue por una extensión de Markdown para \LaTeX. Se puede habilitar esta opción en el archivo de configuración config/_default/params.yaml.

Para mostrar las operaciones en una línea del párrafo o en un bloque se puede hacer con {{< math >}}$...${{< /math >}}

Bloque:

{{< math >}}$$…$${{< /math >}}

El atajo math es nuevo en la versión 5.5-dev.

Por ejemplo, este código:

```latex
{{< math >}}
$$
\gamma_{n} = \frac{ \left | \left (\mathbf x_{n} - \mathbf x_{n-1} \right )^T \left [\nabla F (\mathbf x_{n}) - \nabla F (\mathbf x_{n-1}) \right ] \right |}{\left \|\nabla F(\mathbf{x}_{n}) - \nabla F(\mathbf{x}_{n-1}) \right \|^2}
$$
{{< /math >}}
```

Se muestra:

$$\gamma_{n} = \frac{ \left | \left (\mathbf x_{n} - \mathbf x_{n-1} \right )^T \left [\nabla F (\mathbf x_{n}) - \nabla F (\mathbf x_{n-1}) \right ] \right |}{\left \|\nabla F(\mathbf{x}_{n}) - \nabla F(\mathbf{x}_{n-1}) \right \|^2}$$

{{< math >}} \[\gamma_{n} = \frac{ \left | \left (\mathbf x_{n} - \mathbf x_{n-1} \right )^T \left [\nabla F (\mathbf x_{n}) - \nabla F (\mathbf x_{n-1}) \right ] \right |}{\left \|\nabla F(\mathbf{x}_{n}) - \nabla F(\mathbf{x}_{n-1}) \right \|^2}\] {{< /math >}}

Otro ejemplo de de inline math, {{< math >}}$\nabla F(\mathbf{x}_{n})${{< /math >}} se muestra como {{< math >}}\(\nabla F(\mathbf{x}_{n})\){{< /math >}}.

Ejemplo de varias líneas con \\:


```latex
{{< math >}}
$$f(k;p_{0}^{*}) = \begin{cases}p_{0}^{*} & \text{if }k=1, \\
1-p_{0}^{*} & \text{if }k=0.\end{cases}$$
{{< /math >}}
```

Que se muestra:

$$ f(k;p_{0}^{*}) = \begin{cases}p_{0}^{*} & \text{if }k=1, \\ 1-p_{0}^{*} & \text{if }k=0.\end{cases} $$

Diagramas

La extensión de Markdown para diagramas se puede activar en el archivo de configuración config/_default/params.toml o bien añadiendo diagram: true a la configuración del artículo.

Flowchart

Un ejemplo de gráfico de flujo o flowchart:

```mermaid
graph TD
A[Hard] -->|Text| B(Round)
B --> C{Decision}
C -->|One| D[Result 1]
C -->|Two| E[Result 2]
```

Lo que se muestra como:

graph TD A[Hard] -->|Text| B(Round) B --> C{Decision} C -->|One| D[Result 1] C -->|Two| E[Result 2]

Diagrama secuencial

Un ejemplo de diagrama secuencial o sequence diagram:

```mermaid
sequenceDiagram
Alice->>John: Hello John, how are you?
loop Healthcheck
    John->>John: Fight against hypochondria
end
Note right of John: Rational thoughts!
John-->>Alice: Great!
John->>Bob: How about you?
Bob-->>John: Jolly good!
```

Lo que se muestra como:

sequenceDiagram Alice->>John: Hello John, how are you? loop Healthcheck John->>John: Fight against hypochondria end Note right of John: Rational thoughts! John-->>Alice: Great! John->>Bob: How about you? Bob-->>John: Jolly good!

Diagrama de Gantt

Un ejemplo de diagrama de Gantt:


```mermaid
gantt
section Section
Completed :done,    des1, 2014-01-06,2014-01-08
Active        :active,  des2, 2014-01-07, 3d
Parallel 1   :         des3, after des1, 1d
Parallel 2   :         des4, after des1, 1d
Parallel 3   :         des5, after des3, 1d
Parallel 4   :         des6, after des4, 1d
```

Lo que se muestra como:

gantt section Section Completed :done, des1, 2014-01-06,2014-01-08 Active :active, des2, 2014-01-07, 3d Parallel 1 : des3, after des1, 1d Parallel 2 : des4, after des1, 1d Parallel 3 : des5, after des3, 1d Parallel 4 : des6, after des4, 1d

Diagrama de clases

Un ejemplo de diagrama de clases:

```mermaid
classDiagram
Class01 <|-- AveryLongClass : Cool
Class03 *-- Class04
Class05 o-- Class06
Class07 .. Class08
Class09 --> C2 : Where am i?
Class09 --* C3
Class09 --|> Class07
Class07 : equals()
Class07 : Object[] elementData
Class01 : size()
Class01 : int chimp
Class01 : int gorilla
Class08 <--> C2: Cool label
```

Lo que se muestra como:

classDiagram Class01 <|-- AveryLongClass : Cool Class03 *-- Class04 Class05 o-- Class06 Class07 .. Class08 Class09 --> C2 : Where am i? Class09 --* C3 Class09 --|> Class07 Class07 : equals() Class07 : Object[] elementData Class01 : size() Class01 : int chimp Class01 : int gorilla Class08 <--> C2: Cool label

Diagrama de estados

Un ejemplo de diagrama de estados:

```mermaid
stateDiagram
[*] --> Still
Still --> [*]
Still --> Moving
Moving --> Still
Moving --> Crash
Crash --> [*]
```

Lo que se muestra como:

stateDiagram [*] --> Still Still --> [*] Still --> Moving Moving --> Still Moving --> Crash Crash --> [*]

Listas de tareas por hacer

También se pueden hacer listas de tareas por hacer como en Markdown:


```markdown
- [x] Write math example
  - [x] Write diagram example
- [ ] Do something else
```

Se muestra como:

- [x] Write math example
  - [x] Write diagram example
- [ ] Do something else

Tablas

Si se guardan datos tabulados en CSV en un archivo en la carpeta del artículo se pueden mostrar como una tabla con el siguiente código:

{{< table path="results.csv" header="true" caption="Tabla 1: Mis resultados" >}}

Se muestra como:

customer_id score
1 0
2 0.5
3 1
Tabla 1: Mis resultados

Llamadas

El atajo para llamadas (callouts, también llamadas asides, hints o alertas/, una especie de ladillo, sería {{% callout note %}} ... {{% /callout %}} o:

{{% callout note %}}
A Markdown aside is useful for displaying notices, hints, or definitions to your readers.
{{% /callout %}}

Lo que se muestra como:

A Markdown aside is useful for displaying notices, hints, or definitions to your readers.

Spoilers

Se puede añadir un spoiler a una página para mostrar, por ejemplo, la respuesta a una pregunta una vez que se pincha en un botón:

{{< spoiler text="Pincha para ver la respuesta" >}}
¡¡Me encontraste!!
{{< /spoiler >}}

Lo cual se muestra:

Pincha para ver la respuesta

¡¡Me encontraste!!

Iconos

Se pueden utilizar los iconos de Font Awesome y de Academicons además de los emojis.

Algunos ejemplos a través del atajo icon para mostrar iconos:

{{< icon name="terminal" pack="fas" >}} Terminal
{{< icon name="python" pack="fab" >}} Python
{{< icon name="r-project" pack="fab" >}} R

Lo que se muestra como:

Terminal Python R

Awesome

🙌

Adolfo Antón Bravo
Adolfo Antón Bravo
periodismo como código

Interesado por la Web Semántica, el Periodismo, la Visualización y la Ciencia de Datos.