Publicando contenido técnico en Hugo con Markdown y Blox

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:

{{< 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:

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:

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:

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:

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:

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:

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:

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:

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:

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

🙌