✨ feat: add support for social media cards (#130)

.githooks/pre-commit

@@ -45,6 +45,48 @@ function contains_todo() {
     grep -q "TODO" "$file"
 }
 
+# Check for changes outside of the front matter.
+function has_body_changes() {
+    local file="$1"
+    local in_front_matter=1
+    local triple_plus_count=0
+
+    diff_output=$(git diff --unified=999 --cached --output-indicator-new='%' --output-indicator-old='&' "$file")
+
+    while read -r line; do
+        if [[ "$line" =~ ^\+\+\+$ ]]; then
+            triple_plus_count=$((triple_plus_count + 1))
+            if [[ $triple_plus_count -eq 2 ]]; then
+                in_front_matter=0
+            fi
+        elif [[ $in_front_matter -eq 0 ]]; then
+            if [[ "$line" =~ ^[\%\&] ]]; then
+                return 0
+            fi
+        fi
+    done <<< "$diff_output"
+    return 1
+}
+
+# Function to update the social media card for a post or section.
+function generate_and_commit_card {
+    local file=$1
+    social_media_card=$(social-cards-zola -o static/img/social_cards -b http://127.0.0.1:1025 -u -p -i "$file") || {
+        echo "Failed to update social media card for $file"
+        exit 1
+    }
+    
+    git add "$social_media_card" || {
+        echo "Failed to add social media card $social_media_card"
+        exit 1
+    }
+    
+    git add "$file" || {
+        echo "Failed to add $file"
+        exit 1
+    }
+}
+
 function has_minified_version() {
     local file="$1"
     local extension="${file##*.}"
@@ -94,7 +136,9 @@ fi
 # Compress PNG files with either oxipng or optipng if available. #
 # Update the "updated" field in the front matter of .md files.   #
 #          https://osc.garden/blog/zola-date-git-hook/           #
-# Interrupt the commit if a draft .md file is being committed.   #
+# Ensure the [extra] section from config.toml and theme.toml     #
+# have the same amount of lines.                                 #
+# Ensure JavaScript files are minified.                          #
 ##################################################################
 
 # Get the newly added and modified files.
@@ -114,13 +158,6 @@ for file in $all_changed_files; do
         continue
     fi
 
-    # If the file is an .md file and it's a draft, abort the commit.
-    if [[ "$file" == *.md ]]; then
-        if is_draft "$file"; then
-            error_exit "Draft file $file is being committed!"
-        fi
-    fi
-
     # If the file contains "TODO", abort the commit.
     if contains_todo "$file"; then
         error_exit "File $file contains TODO! Remove or complete the TODO before committing."
@@ -159,10 +196,21 @@ for file in $all_changed_files; do
 done
 
 # Get the modified .md to update the "updated" field in the front matter.
-modified_files=$(git diff --cached --name-only --diff-filter=M | grep -E '\.md$' | grep -v '_index.md$')
+modified_md_files=$(git diff --cached --name-only --diff-filter=M | grep -E '\.md$' | grep -v '_index.md$')
 
 # Loop through each modified .md file.
-for file in $modified_files; do
+for file in $modified_md_files; do
+    # If the file is an .md file and it's a draft, abort the commit.
+    if is_draft "$file"; then
+        error_exit "Draft file $file is being committed!"
+    fi
+
+    # If changes are only in the front matter, skip the file.
+    if ! has_body_changes "$file"; then
+        continue
+    fi
+
+    # Modify the "updated" date, if necessary.
     # Get the last modified date from the filesystem.
     last_modified_date=$(date -r "$file" +'%Y-%m-%d')
 
@@ -193,8 +241,14 @@ for file in $modified_files; do
 
     # Stage the changes.
     git add "$file"
+
 done
 
+# Use `social-cards-zola` to create/update the social media card for Markdown files.
+# See https://osc.garden/blog/automating-social-media-cards-zola/ for context.
+# Use parallel to create the social media cards in parallel and commit them.
+echo "$modified_md_files" | parallel -j 8 generate_and_commit_card
+
 #########################################################
 # Run subset_font if config.toml has been modified.     #
 # https://welpo.github.io/tabi/blog/custom-font-subset/ #

config.toml

@@ -222,8 +222,11 @@ favicon = "img/seedling.png"
 # Compatibility: https://caniuse.com/link-icon-svg
 favicon_emoji = "🌱"
 
-# This header image is used for SEO. For example if you were to share an image via Messenger/Instagram/Twitter a preview picture is also presented
+# Path to the fallback image for social media cards (the preview image shown when sharing a link on WhatsApp, LinkedIn…).
-headerImage = ""
+# Can be set at page or section levels, following the hierarchy: page > section > config. See: https://github.com/welpo/tabi/pull/128
+# Learn how to create these images in batch and automatically:
+# https://osc.garden/blog/automating-social-media-cards-zola/
+social_media_card = "img/social_cards/index.jpg"
 
 menu = [
     { name = "blog", url = "blog", trailing_slash = true },

content/_index.ca.md

@@ -8,6 +8,7 @@ template = "section.html"
 header = {title = "Hola! Soc tabi~", img = "img/main.webp" }
 section_path = "blog/_index.ca.md"
 max_posts = 4
+social_media_card = "img/social_cards/ca.jpg"
 +++
 
 tabi és un tema de [Zola](https://getzola.org) ràpid, lleuger i modern. Té com a objectiu ser una pàgina personal i llar d'entrades de blog. Compta amb una puntuació perfecta de Lighthouse, disseny responsive, tema fosc i clar, shortcodes personalitzats i molt més.

content/_index.es.md

@@ -8,6 +8,7 @@ template = "section.html"
 header = {title = "¡Hola! Soy tabi~", img = "img/main.webp" }
 section_path = "blog/_index.es.md"
 max_posts = 4
+social_media_card = "img/social_cards/es.jpg"
 +++
 
 tabi es un tema de [Zola](https://getzola.org) rápido, ligero y moderno. Su objetivo es ser una página personal y hogar para publicaciones de blogs. Cuenta con una puntuación perfecta en Lighthouse, diseño responsive, tema oscuro y claro, shortcodes personalizados y mucho más.

content/_index.md

@@ -8,6 +8,7 @@ template = "section.html"
 header = {title = "Hello! I'm tabi~", img = "img/main.webp" }
 section_path = "blog/_index.md"
 max_posts = 4
+social_media_card = "img/social_cards/index.jpg"
 +++
 
 tabi is a fast, lightweight, and modern [Zola](https://getzola.org) theme. It aims to be a personal page and home to blog posts. It features a perfect Lighthouse score, responsive design, dark and light themes, custom shortcodes, and much more.

content/archive/_index.ca.md

@@ -1,4 +1,7 @@
 +++
 title = "Arxiu"
 template = "archive.html"
+
+[extra]
+social_media_card = "img/social_cards/ca_archive.jpg"
 +++

content/archive/_index.es.md

@@ -1,4 +1,7 @@
 +++
 title = "Archivo"
 template = "archive.html"
+
+[extra]
+social_media_card = "img/social_cards/es_archive.jpg"
 +++

content/archive/_index.md

@@ -1,4 +1,7 @@
 +++
 title = "Archive"
 template = "archive.html"
+
+[extra]
+social_media_card = "img/social_cards/archive.jpg"
 +++

content/blog/_index.ca.md

@@ -5,4 +5,7 @@ title = "Blog"
 sort_by = "date"
 template = "section.html"
 insert_anchor_links = "left"
+
+[extra]
+social_media_card = "img/social_cards/ca_blog.jpg"
 +++

content/blog/_index.es.md

@@ -5,4 +5,7 @@ title = "Blog"
 sort_by = "date"
 template = "section.html"
 insert_anchor_links = "left"
+
+[extra]
+social_media_card = "img/social_cards/es_blog.jpg"
 +++

content/blog/_index.md

@@ -5,4 +5,7 @@ title = "Blog"
 sort_by = "date"
 template = "section.html"
 insert_anchor_links = "left"
+
+[extra]
+social_media_card = "img/social_cards/blog.jpg"
 +++

content/blog/comments.ca.md

@@ -11,6 +11,7 @@ tags = ["funcionalitat", "tutorial"]
 giscus = true
 quick_navigation_buttons = true
 toc = true
+social_media_card = "img/social_cards/ca_blog_comments.jpg"
 +++
 
 tabi actualment suporta quatre sistemes de comentaris: [giscus](https://giscus.app/ca) i [utterances](https://utteranc.es/), [Hyvor Talk](https://talk.hyvor.com/) i [Isso](https://isso-comments.de/).

content/blog/comments.es.md

@@ -11,6 +11,7 @@ tags = ["funcionalidad", "tutorial"]
 giscus = true
 quick_navigation_buttons = true
 toc = true
+social_media_card = "img/social_cards/es_blog_comments.jpg"
 +++
 
 tabi actualmente soporta cuatro sistemas de comentarios: [giscus](https://giscus.app/es) y [utterances](https://utteranc.es/), [Hyvor Talk](https://talk.hyvor.com/) e [Isso](https://isso-comments.de/).

content/blog/comments.md

@@ -11,6 +11,7 @@ tags = ["showcase", "tutorial"]
 giscus = true
 quick_navigation_buttons = true
 toc = true
+social_media_card = "img/social_cards/blog_comments.jpg"
 +++
 
 tabi currently supports four comment systems: [giscus](https://giscus.app/), [utterances](https://utteranc.es/), [Hyvor Talk](https://talk.hyvor.com/), and [Isso](https://isso-comments.de/).

content/blog/custom-font-subset.ca.md

@@ -6,6 +6,9 @@ description = "Aprèn com crear un subconjunt personalitzat que només inclogui
 
 [taxonomies]
 tags = ["funcionalitat", "tutorial"]
+
+[extra]
+social_media_card = "img/social_cards/ca_blog_custom_font_subset.jpg"
 +++
 
 ## El problema

content/blog/custom-font-subset.es.md

@@ -6,6 +6,9 @@ description = "Aprende cómo crear un subconjunto personalizado que solo incluya
 
 [taxonomies]
 tags = ["funcionalidad", "tutorial"]
+
+[extra]
+social_media_card = "img/social_cards/es_blog_custom_font_subset.jpg"
 +++
 
 ## El problema

content/blog/custom-font-subset.md

@@ -6,6 +6,9 @@ description = "Learn how to create a custom subset that only includes the necess
 
 [taxonomies]
 tags = ["showcase", "tutorial"]
+
+[extra]
+social_media_card = "img/social_cards/blog_custom_font_subset.jpg"
 +++
 
 ## The problem

content/blog/customise-tabi.ca.md

@@ -10,6 +10,7 @@ tags = ["funcionalitat", "tutorial"]
 [extra]
 toc = true
 quick_navigation_buttons = true
+social_media_card = "img/social_cards/ca_blog_customise_tabi.jpg"
 +++
 
 tabi pot ser personalitzat de dues maneres: establint el tema per defecte (fosc o clar) i triant el color principal per al tema ("skin").

content/blog/customise-tabi.es.md

@@ -10,6 +10,7 @@ tags = ["funcionalidad", "tutorial"]
 [extra]
 toc = true
 quick_navigation_buttons = true
+social_media_card = "img/social_cards/es_blog_customise_tabi.jpg"
 +++
 
 tabi puede ser personalizado de dos maneras: estableciendo el tema predeterminado (oscuro o claro) y eligiendo el color principal para el tema ("skin").

content/blog/customise-tabi.md

@@ -10,6 +10,7 @@ tags = ["showcase", "tutorial"]
 [extra]
 toc = true
 quick_navigation_buttons = true
+social_media_card = "img/social_cards/blog_customise_tabi.jpg"
 +++
 
 tabi can be customised in two ways: by setting the default theme (dark or light) and by choosing the main colour for the theme (skins).

content/blog/javascript.ca.md

@@ -9,6 +9,7 @@ tags = ["funcionalitat", "tutorial"]
 
 [extra]
 footnote_backlinks = true
+social_media_card = "img/social_cards/ca_blog_javascript.jpg"
 +++
 
 Aquest tema no requereix JavaScript obligatori. Opcionalment, pot carregar una quantitat mínima per afegir algunes característiques que són impossibles d'aconseguir amb HTML i CSS.

content/blog/javascript.es.md

@@ -9,6 +9,7 @@ tags = ["funcionalidad", "tutorial"]
 
 [extra]
 footnote_backlinks = true
+social_media_card = "img/social_cards/es_blog_javascript.jpg"
 +++
 
 Este tema no requiere JavaScript de manera obligatoria. Opcionalmente, puede cargar una cantidad mínima de JavaScript para añadir algunas características que son imposibles de lograr con solo HTML y CSS.

content/blog/javascript.md

@@ -9,6 +9,7 @@ tags = ["showcase", "tutorial"]
 
 [extra]
 footnote_backlinks = true
+social_media_card = "img/social_cards/blog_javascript.jpg"
 +++
 
 This theme has no mandatory JavaScript. Optionally, it can load a minimal amount to add some features that are impossible to achieve with HTML and CSS.

content/blog/markdown.ca.md

@@ -10,6 +10,7 @@ tags = ["markdown", "funcionalitat"]
 [extra]
 katex = true
 footnote_backlinks = true
+social_media_card = "img/social_cards/ca_blog_markdown.jpg"
 +++
 
 ## $\KaTeX$

content/blog/markdown.es.md

@@ -10,6 +10,7 @@ tags = ["markdown", "funcionalidad"]
 [extra]
 katex = true
 footnote_backlinks = true
+social_media_card = "img/social_cards/es_blog_markdown.jpg"
 +++
 
 ## $\KaTeX$

content/blog/markdown.md

@@ -10,6 +10,7 @@ tags = ["markdown", "showcase"]
 [extra]
 katex = true
 footnote_backlinks = true
+social_media_card = "img/social_cards/blog_markdown.jpg"
 +++
 
 ## $\KaTeX$

content/blog/security.ca.md

@@ -6,6 +6,9 @@ description = "tabi té una Política de Seguretat de Contingut (CSP) fàcilment
 
 [taxonomies]
 tags = ["seguretat", "funcionalitat"]
+
+[extra]
+social_media_card = "img/social_cards/ca_blog_security.jpg"
 +++
 
 La configuració per defecte del tema obté una puntuació A+ a l'[Observatori de Mozilla](https://observatory.mozilla.org).[^1]

content/blog/security.es.md

@@ -6,6 +6,9 @@ description = "tabi tiene una Política de Seguridad de Contenido (CSP) fácilme
 
 [taxonomies]
 tags = ["seguridad", "funcionalidad"]
+
+[extra]
+social_media_card = "img/social_cards/es_blog_security.jpg"
 +++
 
 La configuración predeterminada del tema obtiene una calificación de A+ en [Mozilla Observatory](https://observatory.mozilla.org).[^1]

content/blog/security.md

@@ -6,6 +6,9 @@ description = "tabi has an easily customizable Content Security Policy (CSP) wit
 
 [taxonomies]
 tags = ["security", "showcase"]
+
+[extra]
+social_media_card = "img/social_cards/blog_security.jpg"
 +++
 
 The default configuration of the theme gets an A+ score on [Mozilla Observatory](https://observatory.mozilla.org).[^1]

content/blog/shortcodes.ca.md

@@ -11,6 +11,7 @@ tags = ["funcionalitat", "shortcodes"]
 toc = true
 toc_levels = 2
 quick_navigation_buttons = true
+social_media_card = "img/social_cards/ca_blog_shortcodes.jpg"
 +++
 
 ## Shortcodes d'imatge

content/blog/shortcodes.es.md

@@ -11,6 +11,7 @@ tags = ["funcionalidad", "shortcodes"]
 toc = true
 toc_levels = 2
 quick_navigation_buttons = true
+social_media_card = "img/social_cards/es_blog_shortcodes.jpg"
 +++
 
 ## Shortcodes de imagen

content/blog/shortcodes.md

@@ -11,6 +11,7 @@ tags = ["showcase", "shortcodes"]
 toc = true
 toc_levels = 2
 quick_navigation_buttons = true
+social_media_card = "img/social_cards/blog_shortcodes.jpg"
 +++
 
 ## Image shortcodes

content/blog/toc.ca.md

@@ -10,6 +10,7 @@ tags = ["funcionalitat", "markdown", "tutorial"]
 [extra]
 toc = true
 quick_navigation_buttons = true
+social_media_card = "img/social_cards/ca_blog_toc.jpg"
 +++
 
 ## Documentació

content/blog/toc.es.md

@@ -10,6 +10,7 @@ tags = ["funcionalidad", "markdown", "tutorial"]
 [extra]
 toc = true
 quick_navigation_buttons = true
+social_media_card = "img/social_cards/es_blog_toc.jpg"
 +++
 
 ## Documentación

content/blog/toc.md

@@ -10,6 +10,7 @@ tags = ["showcase", "markdown", "tutorial"]
 [extra]
 toc = true
 quick_navigation_buttons = true
+social_media_card = "img/social_cards/blog_toc.jpg"
 +++
 
 ## Documentation

content/projects/_index.ca.md

@@ -2,4 +2,7 @@
 title = "Projectes"
 sort_by = "weight"
 template = "cards.html"
+
+[extra]
+social_media_card = "img/social_cards/ca_projects.jpg"
 +++

content/projects/_index.es.md

@@ -2,4 +2,7 @@
 title = "Proyectos"
 sort_by = "weight"
 template = "cards.html"
+
+[extra]
+social_media_card = "img/social_cards/es_projects.jpg"
 +++

content/projects/_index.md

@@ -2,4 +2,7 @@
 title = "Projects"
 sort_by = "weight"
 template = "cards.html"
+
+[extra]
+social_media_card = "img/social_cards/projects.jpg"
 +++

templates/macros/settings.html

@@ -1,4 +1,4 @@
-{# 
+{#
 Evaluates the priority of a particular setting across different scopes.
 
 The priority is as follows: page > section > config.
@@ -9,10 +9,12 @@ Parameters:
     - default_global_value: The setting's default value.
 #}
 
-{% macro evaluate_setting_priority(setting, page) %}
+{% macro evaluate_setting_priority(setting, page, section="", default_global_value="") %}
 
-{#- Retrieve last ancestor to determine current section, if applicable -#}
+{%- if section -%}
-{%- if page -%}
+    {%- set current_section = section -%}
+{%- elif page -%}
+    {#- Retrieve last ancestor to determine current section, if applicable -#}
     {%- set last_ancestor = page.ancestors | slice(start=-1) %}
     {%- set current_section = get_section(path=last_ancestor.0) %}
 {%- endif -%}
@@ -20,17 +22,14 @@ Parameters:
 {%- set priority_order = [
     page.extra[setting] | default(value=""),
     current_section.extra[setting] | default(value=""),
-    config.extra[setting] | default(value=default_global_value)
+    config.extra[setting] | default(value="")
 ] -%}
 
-{%- set output = "false" -%}
+{%- set output = default_global_value -%}
 
 {%- for value in priority_order -%}
-    {%- if value == true -%}
+    {%- if value != "" -%}
-        {%- set_global output = "true" -%}
+        {%- set_global output = value -%}
-        {%- break -%}
-    {%- elif value == false -%}
-        {%- set_global output = "false" -%}
         {%- break -%}
     {%- endif -%}
 {%- endfor -%}

templates/partials/header.html

@@ -51,31 +51,33 @@
         <link rel="stylesheet" href="{{ get_url(path=stylesheet, cachebust=true) | safe }}" />
     {%- endfor %}
     
-    <meta name="color-scheme" content="{%- if config.extra.theme_switcher -%}light dark{%- elif config.extra.default_theme -%}{{config.extra.default_theme}}{%- else -%}light{%- endif -%}">
+    <meta name="color-scheme" content="{%- if config.extra.theme_switcher -%}light dark{%- elif config.extra.default_theme -%}{{config.extra.default_theme}}{%- else -%}light{%- endif -%}" />
 
     {%- if page.description %}
         <meta name="description" content="{{ page.description | striptags | safe }}" />
-        <meta property="og:description" content="{{ page.description | striptags | safe }}">
+        <meta property="og:description" content="{{ page.description | striptags | safe }}" />
     {%- elif page.summary %}
         <meta name="description" content="{{ page.summary | striptags | safe | trim_end_matches(pat=".") }}…" />
-        <meta property="og:description" content="{{ page.summary | striptags | safe | trim_end_matches(pat=".") }}…">
+        <meta property="og:description" content="{{ page.summary | striptags | safe | trim_end_matches(pat=".") }}…" />
     {%- else %}
         <meta name="description" content="{{ config.description }}" />
-        <meta property="og:description" content="{{ config.description }}">
+        <meta property="og:description" content="{{ config.description }}" />
     {%- endif %}
 
     {% if is_404 %}
-        <meta name="robots" content="noindex, follow">
+        <meta name="robots" content="noindex, follow" />
     {% else %}
-        <meta name="robots" content="index, nofollow">
+        <meta name="robots" content="index, nofollow" />
     {% endif %}
 
-    <meta property="og:title" content="{{ config.title }}">
+    <meta property="og:title" content="{{ config.title }}" />
     <meta property="og:type" content="article" />
 
-    {% if config.extra.headerImage %}
+    {# Image for social media sharing #}
-        <meta property="og:image" content="{{ config.extra.headerImage }}">
+    {%- set social_media_card = macros_settings::evaluate_setting_priority(setting="social_media_card", page=page | default(value=""), section=section | default(value=""), default_global_value="") -%}
-        <meta name="twitter:card" content="{{ config.extra.headerImage }}">
+    {% if social_media_card %}
+        <meta property="og:image" content="{{ get_url(path=social_media_card, cachebust=true) }}" />
+        <meta name="twitter:card" content="summary_large_image" />
     {% endif %}
 
     {% set current_url = current_url | default(value="/") %}

theme.toml

@@ -107,8 +107,11 @@ separator = "•"
 # Compatibility: https://caniuse.com/link-icon-svg
 # favicon_emoji = "🌱"
 
-# This header image is used for SEO. For example if you were to share an image via Messenger/Instagram/Twitter a preview picture is also presented
+# Path to the fallback image for social media cards (the preview image shown when sharing a link on WhatsApp, LinkedIn…).
-# headerImage = ""
+# Can be set at page or section levels, following the hierarchy: page > section > config. See: https://github.com/welpo/tabi/pull/128
+# Learn how to create these images in batch and automatically:
+# https://osc.garden/blog/automating-social-media-cards-zola/
+# social_media_card = "img/social_cards/index.jpg"
 
 menu = [
     { name = "blog", url = "blog", trailing_slash = true },