Shortcodes personalitzats

19 de febr. 2023
5 mins de lectura
Etiquetes:
funcionalitat,
shortcodes

Actualitzat el 15 de febr. 2025
Veure canvis

Shortcodes de diagrames

Diagrames de Mermaid

Mermaid és una eina de diagramació i gràfics que utilitza text i codi per generar diagrames. Admet diagrames de flux, diagrames de seqüència, gràfics de Gantt i més.

Per incloure un diagrama Mermaid a la teva publicació, cal fer dues coses:

Estableix mermaid = true a la secció [extra] del front matter de la teva pàgina, secció o config.toml. Això carregarà el JavaScript necessari per renderitzar els diagrames.
Utilitza el shortcode mermaid() per definir el teu diagrama. Per exemple:

{% mermaid() %}
classDiagram
    class DistorsionsCognitives {
        +PensamentTotORes()
        +Sobregeneralitzacio()
        +FiltreMental()
        +TreureConclusionsPrecipitades()
    }
    class PensamentTotORes {
        +VeureEnExtrems()
    }
    class Sobregeneralitzacio {
        +GeneralitzarDUnic()
    }
    class FiltreMental {
        +EnfocarseEnNegatiu()
    }
    class TreureConclusionsPrecipitades {
        +FerSuposicions()
    }
    DistorsionsCognitives *-- PensamentTotORes
    DistorsionsCognitives *-- Sobregeneralitzacio
    DistorsionsCognitives *-- FiltreMental
    DistorsionsCognitives *-- TreureConclusionsPrecipitades
{% end %}

El diagrama es renderitzarà així:

    classDiagram
    class DistorsionsCognitives {
        +PensamentTotORes()
        +Sobregeneralitzacio()
        +FiltreMental()
        +TreureConclusionsPrecipitades()
    }
    class PensamentTotORes {
        +VeureEnExtrems()
    }
    class Sobregeneralitzacio {
        +GeneralitzarDUnic()
    }
    class FiltreMental {
        +EnfocarseEnNegatiu()
    }
    class TreureConclusionsPrecipitades {
        +FerSuposicions()
    }
    DistorsionsCognitives *-- PensamentTotORes
    DistorsionsCognitives *-- Sobregeneralitzacio
    DistorsionsCognitives *-- FiltreMental
    DistorsionsCognitives *-- TreureConclusionsPrecipitades

El shortcode de Mermaid admet dos paràmetres:

invertible: Si s’estableix a true (per defecte), el diagrama invertirà els seus colors en mode fosc, igual que les imatges invertibles.
full_width: Permet que el diagrama ocupi l’amplada de la capçalera. Mira imatge d’amplada completa.

CONSELL

Empra l’editor de Mermaid per crear i previsualitzar els teus diagrames.

Ús

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

El teu codi Mermaid va aquí.

`invertible` or `full_width` poden ometre's per emprar els valors per defecte.

{% end %}

Shortcodes d’imatge

Tots els shortcodes d’imatge admeten rutes absolutes, rutes relatives, i fonts remotes en el paràmetre src.

Tots els shortcodes d’imatge tenen els següents paràmetres opcionals:

raw_path. Per defecte és false. Si es configura a true, el paràmetre src s’utilitzarà tal qual. Útil per a actius ubicats a la mateixa carpeta que tenen un slug personalitzat (vegeu Zola issue #2598).
inline. Valor predeterminat: false. Si s’estableix a true, la imatge es mostrarà en línia amb el text.
full_width. Valor predeterminat: false (vegeu a sota).
lazy_loading. Valor predeterminat: true.

Imatges per a temes duals

Útil si vols utilitzar una imatge diferent pels temes clar i fosc:

Ús

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

Imatge invertible

Útil per a gràfics, dibuixos de línies, diagrames… Inverteix els colors de la imatge. La imatge original s’utilitzarà per al tema clar.

Ús

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

Imatge regulable

Les imatges amb massa brillantor o contrast poden ser molestes en un fons fosc. Aquí tens un exemple d’una fotografia que s’atenua quan s’activa el tema fosc.

Ús

{{ dimmable_image(src="img/desert_by_oskerwyld.webp", alt="Fotografia d'un desert, cel celestial") }}

Canvi d’imatge en passar el cursor

La imatge mostrada canvia quan l’usuari passa el cursor per sobre. Útil per a comparacions d’abans i després, per exemple.

Ús

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

Canvi d’imatge via clic

Mostra una imatge i canvia a una diferent en fer clic. Ideal per destacar diferències o cridar l’atenció sobre detalls.

Ús

{{ image_toggler(default_src="img/mojave_day.webp", toggled_src="img/mojave_night.webp", default_alt="Mojave de dia", toggled_alt="Mojave de nit") }}

Imatge d’amplada completa

La imatge s’expandirà per coincidir amb l’amplada de la capçalera, que normalment és més ampla que el text de l’article (excepte en mòbil/finestres petites).

Tots els altres shortcodes d’imatges poden utilizar l’amplada completa assignant true al paràmetre opcional full_width.

Ús

{{ full_width_image(src="img/amsterdam_by_oskerwyld.webp", alt="Fotografia d'un canal a Àmsterdam") }}

Shortcodes de codi

Mostrar ruta o URL

Pots mostrar una ruta o URL per a un bloc de codi utilitzant la sintaxi nativa de Zola:

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

Això renderitza:

fn main() {
    println!("Hola, món!");
}

Si estableixes el name com una URL (és a dir, comença amb http o https), pots convertir-lo en un enllaç clicable. Això és particularment útil quan s’utilitza juntament amb el shortcode de text remot.

JavaScript necessari

La funció d’URLs clicables requereix JavaScript. Per habilitar-la, configura code_block_name_links = true a la secció [extra] de la teva pàgina, secció, o config.toml.

__pycache__/
*coverage*
.vscode/
dist/

Suport de shortcode heretat

El shortcode add_src_to_code_block segueix funcionant per retrocompatibilitat però serà descontinuat en una versió futura. Si us plau, utilitza la sintaxi nativa de Zola:

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

# Forma nova (recomanada):
```rust,name=ruta/al/fitxer.rs

Ús

{{ add_src_to_code_block(src="https://github.com/welpo/doteki/blob/main/.gitignore") }}
```.gitignore
**pycache**/
*coverage*
.vscode/
dist/
```

Shortcodes de text

Aside (nota al marge)

Afegeix contingut complementari als marges en pantalles amples, o com a blocs distintius en mòbil.

El shortcode accepta dos paràmetres:

position: Establir com a "right" per col·locar al marge dret (per defecte, esquerre)
El contingut es pot proporcionar mitjançant el paràmetre text o entre les etiquetes del shortcode

Ús

WARNING

Separa la definició de la nota del shortcode amb dues línies en blanc per evitar errors de renderització.

Fent servir el paràmetre text:

{{ aside(text="*Nota al marge* ve de *nota* (del llatí, 'marca' o 'senyal') i *marge* (del llatí *margo*, 'vora' o 'límit').") }}

Fent servir el cos del contingut i indicant la posició a la dreta:

{% aside(position="right") %}
Una nota més llarga que
pot ocupar diverses línies.

S'admet *Markdown*.
{% end %}

Text remot

Afegeix text des d’una URL remota o un arxiu local.

El shortcode accepta tres paràmetres:

src: L’URL d’origen o ruta del fitxer (obligatori)
start: Primera línia a mostrar (opcional, comença a 1)
end: Número de l’última línia (opcional, per defecte és 0, l’última línia)

INFO

start i end són inclusius. start=3, end=3 mostrarà només la tercera línia.

Important:

Arxius remots VS arxius locals: Si src comença amb “http”, es tractarà com un arxiu remot. D’altra banda, s’assumeix que és una ruta d’arxiu local.
Accés a arxius: Atès que utilitza la funció load_data de Zola, els arxius locals han d’estar dins del directori de Zola —vegeu la lògica de cerca d’arxius. Desde tabi 2.16.0, el shortcode admet també rutes relatives.
Formateig de blocs de codi: Per mostrar el text com un bloc de codi, has d’afegir manualment les tanques de codi Markdown (cometes inverses) i, opcionalment, especificar el llenguatge de programació per al ressaltat sintàctic.

Ús

Afegeix un script de Python remot dins d’un bloc de codi amb ressaltat sintàctic:

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

Mostra el text d’un arxiu local:

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

Mostreu només les línies 3 a 5 d’un arxiu local:

{{ remote_text(src="ruta/a/arxiu.txt", start=3, end=5) }}

Advertències

Destaca informació amb aquests shortcodes. Hi ha cinc tipus (type): note, tip, info, warning, i danger.

NOTE