Shortcodes personalizados

19 feb 2023
5 mins de lectura
Etiquetas:
funcionalidad,
shortcodes

Actualizado el 15 feb 2025
Ver cambios

Shortcodes de diagramas

Diagramas de Mermaid

Mermaid es una herramienta de diagramación y gráficos que usa texto y código para generar diagramas. Admite diagramas de flujo, diagramas de secuencia, gráficos de Gantt y más.

Para incluir un diagrama Mermaid en tu publicación, sigue estos dos pasos:

Establece mermaid = true en la sección [extra] del front matter de tu página, sección o config.toml. Esto cargará el JavaScript necesario para renderizar los diagramas.
Usa el shortcode mermaid() para definir tu diagrama. Por ejemplo:

{% mermaid() %}
classDiagram
    class DistorsionesCognitivas {
        +PensamientoTodoONada()
        +Sobregeneralizacion()
        +FiltroMental()
        +SacarConclusionesPrecipitadas()
    }
    class PensamientoTodoONada {
        +VerEnExtremos()
    }
    class Sobregeneralizacion {
        +GeneralizarDeUnicoEjemplo()
    }
    class FiltroMental {
        +EnfocarseEnNegativo()
    }
    class SacarConclusionesPrecipitadas {
        +HacerSuposiciones()
    }
    DistorsionesCognitivas *-- PensamientoTodoONada
    DistorsionesCognitivas *-- Sobregeneralizacion
    DistorsionesCognitivas *-- FiltroMental
    DistorsionesCognitivas *-- SacarConclusionesPrecipitadas
{% end %}

El diagrama se renderizará así:

    classDiagram
    class DistorsionesCognitivas {
        +PensamientoTodoONada()
        +Sobregeneralizacion()
        +FiltroMental()
        +SacarConclusionesPrecipitadas()
    }
    class PensamientoTodoONada {
        +VerEnExtremos()
    }
    class Sobregeneralizacion {
        +GeneralizarDeUnicoEjemplo()
    }
    class FiltroMental {
        +EnfocarseEnNegativo()
    }
    class SacarConclusionesPrecipitadas {
        +HacerSuposiciones()
    }
    DistorsionesCognitivas *-- PensamientoTodoONada
    DistorsionesCognitivas *-- Sobregeneralizacion
    DistorsionesCognitivas *-- FiltroMental
    DistorsionesCognitivas *-- SacarConclusionesPrecipitadas

El shortcode de Mermaid admite dos parámetros:

invertible: Si se establece en true (por defecto), el diagrama se invertirá en modo oscuro, igual que las imágenes invertibles.
full_width: Permite que el diagrama ocupe el ancho del encabezado. Mira imagen a ancho completo.

CONSEJO

Puedes usar el editor de Mermaid para crear y previsualizar tus diagramas.

Uso

{% mermaid(invertible=true, full_width=false) %}

Tu diagrama Mermaid va aquí. Puedes omitir los parámetros para usar los valores predeterminados.

{% end %}

Shortcodes de imagen

Todos los shortcodes de imagen admiten rutas absolutas, rutas relativas, y fuentes remotas en el parámetro src.

Todos los shortcodes de imagen tienen los siguientes parámetros opcionales:

raw_path. Por defecto es false. Si se establece en true, el parámetro src se usará tal cual. Útil para activos ubicados en la misma carpeta que tienen un slug personalizado (ver Zola issue #2598).
inline. Valor predeterminado: false. Si se establece true, la imagen se mostrará en línea con el texto.
full_width. Valor predeterminado: false (ver más abajo).
lazy_loading. Valor predeterminado: true.

Imágenes de doble tema

Útil si deseas usar una imagen diferente para los temas claro y oscuro:

Uso

{{ dual_theme_image(light_src="img/paris_day.webp", dark_src="img/paris_night.webp" alt="La Torre Eiffel") }}

Imagen invertible

Ideal para gráficos, dibujos lineales, diagramas… Invierte los colores de la imagen. La imagen de origen se utilizará para el tema claro.

Uso

{{ invertible_image(src="img/graph.webp", alt="Gráfico invertible") }}

Imagen atenuable

Las imágenes con demasiado brillo o contraste pueden ser demasiado discordantes en un fondo oscuro. Aquí tienes un ejemplo de una fotografía que se atenúa cuando el tema oscuro está activo.

Fotografía de un desierto, cielo celestial

Uso

{{ dimmable_image(src="img/desert_by_oskerwyld.webp", alt="Fotografía de un desierto, cielo celestial") }}

Cambio de imagen al pasar el cursor

La imagen mostrada cambia cuando el usuario pasa el cursor por encima. Útil para comparaciones de antes y después, por ejemplo.

Uso

{{ image_hover(default_src="img/before.webp", hovered_src="img/after.webp", default_alt="Imagen editada", hovered_alt="Toma original") }}

Cambio de imagen vía click

Muestra una imagen y cambia a una diferente al hacer clic. Ideal para destacar diferencias o llamar la atención sobre detalles.

Uso

{{ image_toggler(default_src="img/mojave_day.webp", toggled_src="img/mojave_night.webp", default_alt="Mojave durante el día", toggled_alt="Mojave durante la noche") }}

Imagen a ancho completo

La imagen se expandirá para coincidir con el ancho del encabezado, que generalmente es más ancho que el texto del artículo (excepto en móvil/ventanas pequeñas).

Todos los otros shortcodes de imágenes pueden usar el ancho completo asignando el valor true al parámetro opcional full_width.

Uso

{{ full_width_image(src="img/amsterdam_by_oskerwyld.webp", alt="Fotografía de un canal en Ámsterdam") }}

Shortcodes de código

Mostrar ruta o URL

Puedes mostrar una ruta o URL para un bloque de código usando la sintaxis nativa de Zola:

```rust,name=src/main.rs
fn main() {
    println!("¡Hola, mundo!");
}
```

Esto renderiza:

fn main() {
    println!("¡Hola, mundo!");
}

Si estableces el name como una URL (es decir, comienza con http o https), puedes convertirlo en un enlace clickable. Esto es particularmente útil cuando se usa junto con el shortcode de texto remoto.

JavaScript requerido

La función de URLs clickables requiere JavaScript. Para habilitarla, configura code_block_name_links = true en la sección [extra] de tu página, sección, o config.toml.

__pycache__/
*coverage*
.vscode/
dist/

Soporte de shortcode heredado

El shortcode add_src_to_code_block sigue funcionando por retrocompatibilidad, pero será descontinuado en una versión futura. Por favor, usa la sintaxis nativa de Zola:

# Forma antigua (descontinuada):
{{ add_src_to_code_block(src="ruta/al/archivo.rs") }}

# Forma nueva (recomendada):
```rust,name=ruta/al/archivo.rs

Shortcodes de texto

Aside (nota al margen)

Añade contenido complementario en los márgenes en pantallas anchas, o como bloques distintivos en móvil.

El shortcode acepta dos parámetros:

position: Establecer como "right" para colocar en el margen derecho (por defecto, izquierdo)
El contenido puede proporcionarse mediante el parámetro text o entre las etiquetas del shortcode

Uso

WARNING

Separa la llamada al shortcode con saltos de línea para evitar errores de renderizado.

Usando el parámetro text:

{{ aside(text="*Nota al margen* viene de *nota* (del latín, 'marca' o 'señal') y *margen* (del latín *margo*, 'borde' o 'límite').") }}

Usando el cuerpo del contenido e indicando la posición:

{% aside(position="right") %}
Una nota más larga que
puede ocupar varias líneas.

Se admite *Markdown*.
{% end %}

Texto remoto

Añade texto desde una URL remota o un archivo local.

El shortcode acepta tres parámetros:

src: La URL de origen o ruta del archivo (obligatorio)
start: Primera línea a mostrar (opcional, empieza en 1)
end: Número de la última línea (opcional, por defecto es 0, la última línea)

INFO

start y end son inclusivos. start=3, end=3 mostrará solo la tercera línea.

Importante:

Archivos remotos VS archivos locales: Si src empieza con “http”, se tratará como un archivo remoto. De lo contrario, se asume que es una ruta de archivo local.
Acceso a archivos: Dado que utiliza la función load_data de Zola, los archivos locales deben estar dentro del directorio de Zola —ver la lógica de búsqueda de archivos. Desde tabi 2.16.0, el shortcode admite también rutas relativas.
Formateo de bloques de código: Para mostrar el texto como un bloque de código, debes añadir manualmente las cercas de código Markdown (comillas invertidas) y, opcionalmente, especificar el lenguaje de programación para el resaltado sintáctico.

Uso

Añade un script de Python remoto dentro de un bloque de código con resaltado sintáctico:

```python
{{ remote_text(src="https://example.com/script.py") }}
```

Visualización de texto de un archivo local:

{{ remote_text(src="ruta/a/archivo.txt") }}

Mostar sólo las líneas 3 a 5 de un archivo remoto:

{{ remote_text(src="https://example.com/script.py", start=3, end=5) }}

Advertencias

Destaca información con estos shortcodes. Hay cinco tipos (type): note, tip, info, warning, y danger.

NOTE