✨ feat: allow pinned posts with pagination (#428)

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-11-13
+updated = 2024-11-14
 description = "Descobreix les múltiples maneres en què pots personalitzar tabi."
 
 [taxonomies]
@@ -167,7 +167,9 @@ Per fixar una entrada, afegeix el següent al seu front matter:
 pinned = true
 ```
 
-{{ admonition(type="note", text="Aquesta configuració només afecta les pàgines que utilitzen la plantilla predeterminada `section.html`. En aquesta demo, això inclou la pàgina principal i `blog/`. Altres seccions —pàgines d'etiquetes, `archive/` o sèries— ignoren aquesta configuració.") }}
+{{ admonition(type="info", text="Aquesta configuració només afecta les pàgines principals del lloc (com `/`, `/es/`, `/fr/`). Altres seccions com `blog/`, `tags/` o `archive/` mostren les publicacions en el seu ordre habitual.") }}
+
+{{ admonition(type="warning", text='Quan s'utilitza la paginació (`paginate_by`), les entrades fixades poden aparèixer dues vegades: una vegada a la part superior de la primera pàgina, i una altra en la seva posició cronològica normal en pàgines posteriors.') }}
 
 ##### Mostrar la data dels articles al llistat
 

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-11-13
+updated = 2024-11-14
 description = "Descubre las múltiples maneras en que puedes personalizar tabi."
 
 [taxonomies]
@@ -167,7 +167,9 @@ Para fijar una publicación, añade lo siguiente a su front matter:
 pinned = true
 ```
 
-{{ admonition(type="note", text='Este ajuste solo afecta a las páginas que usan la plantilla predeterminada `section.html`. En esta demo, esto incluye la página principal y `blog/`. Otras secciones —páginas de etiquetas, `archive/` o series— ignoran este ajuste.') }}
+{{ admonition(type="info", text="Este ajuste solo afecta a las páginas principales del sitio (como `/`, `/es/`, `/fr/`). Otras secciones como `blog/`, `tags/` o `archive/` muestran las publicaciones en su orden habitual.") }}
+
+{{ admonition(type="warning", text='Cuando se utiliza la paginación (`paginate_by`), las publicaciones destacadas pueden aparecer dos veces: una vez en la parte superior de la primera página, y otra en su posición cronológica normal en páginas posteriores.') }}
 
 ##### Mostrar la fecha de los artículos en el listado
 

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

@@ -1,7 +1,7 @@
 +++
 title = "Mastering tabi Settings: A Comprehensive Guide"
 date = 2023-09-18
-updated = 2024-11-13
+updated = 2024-11-14
 description = "Discover the many ways you can customise your tabi site."
 
 [taxonomies]
@@ -167,7 +167,9 @@ To pin a post, add the following to its front matter:
 pinned = true
 ```
 
-{{ admonition(type="note", text='This setting only affects pages using the default `section.html` template. In this demo, this includes the main page and `blog/`. Other sections —tags, archives, or series pages— ignore this setting.') }}
+{{ admonition(type="info", text="This setting only affects your site's main pages (like `/`, `/es/`, `/fr/`). Other sections like `blog/`, `tags/`, or `archive/` show posts in their normal order.") }}
+
+{{ admonition(type="warning", text='When using pagination (`paginate_by`), pinned posts may appear twice: once on top of page 1, and again in their normal chronological position on subsequent pages.') }}
 
 ##### Display the Date of Posts in Listing
 

templates/macros/list_posts.html

@@ -3,30 +3,42 @@
 {# It would also work with arrays (e.g. ["dates"] or ["indexes"] or even ["indexes","dates"]). #}
 {# Nevertheless, arrays cannot be used as a default value for a macro parameter in Tera (see https://github.com/Keats/tera/issues/710). #}
 {# `paginator` is only used to compute indexes metadata and can be let empty otherwise. #}
-{% macro list_posts(posts, max, metadata="dates", language_strings="", section_path="blog", paginator="", pinned_first=false) %}
+{% macro list_posts(posts, all_posts="", max=999999, metadata="dates", language_strings="", section_path="blog", paginator="", pinned_first=false, current_page=1) %}
 
 {%- set separator = config.extra.separator | default(value="•") -%}
 
-{# Separate pinned and regular posts #}
+{# Separate pinned and regular posts from all_posts if available, otherwise from posts #}
-{% set all_posts = [] %}
 {% if pinned_first %}
+    {% set source_posts = all_posts | default(value=posts) %}
     {% set pinned_posts = [] %}
     {% set regular_posts = [] %}
-    {% for post in posts %}
+    {% for post in source_posts %}
         {% if post.extra.pinned %}
             {% set_global pinned_posts = pinned_posts | concat(with=post) %}
         {% else %}
             {% set_global regular_posts = regular_posts | concat(with=post) %}
         {% endif %}
     {% endfor %}
-    {% set all_posts = pinned_posts | concat(with=regular_posts) %}
+
+    {# On page 1 or when no pagination, show pinned then regular #}
+    {% if current_page == 1 %}
+        {% if paginator %}
+            {# With pagination: pinned + current page's posts #}
+            {% set display_posts = pinned_posts | concat(with=posts) %}
+        {% else %}
+            {# Without pagination: pinned + regular (no duplicates) #}
+            {% set display_posts = pinned_posts | concat(with=regular_posts) %}
+        {% endif %}
+    {% else %}
+        {% set display_posts = posts %}
+    {% endif %}
 {% else %}
-    {% set all_posts = posts %}
+    {% set display_posts = posts %}
 {% endif %}
 
 <div class="bloglist-container">
-    {# Display all posts (pinned first, then regular) #}
+    {# Display posts #}
-    {% for post in all_posts %}
+    {% for post in display_posts %}
         {% if loop.index <= max %}
             {% if loop.index == max or loop.last %}
                 {% set bottom_divider = false %}

templates/partials/main_page_posts_list.html

@@ -9,7 +9,7 @@
         {%- set paginator_has_no_pages = paginator and paginator.pages | length == 0 -%}
         {%- set extra_section_has_pages = extra_section and extra_section.pages | length > 0 -%}
 
-        {# Display a warning if both settings are set, paginator has no pages, but extra section does #}
+        {# Display warning if both settings are set #}
         {%- if both_settings_set and paginator_has_no_pages and extra_section_has_pages -%}
             <div class="admonition warning">
                 <div class="admonition-icon admonition-icon-warning"></div>
@@ -30,14 +30,29 @@
             </div>
         {%- endif -%}
 
-        {%- if paginator %}
+        {# Get all posts for pinning if we're in root section with pagination #}
+        {%- if paginator and is_root_section -%}
+            {%- set root_section = get_section(path="_index.md") -%}
+            {%- set all_posts = root_section.pages -%}
             {%- set pages = paginator.pages -%}
-        {% else %}
+        {%- elif paginator -%}
+            {%- set all_posts = paginator.pages -%}
+            {%- set pages = paginator.pages -%}
+        {%- else -%}
+            {%- set all_posts = extra_section.pages -%}
             {%- set pages = extra_section.pages -%}
-        {% endif -%}
+        {%- endif -%}
 
         {% set max_posts = section.extra.max_posts | default(value=999999) %}
-        {{ macros_list_posts::list_posts(posts=pages, max=max_posts, language_strings=language_strings, section_path=path, pinned_first=true) }}
+        {{ macros_list_posts::list_posts(
+            posts=pages,
+            all_posts=all_posts,
+            max=max_posts,
+            language_strings=language_strings,
+            section_path=path,
+            pinned_first=is_root_section,
+            current_page=paginator.current_index | default(value=1)
+        ) }}
     </div>
 
     {% if paginator and paginator.pages | length > 0 %}

templates/section.html

@@ -2,6 +2,16 @@
 
 {% block main_content %}
 
+{# We'll only pin posts in the root section. #}
+{# Right now both the main page and blog/ use the same `section.html` template. #}
+{# To avoid using different templates, we do this. #}
+{%- if lang == config.default_language -%}
+    {%- set expected_root = "/" -%}
+{%- else -%}
+    {%- set expected_root = "/" ~ lang ~ "/" -%}
+{%- endif -%}
+{%- set is_root_section = current_path == expected_root -%}
+
 {%- set show_projects_first = section.extra.show_projects_first | default(value=false) -%}
 {%- if show_projects_first -%}
     {%- set first_section = "projects" -%}