✨ feat: add Mermaid diagram support (#370)

README.md

@@ -44,6 +44,7 @@ tabi has a perfect score on Google's Lighthouse audit:
 - [X] [Comprehensive multi-language support](https://welpo.github.io/tabi/blog/faq-languages/#how-does-tabi-handle-multilingual-support). Add as many languages as you wish.
 - [X] Support for [comments using giscus, utterances, Hyvor Talk, or Isso](https://welpo.github.io/tabi/blog/comments/).
 - [X] Code syntax highlighting with colours based on [Catppuccin](https://github.com/catppuccin/catppuccin) Frappé.
+- [X] [Mermaid support](https://welpo.github.io/tabi/blog/shortcodes/#mermaid-diagrams) to create diagrams and charts with text.
 - [X] [Local search](https://welpo.github.io/tabi/blog/mastering-tabi-settings/#search) with an accessible, multi-lingual interface.
 - [X] [Custom Twitter card](https://welpo.github.io/tabi/blog/mastering-tabi-settings/#social-media-cards) and automatic Open Graph tags.
 - [X] [KaTeX](https://katex.org/) support for mathematical notation.

config.toml

@@ -162,6 +162,16 @@ footnote_backlinks = false
 # Can be set at page or section levels, following the hierarchy: page > section > config. See: https://welpo.github.io/tabi/blog/mastering-tabi-settings/#settings-hierarchy
 katex = false
 
+# Enable Mermaid diagrams for all posts.
+# Loads ~2.5MB of JavaScript.
+# Can be set at page or section levels, following the hierarchy: page > section > config. See: https://welpo.github.io/tabi/blog/mastering-tabi-settings/#settings-hierarchy
+mermaid = false
+
+# Serve Mermaid JavaScript locally. Version bundled with tabi.
+# If set to false, it will load the latest version from JSDelivr.
+# Only relevant when `mermaid = true`.
+serve_local_mermaid = true
+
 # Show links to previous and next articles at the bottom of posts.
 # Can be set at page or section levels, following the hierarchy: page > section > config. See: https://welpo.github.io/tabi/blog/mastering-tabi-settings/#settings-hierarchy
 show_previous_next_article_links = false

content/blog/javascript/index.ca.md

@@ -1,7 +1,7 @@
 +++
 title = "Sense JavaScript obligatori"
 date = 2023-01-06
-updated = 2024-07-01
+updated = 2024-08-28
 description = "JavaScript només s'utilitza quan HTML i CSS no són suficients."
 
 [taxonomies]
@@ -26,6 +26,7 @@ Aquest tema no requereix JavaScript obligatori. Opcionalment, pot carregar una q
 Les següents opcions es poden especificar per a publicacions, seccions i globalment, seguint la jerarquia de `pàgina > secció > config.toml`:
 
 - [**Suport de KaTeX**](@/blog/markdown/index.ca.md#katex). Habilitat configurant `katex = true` (274 KB).
+- [**Diagrames de Mermaid**](@/blog/shortcodes/index.ca.md#diagrames-de-mermaid). Habilitat configurant `mermaid = true` (~2.5 MB).
 - [**Còpia de blocs de codi amb un sol clic**](@/blog/markdown/index.ca.md#bloc-de-codi). Habilitada configurant `copy_button = true`. (~700 bytes)
 - [**Mostrar ruta/URL a blocs de codi**](@/blog/shortcodes/index.ca.md#mostrar-ruta-o-url). S'activa configurant `add_src_to_code_block = true`. (~400 bytes)
 

content/blog/javascript/index.es.md

@@ -1,7 +1,7 @@
 +++
 title = "Sin JavaScript obligatorio"
 date = 2023-01-06
-updated = 2024-07-01
+updated = 2024-08-28
 description = "JavaScript solo se utiliza cuando HTML y CSS no son suficientes."
 
 [taxonomies]
@@ -26,6 +26,7 @@ Este tema no requiere JavaScript de manera obligatoria. Opcionalmente, puede car
 Las siguientes opciones pueden especificarse para publicaciones, secciones y a nivel global, siguiendo la jerarquía de `página > sección > config.toml`:
 
 - [**Soporte de KaTeX**](@/blog/markdown/index.es.md#katex). Habilitado al configurar `katex = true` (274 KB).
+- [**Diagramas de Mermaid**](@/blog/shortcodes/index.es.md#diagramas-de-mermaid). Habilitado al configurar `mermaid = true` (~2.5 MB).
 - [**Copia de bloques de código con un solo clic**](@/blog/markdown/index.es.md#bloque-de-codigo). Habilitado al configurar `copy_button = true` (~700 bytes).
 - [**Mostrar ruta/URL en bloques de código**](@/blog/shortcodes/index.es.md#mostrar-ruta-o-url). Se activa configurando `add_src_to_code_block = true`. (~400 bytes)
 

content/blog/javascript/index.md

@@ -1,7 +1,7 @@
 +++
 title = "No mandatory JavaScript"
 date = 2023-01-06
-updated = 2024-07-01
+updated = 2024-08-28
 description = "JavaScript is only used when HTML and CSS aren't enough."
 
 [taxonomies]
@@ -26,6 +26,7 @@ This theme has no mandatory JavaScript. Optionally, it can load a minimal amount
 The following settings can be specified for posts, sections and globally, following the hierarchy of `page > section > config.toml`:
 
 - [**KaTeX support**](@/blog/markdown/index.md#katex). Enabled by setting `katex = true` (274 KB).
+- [**Mermaid diagrams**](@/blog/shortcodes/index.md#mermaid-diagrams). Enabled by setting `mermaid = true` (~2.5 MB).
 - [**One-click copy of code blocks**](@/blog/markdown/index.md#code-block). Enabled by setting `copy_button = true`. (~700 bytes)
 - [**Showing source (path or URL) in code blocks**](@/blog/shortcodes/index.md#show-source-or-path). Enabled by setting `add_src_to_code_block = true`. (~300 bytes)
 

content/blog/mastering-tabi-settings/index.ca.md

@@ -1,7 +1,7 @@
 +++
 title = "Domina la configuració de tabi: guia completa"
 date = 2023-09-18
-updated = 2024-08-13
+updated = 2024-08-28
 description = "Descobreix les múltiples maneres en què pots personalitzar tabi."
 
 [taxonomies]
@@ -576,6 +576,18 @@ Estableix `add_src_to_code_block = true` per habilitar l'ús del [shortcode `add
 
 KaTeX és una biblioteca JavaScript ràpida i fàcil d'usar per a la representació de matemàtiques TeX a la web. Pots habilitar-ho amb `katex = true`. Mira com es veu en tabi [aquí](/ca/blog/markdown/#katex).
 
+### Suport per a Mermaid
+
+| Pàgina | Secció | `config.toml` | Segueix la jerarquia | Requereix JavaScript |
+|:------:|:------:|:-------------:|:-----------------:|:--------------------:|
+|   ✅   |   ✅   |      ✅       |         ✅        |          ✅          |
+
+[Mermaid](https://github.com/mermaid-js/mermaid) és una eina de diagramació i gràfics basada en JavaScript. Pots activar-la amb `mermaid = true`.
+
+Per defecte, la biblioteca Mermaid es serveix localment. Si prefereixes utilitzar un CDN, estableix `serve_local_mermaid = false` a `config.toml`. L'ús d'un CDN servirà la versió més recent de Mermaid; l'opció local servirà la versió inclosa amb tabi.
+
+Consulta la [documentació de Mermaid](@/blog/shortcodes/index.ca.md#diagrames-de-mermaid) per a instruccions d'ús i exemples.
+
 ### Subconjunt de tipus de lletra personalitzat
 
 | Pàgina | Secció | `config.toml` | Segueix la jerarquia | Requereix JavaScript |

content/blog/mastering-tabi-settings/index.es.md

@@ -1,7 +1,7 @@
 +++
 title = "Domina la configuración de tabi: guía completa"
 date = 2023-09-18
-updated = 2024-08-13
+updated = 2024-08-28
 description = "Descubre las múltiples maneras en que puedes personalizar tabi."
 
 [taxonomies]
@@ -576,6 +576,18 @@ Establece `add_src_to_code_block = true` para habilitar el uso del [shortcode `a
 
 KaTeX es una biblioteca JavaScript rápida y fácil de usar para la representación de matemáticas TeX en la web. Puedes habilitarlo con `katex = true`. Mira cómo se ve en tabi [aquí](/es/blog/markdown/#katex).
 
+### Soporte para Mermaid
+
+| Página | Sección | `config.toml` | Sigue la jerarquía | Requiere JavaScript |
+|:------:|:-------:|:-------------:|:----------------:|:-------------------:|
+|   ✅   |    ✅   |      ✅       |        ✅        |         ✅          |
+
+[Mermaid](https://github.com/mermaid-js/mermaid) es una herramienta de diagramación y gráficos basada en JavaScript. Puedes activarla con `mermaid = true`.
+
+Por defecto, la biblioteca Mermaid se sirve localmente. Si prefieres usar un CDN, establece `serve_local_mermaid = false` en `config.toml`. El uso de un CDN servirá la versión más reciente de Mermaid; la opción local servirá la versión incluida con tabi.
+
+Consulta la [documentación de Mermaid](@/blog/shortcodes/index.es.md#diagramas-de-mermaid) para instrucciones de uso y ejemplos.
+
 ### Subconjunto de fuente personalizada
 
 | Página | Sección | `config.toml` | Sigue la jerarquía | Requiere JavaScript |

content/blog/mastering-tabi-settings/index.md

@@ -1,7 +1,7 @@
 +++
 title = "Mastering tabi Settings: A Comprehensive Guide"
 date = 2023-09-18
-updated = 2024-08-13
+updated = 2024-08-28
 description = "Discover the many ways you can customise your tabi site."
 
 [taxonomies]
@@ -584,6 +584,18 @@ Setting `add_src_to_code_block = true` enables the use of the [`add_src_to_code_
 
 KaTeX is a fast, easy-to-use JavaScript library for TeX math rendering on the web. You can enable it with `katex = true`. See what it looks like in tabi [here](/blog/markdown/#katex).
 
+### Mermaid Support
+
+| Page | Section | `config.toml` | Follows Hierarchy | Requires JavaScript |
+|:----:|:-------:|:-------------:|:-----------------:|:-------------------:|
+|  ✅  |    ✅    |      ✅       |         ✅         |         ✅          |
+
+[Mermaid](https://github.com/mermaid-js/mermaid) is a JavaScript-based diagramming and charting tool. You can enable it with `mermaid = true`.
+
+By default, the Mermaid library is served locally. If you prefer to use a CDN, set `serve_local_mermaid = false` in `config.toml`. Using a CDN will serve the latest version of Mermaid; the local option will serve the version bundled with tabi.
+
+See the [Mermaid documentation](@/blog/shortcodes/index.md#mermaid-diagrams) for usage instructions and examples.
+
 ### Custom Font Subset
 
 | Page | Section | `config.toml` | Follows Hierarchy | Requires JavaScript |

content/blog/security/index.ca.md

@@ -1,7 +1,7 @@
 +++
 title = "Seguretat per defecte"
 date = 2023-02-22
-updated = 2024-05-30
+updated = 2024-08-28
 description = "tabi té una Política de Seguretat de Contingut (CSP) fàcilment personalitzable amb valors segurs per defecte. Obtingues tranquil·litat i un A+ en l'Observatori de Mozilla."
 
 [taxonomies]
@@ -34,7 +34,7 @@ Pots desactivar les capçaleres (permitint-ho tot) en una pàgina, secció, o gl
 
 **Notas**:
 
-- [Habilitar els comentaris](@/blog/comments/index.ca.md) o [les analítiques](@/blog/mastering-tabi-settings/index.ca.md#analisi-web) automàticament permet scripts/frames/estils/connexions en funció del servei habilitat.
+- [Habilitar els comentaris](@/blog/comments/index.ca.md), [les analítiques](@/blog/mastering-tabi-settings/index.ca.md#analisi-web), o [els diagrames de mermaid](@/blog/shortcodes/index.ca.md#diagrames-de-mermaid) permet automàticament els scripts/frames/estils/conexions pertinents.
 - Per utilitzar un [tema de resaltat de sintaxis integrat a Zola](https://www.getzola.org/documentation/getting-started/configuration/#syntax-highlighting), has de permetre `unsafe-inline` a la directiva `style-src`:
 
     ```

content/blog/security/index.es.md

@@ -1,7 +1,7 @@
 +++
 title = "Seguro por defecto"
 date = 2023-02-22
-updated = 2024-05-30
+updated = 2024-08-28
 description = "tabi tiene una Política de Seguridad de Contenido (CSP) fácilmente personalizable con configuraciones seguras. Obtén tranquilidad y una calificación de A+ en Mozilla Observatory."
 
 [taxonomies]
@@ -34,7 +34,7 @@ Puedes desactivar las cabeceras (permitiendo todo) en una página, sección, o g
 
 **Notas**:
 
-- [Habilitar los comentarios](@/blog/comments/index.es.md) o [las analíticas](@/blog/mastering-tabi-settings/index.es.md#analisis-web) automáticamente permite scripts/frames/estilos/conexiones en función del servicio habilitado.
+- [Habilitar los comentarios](@/blog/comments/index.es.md), [las analíticas](@/blog/mastering-tabi-settings/index.es.md#analisis-web), o [los diagramas mermaid](@/blog/shortcodes/index.es.md#diagramas-de-mermaid) permite automáticamente los scripts/frames/estilos/conexiones pertinentes.
 - Para usar un [tema de resaltado de sintaxis integrado en Zola](https://www.getzola.org/documentation/getting-started/configuration/#syntax-highlighting), has de permitir `unsafe-inline` en la directiva `style-src`:
 
     ```

content/blog/security/index.md

@@ -1,7 +1,7 @@
 +++
 title = "Secure by default"
 date = 2023-02-22
-updated = 2024-05-30
+updated = 2024-08-28
 description = "tabi has an easily customizable Content Security Policy (CSP) with safe defaults. Get peace of mind and an A+ on Mozilla Observatory."
 
 [taxonomies]
@@ -34,7 +34,7 @@ You can disable the CSP (allowing all connections) on a page, section, or global
 
 **Notes**:
 
-- [Enabling comments](@/blog/comments/index.md) or [analytics](@/blog/mastering-tabi-settings/index.md#analytics) automatically allows scripts/frames/styles/connections as needed from the respective services.
+- [Enabling comments](@/blog/comments/index.md), [analytics](@/blog/mastering-tabi-settings/index.md#analytics), or [mermaid diagrams](@/blog/shortcodes/index.md#mermaid-diagrams) automatically allows scripts/frames/styles/connections as needed.
 - To use a [Zola built-in syntax highlighting theme](https://www.getzola.org/documentation/getting-started/configuration/#syntax-highlighting), you need to allow `unsafe-inline` in the `style-src` directive:
 
     ```

content/blog/shortcodes/index.ca.md

@@ -1,7 +1,7 @@
 +++
 title = "Shortcodes personalitzats"
 date = 2023-02-19
-updated = 2024-06-27
+updated = 2024-08-28
 description = "Aquest tema inclou alguns shortcodes personalitzats útils que pots utilitzar per millorar les teves publicacions. Ja sigui per mostrar imatges que s'adapten als temes clar i fosc, o per donar format a una secció de referències amb un aspecte professional, aquests shortcodes personalitzats t'ajudaran."
 
 [taxonomies]
@@ -12,9 +12,85 @@ toc = true
 toc_levels = 2
 quick_navigation_buttons = true
 add_src_to_code_block = true
+mermaid = true
 social_media_card = "social_cards/ca_blog_shortcodes.jpg"
 +++
 
+## Shortcodes de diagrames
+
+### Diagrames de Mermaid
+
+[Mermaid](https://github.com/mermaid-js/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:
+
+1. 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.
+
+2. Utilitza el shortcode `mermaid()` per definir el teu diagrama. Per exemple:
+
+```plaintext
+{%/* 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í:
+
+{% 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 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](#imatge-invertible).
+- `full_width`: Permet que el diagrama ocupi l'amplada de la capçalera. Mira [imatge d'amplada completa](#imatge-d-amplada-completa).
+
+{{ admonition(type="tip", title="CONSELL", text="Empra l'[editor de Mermaid](https://mermaid.live/) per crear i previsualitzar els teus diagrames.") }}
+
 ## Shortcodes d'imatge
 
 Tots els shortcodes d'imatge admeten rutes absolutes, rutes relatives, i fonts remotes en el paràmetre `src`.