Escribir contenido técnico en Markdown
Créditos: John Moeses Bauan
Wowchemy está diseñado para ofrecer a los creadores de contenido una experiencia perfecta, es decir, céntrate en marcar el contenido que Wowchemy se ocupa de los demás.
Wowchemy se encarga de resaltar la sintaxis de los bloques de código, de las notas o de los bloques de matemáticas y crea diagramas de la representación textual..
A continuación se muestran algunos ejemplos:
Ejemplos
Código
Wowchemy soporta una extensión de Markdown para el resaltado de sintaxis. Se puede personalizar el estilo con la opción syntax_highlighter en el archivo config/_default/params.yaml.
Python
Por ejemplo, este código Python:
```python
import pandas as pd
data = pd.read_csv("data.csv")
data.head()
```
Se convierte en:
import pandas as pd
data = pd.read_csv("data.csv")
data.head()
R
O este código R:
```R
install.packages('tidyverse')
library(tidyverse)
ggplot(data = mpg)
```
Se convierte en:
install.packages('tidyverse')
library(tidyverse)
ggplot(data = mpg)
Mapas mentales
Wowchemy soporta una extensión de Markdown para mapas mentales. Tal solo hay que insertar un bloque de código markmap y opcionalmente establecer la altura con height:
```markmap {height="200px"}
- Hugo Modules
- wowchemy
- wowchemy-plugins-netlify
- wowchemy-plugins-netlify-cms
- wowchemy-plugins-reveal
```
Se convierte en:
- Hugo Modules - wowchemy - wowchemy-plugins-netlify - wowchemy-plugins-netlify-cms - wowchemy-plugins-reveal
Un mapa mental más avanzdo que combina formateado, bloques de código y matemáticas:
```markmap
- Mindmaps
- Links
- [Wowchemy Docs](https://wowchemy.com/docs/)
- [Discord Community](https://discord.gg/z8wNYzb)
- [GitHub](https://github.com/wowchemy/wowchemy-hugo-themes)
- 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}$
```
Se convierte en:
- Mindmaps
- Links
- [Wowchemy Docs](https://wowchemy.com/docs/)
- [Discord Community](https://discord.gg/z8wNYzb)
- [GitHub](https://github.com/wowchemy/wowchemy-hugo-themes)
- 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
Wowchemy soporta el popular formato de Plotly para gráficos interactivos. Tan solo hay que guardar un JSON en el mismo directorio para que sea renderizado.
Por ejemplo, se incluye line-chart.json en este directorio, se incluye el código {{< chart data="line-chart" >}} donde debe aparecer y… tachán:
Para editar y previsualizar un JSON con Plotly se puede usar el Plotly JSON Editor.
Matemáticas
Wowchemy soporta una extensión Markdown para la sintaxis de matemáticas en $\LaTeX$. Se puede habilitar esta característica en la opción math del archivo config/_default/params.yaml.
Para renderizar este código en línea o en bloques de código se tiene que rodear con {{< math >}}$...${{< /math >}} para código en línea o {{< math >}}$$...$${{< /math >}} para bloques de código. (Se rodea el código de matemáticas de LaTeX así _math_ para prevenir a Hugo de renderizarlo como Markdown. El código _math_ es nuevo desde v5.5-dev.)
Ejemplo de bloque
{{< 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 >}}
Lo cual renderiza como:
$$\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}$$Ejemplo de código en línea
Este código {{< math >}}$\nabla F(\mathbf{x}_{n})${{< /math >}} renderiza como
$\nabla F(\mathbf{x}_{n})$.
Ejemplo de matemáticas multilínea
Se utiliza el salto de línea con \\:
{{< math >}}
$$f(k;p_{0}^{*}) = \begin{cases}p_{0}^{*} & \text{if }k=1, \\
1-p_{0}^{*} & \text{if }k=0.\end{cases}$$
{{< /math >}}
Lo cual renderiza como:
$$ f(k;p_{0}^{*}) = \begin{cases}p_{0}^{*} & \text{if }k=1, \\ 1-p_{0}^{*} & \text{if }k=0.\end{cases} $$Diagramas
Wowchemy soporta una extensión de Markdown para diagramas. Se puede habilitar con la opción diagram en el archivo config/_default/params.toml o añadiendo diagram: true en la página.
Flowchart
Para crear un gráfico de flujo:
```mermaid
graph TD
A[Hard] -->|Text| B(Round)
B --> C{Decision}
C -->|One| D[Result 1]
C -->|Two| E[Result 2]
```
Se convierte en:
Diagrama de secuencia
Un ejemplo de diagrama de secuencia:
```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!
```
Se convierte en:
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
```
Se convierte en:
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
```
Se convierte en:
Diagrama de estado
Un ejemplo de diagrama de estado:
```mermaid
stateDiagram
[*] --> Still
Still --> [*]
Still --> Moving
Moving --> Still
Moving --> Crash
Crash --> [*]
```
Se convierte en:
Listas de tareas por hacer
Se pueden escribir listas de tareas por hacer en Markdown:
- [x] Write math example
- [x] Write diagram example
- [ ] Do something else
Se convierte en:
- Write math example
- Write diagram example
- Do something else
Tablas
Se puede guardar un CSV en este directorio y se renderiza como una tabla en la página:
{{< table path="results.csv" header="true" caption="Tabla 1: Mis resultados" >}}
Lo que se convierte en:
| customer_id | score |
|---|---|
| 1 | 0 |
| 2 | 0.5 |
| 3 | 1 |
Llamadas de atención
El tema Academic soporta también un código para llamadas de atención o callouts en el original inglés, también referidas como asides, hints, o alerts.
Se puede poner este código rodeando un párrafo {{% callout note %}} ... {{% /callout %}} para que lo muestre como un bloque destacado. Esto:
{{% callout note %}}
Un bloque destacado o de atención es útil para mostrar noticias, consejos o definiciones.
{{% /callout %}}
Se convierte en:
Texto desplegable
Se puede añadir un bloque con texto que se despliegue al activarlo. Esto:
{{< spoiler text="Activa esto para ver el texto oculto" >}}
¡Viva la república!
{{< /spoiler >}}
Se convierte en:
Activa esto para ver el texto oculto
¡Viva la República!
Iconos
Se pueden utilizar iconos de Font Awesome_ y_Academicons_ además de los emojis.
Algunos ejemplos de uso de iconos:
Esto:
{{< icon name="terminal" pack="fas" >}} Terminal
{{< icon name="python" pack="fab" >}} Python
{{< icon name="r-project" pack="fab" >}} R
Se convierte en:
Terminal
Python
R
