✨ feat: enhance Table of Contents

- Introduce `toc_ignore_pattern` to ignore specific headers based on regex.
- Allow custom ToC placement with shortcode or "<!-- toc -->" marker.
- Increase max depth for ToC to 4.
- Update Documentation for the above features.
 - Move ToC generation to a macro file.

content/blog/toc.ca.md

@@ -1,34 +1,104 @@
 +++
 title = "Taula de contingut"
 date = 2022-11-01
-updated = 2023-08-12
+updated = 2023-08-14
-description = "Una publicació que mostra la taula de contingut opcional."
+description = "Una publicació que mostra la taula de contingut opcional i la seva configuració."
 
 [taxonomies]
 tags = ["funcionalitat", "markdown", "tutorial"]
 
 [extra]
 toc = true
+quick_navigation_buttons = true
 +++
 
-Per habilitar la taula de continguts, estableix aquesta variable a la metainformació de l'article:
+## Documentació
+### Habilitant (i posicionant) la Taula de Contingut
+
+Hi ha dues formes d'habilitar la Taula de Contingut (TdC). Si vols que estigui just a sota del capçalera (com en aquesta pàgina), configura aquesta variable en el front matter del teu post:
 
 ```toml
 [extra]
 toc = true
 ```
 
-També pots establir la profunditat màxima de la taula de continguts especificant la variable `toc_levels`:
+Si prefereixes col·locar la TdC a un altre lloc (per exemple, després d'una introducció), pots fer-ho afegint una línia amb aquest contingut allà on vulguis que aparegui la TdC:
+
+```markdown
+<!-- toc -->
+```
+
+També pots utilitzar el shortcode `{{/* toc() */}}`, que simplement inserirà aquest text per tu ([idea de Michael Clayton](https://github.com/getzola/zola/issues/584#issuecomment-1546086781)).
+
+Aquest mètode renderitzarà la TdC sense el capçalera "Taula de Contingut". Això et permet utilitzar un capçalera diferent (o cap) per la TdC, o fins i tot ocultar-la de forma predeterminada:
+
+<details>
+    <summary>TdC oculta</summary>
+    <!-- toc -->
+</details>
+
+El codi per aconseguir-ho:
+
+```markdown
+<details>
+    <summary>TdC oculta</summary>
+    <!-- toc -->
+</details>
+```
+
+*Nota*: Si actives la TdC amb `toc = true` i també afegeixes `<!-- toc -->` en algun lloc del teu text, obtindràs múltiples TdCs.
+
+Si col·loques la TdC en un lloc diferent del predeterminat i li afegeixes un capçalera, segurament voldràs ocultar aquest capçalera de la TdC (consulta la [secció per ocultar capçaleres](#ocultant-capcaleres-de-la-tdc)). Pots fer-ho així:
+
+```markdown,hl_lines=06 11-13
++++
+title = "El títol del teu post"
+date = 2034-01-11
 
-```toml, hl_lines=03
 [extra]
-toc = true
+toc_ignore_pattern = "^(Taula de contingut)"
++++
+
+Aquí va algun text introductori.
+
+### Taula de contingut
+
+<!-- toc -->
+
+## Primer encapçalament de contingut
+```
+
+### Establint la profunditat màxima
+
+Pots establir la profunditat màxima per la TdC especificant la variable `toc_levels`, que accepta un número enter entre 1 i 4:
+
+```toml
+[extra]
 toc_levels = 2
 ```
 
-En aquest exemple, només s'inclourien els primers dos nivells de capçaleres a la taula de continguts, independentment de les seves etiquetes HTML reals (`h1`, `h2`, `h3`, etc.). Si només vols incloure el nivell principal de capçaleres, estableix `toc_max_depth = 1`. Per defecte, si no s'especifica `toc_max_depth`, la taula de continguts inclourà tres nivells de capçaleres.
+En aquest exemple, només els dos primers nivells d'encapçalaments s'inclourien a la TdC, independentment de les seves etiquetes HTML reals (`h1`, `h2`, `h3`, etc.). Si vols incloure només el nivell principal d'encapçalaments, estableix `toc_levels = 1`. El valor per defecte de `toc_levels` és `3`.
+
+Tingues en compte als teus lectors quan establertis `toc_levels`. Encara que pot ser temptador incloure molts nivells imbricats per a una navegació detallada, una TdC més curta i senzilla sovint és més amigable i menys aclaparadora.
+
+### Ocultant capçaleres de la TdC
+
+És possible que vulguis amagar certes capçaleres. Per exemple, si el teu article té moltes Figures o Taules, aquestes podrien saturar la TdC. Pots ocultar capçaleres específiques a la TdC configurant la variable `toc_ignore_pattern` en la secció `[extra]` del front matter del teu post.
+
+Aquesta variable espera una expressió regular (regex), ja que utilitza el test [matching](https://tera.netlify.app/docs/#matching) de Tera. El `toc_ignore_pattern` es prova contra el text del capçalera. Per exemple, per a la capçalera `### Lectura addicional`, només el text `Lectura addicional` s'utilitzaria per comprovar si coincideix amb el patró.
+
+Aquí tens alguns valors d'exemple per a `toc_ignore_pattern` juntament amb les capçaleres que amagarien:
+
+| `toc_ignore_pattern`             | Exclou capçaleres que…                                                 |
+|----------------------------------|------------------------------------------------------------------------|
+| `Taula`                          | continguin "Taula"                                                     |
+| `^Figura`                        | comencin amb "Figura"                                                  |
+| <code>(?i)(taula\|figura)</code> | comencin amb "Taula" o "Figura" (insensible a majúscules/minúscules)   |
+| `\[Esborrany\]$`                 | acabin amb "[Esborrany]".                                              |
+
+Pots provar la teva expressió regular en plataformes com [regex101](https://regex101.com/r/2dI7U2/1) per assegurar-te que funciona com esperes.
 
-Tingues en compte als teus lectors quan configures `toc_levels`. Encara que pot ser temptador incloure molts nivells per a una navegació detallada, una taula de continguts més curta i senzilla sovint és més amigable per al lector. Ajusta la profunditat segons la complexitat i longitud del teu contingut per a la millor experiència del lector.
+*Nota*: Les capacitats de "look-around", incloent look-ahead i look-behind, no estan suportades.
 
 # Capçalera 1
 Lorem ipsum dolor sit amet, consectetur adipiscing elit. Mauris sed mollis augue, vel efficitur lacus. Pellentesque eu egestas mi. Etiam ultrices lectus sit amet aliquet ullamcorper. Praesent in erat quis est sagittis finibus. Etiam nec sapien in nulla interdum faucibus. Integer iaculis lorem quis arcu lobortis, non malesuada neque vehicula. Aenean nec tellus eu metus bibendum tempus. Sed rutrum urna ut commodo tempor. Vestibulum aliquet elit posuere turpis maximus condimentum. Sed urna libero, ornare eu tellus vitae, laoreet condimentum risus. Aenean elit lectus, mattis quis nibh nec, faucibus rutrum sapien. Sed iaculis consectetur mi, eget posuere turpis finibus et.

content/blog/toc.es.md

@@ -1,34 +1,104 @@
 +++
 title = "Tabla de contenido"
 date = 2022-11-01
-updated = 2023-08-12
+updated = 2023-08-14
-description = "Una publicación que muestra la tabla de contenido opcional."
+description = "Una publicación que muestra la tabla de contenido opcional así como su configuración."
 
 [taxonomies]
 tags = ["funcionalidad", "markdown", "tutorial"]
 
 [extra]
 toc = true
+quick_navigation_buttons = true
 +++
 
-Para habilitar la tabla de contenidos, establece esta variable en la metainformación del post:
+## Documentación
+### Habilitando (y posicionando) la Tabla de Contenido
+
+Hay dos formas de habilitar la Tabla de Contenido (TdC). Si quieres que esté justo debajo del encabezado (como en esta página), configura esta variable en el front matter de tu post:
 
 ```toml
 [extra]
 toc = true
 ```
 
-También puedes establecer la profundidad máxima de la tabla de contenidos especificando la variable `toc_levels`:
+Si prefieres situar la TdC en otro lugar de tu post (por ejemplo, después de una introducción), puedes hacerlo añadiendo una línea con este contenido ahí donde quieras que aparezca la TdC:
+
+```markdown
+<!-- toc -->
+```
+
+También puedes usar el shortcode `{{/* toc() */}}`, que simplemente insertará ese texto por ti ([idea de Michael Clayton](https://github.com/getzola/zola/issues/584#issuecomment-1546086781)).
+
+Este método renderizará la TdC sin el encabezado "Tabla de contenido". Esto te permite usar un encabezado diferente (o ninguno) para la TdC, o incluso ocultarla de forma predeterminada:
+
+<details>
+    <summary>TdC oculta</summary>
+    <!-- toc -->
+</details>
+
+El código para lograr esto:
+
+```markdown
+<details>
+    <summary>TdC oculta</summary>
+    <!-- toc -->
+</details>
+```
+
+*Nota*: Si activas la TdC a través de `toc = true` y además añades `<!-- toc -->` en algún lugar de tu texto, obtendrás múltiples TdCs.
+
+Si colocas la TdC en algún lugar distinto al predeterminado y le añades un encabezado, seguramente quieras ocultar dicho encabezado de la TdC (consulta la [sección para ocultar encabezados](#ocultando-encabezados-de-la-tdc)). Puedes lograrlo así:
+
+```markdown,hl_lines=06 11-13
++++
+title = "El título de tu post"
+date = 2034-01-11
 
-```toml, hl_lines=03
 [extra]
-toc = true
+toc_ignore_pattern = "^(Tabla de contenido)"
++++
+
+Aquí va algún texto introductorio.
+
+### Tabla de contenido
+
+<!-- toc -->
+
+## Primer encabezado de contenido
+```
+
+### Estableciendo la profundidad máxima
+
+Puedes establecer la profundidad máxima para la TdC especificando la variable `toc_levels`, que acepta un número entero entre 1 y 4:
+
+```toml
+[extra]
 toc_levels = 2
 ```
 
-En este ejemplo, sólo los primeros dos niveles de encabezados se incluirían en la tabla de contenidos, independientemente de sus etiquetas HTML reales (`h1`, `h2`, `h3`, etc.). Si sólo quieres incluir el nivel principal de encabezados, establece `toc_levels = 1`. Por defecto, si no se especifica `toc_levels`, la tabla de contenidos incluirá tres niveles de encabezados.
+En este ejemplo, sólo los dos primeros niveles de encabezados se incluirían en la TdC, independientemente de sus etiquetas HTML reales (`h1`, `h2`, `h3`, etc.). Si quieres incluir sólo el nivel principal de encabezados, establece `toc_levels = 1`. El valor predeterminado de `toc_levels` es `3`.
+
+Ten en cuenta a tus lectores al establecer `toc_levels`. Aunque puede ser tentador incluir muchos niveles anidados para una navegación detallada, una TdC más corta y sencilla suele ser más amigable y menos abrumadora.
+
+### Ocultando encabezados de la TdC
+
+Es posible que quieras ocultar ciertos encabezados. Por ejemplo, si tu artículo tiene muchas Figuras o Tablas, éstas podrían saturar la TdC. Puedes ocultar encabezados específicos en la TdC configurando la variable `toc_ignore_pattern` en la sección `[extra]` del front matter de tu post.
+
+Esta variable espera una expresión regular (regex), ya que utiliza el test [matching](https://tera.netlify.app/docs/#matching) de Tera. El `toc_ignore_pattern` se prueba contra el texto del encabezado. Por ejemplo, para el encabezado `### Lectura adicional`, sólo el texto `Lectura adicional` se usaría para comprobar si concuerda con el patrón.
+
+Aquí tienes algunos valores de ejemplo para `toc_ignore_pattern` junto con los encabezados que ocultarían:
+
+| `toc_ignore_pattern`             | Excluye encabezados que…                                             |
+|----------------------------------|----------------------------------------------------------------------|
+| `Tabla`                          | contengan "Tabla"                                                    |
+| `^Figura`                        | empiecen por "Figura"                                                |
+| <code>(?i)(tabla\|figura)</code> | empiecen por "Tabla" o "Figura" (insensible a mayúsculas/minúsculas) |
+| `\[Borrador\]$`                  | terminen con "[Borrador]".                                           |
+
+Puedes probar tu expresión regular en plataformas como [regex101](https://regex101.com/r/2dI7U2/1) para asegurarte de que funciona como esperas.
 
-Ten en cuenta a tus lectores al configurar `toc_levels`. Aunque puede ser tentador incluir muchos niveles anidados para una navegación detallada, una tabla de contenidos más corta y sencilla suele ser más amigable y menos abrumadora para el lector. Ajusta la profundidad según la complejidad y longitud de tu contenido para la mejor experiencia del lector.
+*Nota*: Las capacidades de "look-around", incluyendo look-ahead y look-behind, no están soportadas.
 
 # Encabezado 1
 Lorem ipsum dolor sit amet, consectetur adipiscing elit. Mauris sed mollis augue, vel efficitur lacus. Pellentesque eu egestas mi. Etiam ultrices lectus sit amet aliquet ullamcorper. Praesent in erat quis est sagittis finibus. Etiam nec sapien in nulla interdum faucibus. Integer iaculis lorem quis arcu lobortis, non malesuada neque vehicula. Aenean nec tellus eu metus bibendum tempus. Sed rutrum urna ut commodo tempor. Vestibulum aliquet elit posuere turpis maximus condimentum. Sed urna libero, ornare eu tellus vitae, laoreet condimentum risus. Aenean elit lectus, mattis quis nibh nec, faucibus rutrum sapien. Sed iaculis consectetur mi, eget posuere turpis finibus et.

content/blog/toc.md

@@ -1,34 +1,103 @@
 +++
 title = "Table of Contents"
 date = 2022-11-01
-updated = 2023-08-12
+updated = 2023-08-14
-description = "A post showcasing the optional Table of Contents."
+description = "A post showcasing the optional Table of Contents and its options."
 
 [taxonomies]
 tags = ["showcase", "markdown", "tutorial"]
 
 [extra]
 toc = true
+quick_navigation_buttons = true
 +++
 
-To enable the table of contents, set this variable on the post's front matter:
+## Documentation
+### Enabling (and positioning) the Table of Contents
+
+There are two ways to enable the Table of Contents (ToC). If you want it to be right below the header (like in this page) set this variable on the post's front matter:
 
 ```toml
 [extra]
 toc = true
 ```
+If you'd rather show the ToC elsewhere on your post (e.g. after an introduction), you can do so by adding a line with this content wherever you'd like the ToC to appear:
+
+```markdown
+<!-- toc -->
+```
+
+You can also use the simple `{{/* toc() */}}` shortcode, which will simply write that string for you, effectively inserting the ToC ([Michael Clayton's idea](https://github.com/getzola/zola/issues/584#issuecomment-1546086781)).
+
+This method will render the ToC without the "Table of Contents" header. This allows you to use a different (or no) header for the ToC, or hide it like this:
+
+<details>
+    <summary>Hidden ToC</summary>
+    <!-- toc -->
+</details>
+
+The code to achieve this:
+
+```markdown
+<details>
+    <summary>Hidden ToC</summary>
+    <!-- toc -->
+</details>
+```
+
+*Note*: If you both set `toc = true` and have `<!-- toc -->` somewhere in your text, you'll get multiple ToCs.
 
-You can also set the maximum depth for the table of contents by specifying the `toc_levels` variable:
+If you set a custom position and a custom header for the ToC, you'll probably want to hide it (see the [section below](#hiding-headers-from-the-toc)) like this:
+
+```markdown,hl_lines=06 11-13
++++
+title = "Your Post's Title"
+date = 2034-01-11
 
-```toml, hl_lines=03
 [extra]
-toc = true
+toc_ignore_pattern = "^(Table of Contents)"
++++
+
+Here goes some introductory text.
+
+### Table of Contents
+
+<!-- toc -->
+
+## First content header
+```
+
+### Setting a maximum depth
+
+You can set the maximum depth for the ToC by specifying the `toc_levels` variable, which takes an integer between 1 and 4:
+
+```toml
+[extra]
 toc_levels = 2
 ```
 
-In this example, only the first two levels of headers would be included in the table of contents, regardless of their actual HTML tags (`h1`, `h2`, `h3`, etc.). If you want to include only the main level of headers, set `toc_levels = 1`. By default, if `toc_levels` is not specified, the table of contents will include three levels of headers.
+In this example, only the first two levels of headers would be included in the ToC, regardless of their actual HTML tags (`h1`, `h2`, `h3`, etc.). If you want to include only the main level of headers, set `toc_levels = 1`. The default `toc_levels` value is `3`.
+
+Keep your readers in mind when setting the `toc_levels`. While it can be tempting to include many nested levels for detailed navigation, a shorter and simpler ToC can often be more reader-friendly and less overwhelming. Adjust the depth according to the complexity and length of your content for the best reader experience.
+
+### Hiding headers from the ToC
+
+You might want to hide certain headers. For example, if your article has many Figures or Tables, they might clutter the ToC. You can hide specific headers in the ToC with the `toc_ignore_pattern` variable.
+
+This variable expects a regular expression (regex), as it's using Tera's [matching](https://tera.netlify.app/docs/#matching) test. The `toc_ignore_pattern` is tested against the text of the header, excluding the `#` character(s). For example, for the header `### Further reading`, the text `Further reading` would be checked against.
+
+Here are some example values for `toc_ignore_pattern` along with the headers they can hide:
+
+| `toc_ignore_pattern`             | Excludes headers which…                           |
+|----------------------------------|---------------------------------------------------|
+| `Table`                          | contain "Table"                                   |
+| `^Figure`                        | start with "Figure"                               |
+| <code>(?i)(table\|figure)</code> | start with "Table" or "Figure" (case insensitive) |
+| `\[Draft\]$`                     | end with "[Draft]".                               |
+
+You can test your regular expression on a site like [regex101](https://regex101.com/r/2dI7U2/1) to ensure it works as expected.
 
-Keep your readers in mind when setting the `toc_levels`. While it can be tempting to include many nested levels for detailed navigation, a shorter and simpler table of contents can often be more reader-friendly and less overwhelming. Adjust the depth according to the complexity and length of your content for the best reader experience.
+*Note*: "Look-around" capabilities, including look-ahead and look-behind, are not supported.
 
 # Heading 1
 Lorem ipsum dolor sit amet, consectetur adipiscing elit. Mauris sed mollis augue, vel efficitur lacus. Pellentesque eu egestas mi. Etiam ultrices lectus sit amet aliquet ullamcorper. Praesent in erat quis est sagittis finibus. Etiam nec sapien in nulla interdum faucibus. Integer iaculis lorem quis arcu lobortis, non malesuada neque vehicula. Aenean nec tellus eu metus bibendum tempus. Sed rutrum urna ut commodo tempor. Vestibulum aliquet elit posuere turpis maximus condimentum. Sed urna libero, ornare eu tellus vitae, laoreet condimentum risus. Aenean elit lectus, mattis quis nibh nec, faucibus rutrum sapien. Sed iaculis consectetur mi, eget posuere turpis finibus et.

templates/base.html

@@ -7,6 +7,7 @@
 {% import "macros/paginate.html" as macros_paginate %}
 {% import "macros/format_date.html" as macros_format_date %}
 {% import "macros/add_comments.html" as macros_add_comments %}
+{% import "macros/table_of_contents.html" as macros_toc %}
 
 <!DOCTYPE html>
 <html lang="{{ lang }}" {% if config.extra.default_theme -%}

templates/macros/content.html

@@ -42,43 +42,15 @@
             </div>
         {% endif %}
 
-        {# Optional table of contents #}
+        {# Optional table of contents below the header #}
-        {% set toc_levels = page.extra.toc_levels | default(value=3) %}
+        {% if page.extra.toc | default(value=false) and page.toc %}
-        {% if page.extra.toc | default(value=false) %}
+            {{ macros_toc::toc(page=page, header=true) }} 
-        {% if page.toc %}
-            <div class="toc-container">
-            <h3>{%- if lang != config.default_language %} {{ trans(key="table_of_contents" | safe, lang=lang) }} {% else %} Table of Contents {% endif %}</h3>
-            <ul>
-                {% for h1 in page.toc %}
-                <li>
-                    <a href="{{ h1.permalink | safe }}">{{ h1.title }}</a>
-                    {% if h1.children and toc_levels > 1 %}
-                    <ul>
-                        {% for h2 in h1.children %}
-                        <li>
-                            <a href="{{ h2.permalink | safe }}">{{ h2.title }}</a>
-                            {% if h2.children and toc_levels > 2 %}
-                            <ul>
-                                {% for h3 in h2.children %}
-                                <li>
-                                    <a href="{{ h3.permalink | safe }}">{{ h3.title }}</a>
-                                </li>
-                                {% endfor %}
-                            </ul>
-                            {% endif %}
-                        </li>
-                        {% endfor %}
-                    </ul>
-                    {% endif %}
-                </li>
-                {% endfor %}
-            </ul>
-            </div>
-        {% endif %}
         {% endif %}
 
         <section class="body">
-            {{ page.content | safe }}
+            {# The replace pattern is used to enable arbitrary locations for the Table of Contents #}
+            {# This is Philipp Oppermann's workaround: https://github.com/getzola/zola/issues/584#issuecomment-474329637 #}
+            {{ page.content | replace(from="<!-- toc -->", to=macros_toc::toc(page=page, header=false)) | safe }}
         </section>
 
         {# Check if comments are enabled #}

templates/macros/table_of_contents.html

@@ -0,0 +1,54 @@
+{% macro toc(page, header) %}
+
+{%- set toc_levels = page.extra.toc_levels | default(value=3) -%}
+
+{% if toc_ignore_pattern %}
+    {%- set toc_ignore_pattern = page.extra.toc_ignore_pattern -%}
+{% endif %}
+
+<div class="toc-container">
+    {% if header %}
+        <h3>{%- if lang != config.default_language %} {{ trans(key="table_of_contents" | safe, lang=lang) }} {% else %} Table of Contents {% endif %}</h3>
+    {% endif %}
+
+    <ul>
+        {% for h1 in page.toc %}
+            {# Only render headers if there's no ignore pattern, or if the header text doesn't match the pattern. #}
+            {% if not toc_ignore_pattern or not (h1.title is matching(toc_ignore_pattern)) %}
+                <li><a href="{{ h1.permalink | safe }}">{{ h1.title }}</a>
+                    {% if h1.children and toc_levels > 1 %}
+                        <ul>
+                            {% for h2 in h1.children %}
+                                {% if not toc_ignore_pattern or not (h2.title is matching(toc_ignore_pattern)) %}
+                                    <li><a href="{{ h2.permalink | safe }}">{{ h2.title }}</a>
+                                        {% if h2.children and toc_levels > 2 %}
+                                            <ul>
+                                                {% for h3 in h2.children %}
+                                                    {% if not toc_ignore_pattern or not (h3.title is matching(toc_ignore_pattern)) %}
+                                                        <li><a href="{{ h3.permalink | safe }}">{{ h3.title }}</a>
+                                                            {% if h3.children and toc_levels > 3 %}
+                                                                <ul>
+                                                                    {% for h4 in h3.children %}
+                                                                        {% if not toc_ignore_pattern or not (h4.title is matching(toc_ignore_pattern)) %}
+                                                                            <li><a href="{{ h4.permalink | safe }}">{{ h4.title }}</a></li>
+                                                                        {% endif %}
+                                                                    {% endfor %}
+                                                                </ul>
+                                                            {% endif %}
+                                                        </li>
+                                                    {% endif %}
+                                                {% endfor %}
+                                            </ul>
+                                        {% endif %}
+                                    </li>
+                                {% endif %}
+                            {% endfor %}
+                        </ul>
+                    {% endif %}
+                </li>
+            {% endif %}
+        {% endfor %}
+    </ul>
+</div>
+
+{% endmacro toc %}

templates/shortcodes/toc.html

@@ -0,0 +1,2 @@
+{# Inserts special string to add the Table of Contents anywhere on a post #}
+<!-- toc -->