📝 docs: clarify instructions for listing recent posts (#418)

welpo · Oct 20, 2024 · 3442fd9 · 3442fd9
1 parent 5737c27
commit 3442fd9
Show file tree

Hide file tree

Showing 5 changed files with 130 additions and 53 deletions.
diff --git a/README.md b/README.md
@@ -111,26 +111,44 @@ highlight_code = true
 highlight_theme = "css"
 ```
 
-5. Create a `content/_index.md` file with the following content:
+5. Create a `content/_index.md` file. This file controls how your home page looks and behaves. Choose one of the following options:
 
-```
-+++
-title = "Home"
-paginate_by = 5 # Set the number of posts per page
-template = "index.html"
-+++
-```
+   **Option A: Serve posts from `/`**:
 
-If you want to serve your blog posts from a different path, such as `blog/`, add a `section_path` in the `[extra]` section of `content/_index.md` (this file will need pagination):
+   ```
+   +++
+   title = "Home"
+   paginate_by = 5  # Show 5 posts per page.
+   template = "section.html"
+   +++
+   ```
 
-```
-[extra]
-section_path = "blog/_index.md"
-```
+   - This will display posts in `content/` with pagination.
+
+   **Option B: Serve posts from a different path (e.g., `blog/`)**:
+
+   ```
+   +++
+   title = "Home"
+   # Note we're not setting `paginate_by` here.
+   template = "section.html"
+   +++
+
+   [extra]
+   section_path = "blog/_index.md"  # Where to find your posts.
+   max_posts = 5  # Show 5 posts on the home page.
+   ```
+
+    - This will display the latest 5 posts from the `blog/` section.
+    - Do not set `paginate_by` if you choose this option.
+    - Use the full path to the section's `_index.md` file. Using `section_path = "blog/"` will not work.
 
-**Note**: use the full path to the section's `_index.md` file. Simply using `section_path = "blog/"` will not work.
+> [!WARNING]
+> Do not set both `paginate_by` and `section_path` in `content/_index.md`.
+>
+> These settings are mutually exclusive and using both may result in no posts being displayed.
 
-6. If you want an introduction section (see screenshot above), add these lines to `content/_index.md`:
+1. If you want an introduction section (see screenshot above), add these lines to `content/_index.md`:
 
 ```
 [extra]

diff --git a/content/blog/mastering-tabi-settings/index.ca.md b/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-09-17
+updated = 2024-10-20
 description = "Descobreix les múltiples maneres en què pots personalitzar tabi."
 
 [taxonomies]
@@ -110,37 +110,48 @@ header = {title = "Hola! Soc tabi~", img = "img/main.webp", img_alt = "Óscar Fe
 
 La descripció és contingut Markdown normal, escrit fora del front matter.
 
-#### Mostrant publicacions recents
+#### Llistant publicacions recents
 
-Si vols mostrar publicacions a la pàgina principal, primer necessites decidir si la seva ruta serà `/` o quelcom diferent, com ara `/blog/`.
+Per mostrar publicacions a la pàgina principal, primer has de decidir d'on es serviran: de la ruta arrel (`/`) o d'un subdirectori (per exemple, `/blog`).
 
-Si vols servir les publicacions des de `/`, necessites configurar `paginate_by = 5` al front matter del teu arxiu `_index.md`. **Nota**: això no es configura a l'apartat `[extra]`, sinó al front matter principal. Exemple:
+**Opció A: Servir publicacions des de la ruta arrel (`/`)**
+
+Configura `paginate_by` al front matter del teu arxiu `content/_index.md`:
 
 ```toml
+title = "Últimes publicacions"
 sort_by = "date"
 template = "section.html"
-paginate_by = 5
+paginate_by = 5  # Mostra 5 publicacions per pàgina.
 
 [extra]
-header = {title = "Hola! Sóc tabi~", img = "img/main.webp", img_alt = "Óscar Fernández, l'autor del tema" }
+header = {title = "Hola! Soc tabi~", img = "img/main.webp", img_alt = "El teu nom" }
 ```
 
-Si prefereixes servir les publicacions des de `/blog`, pots configurar `section_path = "/blog"` a la secció `[extra]`. Aquesta és la configuració d'aquesta demo:
+{{ admonition(type="note", text="La configuració `paginate_by` va al front matter principal, no a la secció `[extra]`.") }}
+
+**Opció B: Servir publicacions des d'un subdirectori (per exemple, `/blog`)**
+
+Utilitza `section_path` a la secció `[extra]` del teu arxiu `content/_index.md`:
 
 ```toml
-title = "Publicacions recents"
+title = "Últimes publicacions"
 sort_by = "date"
 template = "section.html"
+# No configuris `paginate_by` aquí.
 
 [extra]
-header = {title = "Hola! Sóc tabi~", img = "img/main.webp", img_alt = "Óscar Fernández, l'autor del tema" }
-section_path = "blog/_index.es.md"
-max_posts = 4
+header = {title = "Hola! Soc tabi~", img = "img/main.webp", img_alt = "El teu nom" }
+section_path = "blog/_index.md"  # On trobar les teves publicacions.
+max_posts = 5  # Mostra fins a 5 publicacions a la pàgina principal.
 ```
 
-Fixa't que si configures `section_path`, no cal que configuris `paginate_by`. Pots establir `max_posts` per determinar el nombre de publicacions que vols mostrar a la pàgina principal.
+{{ admonition(type="warning", title="ALERTA", text="No configuris `paginate_by` i `section_path` alhora. Aquestes configuracions són mútuament excloents i usar ambdues pot fer que no es mostrin publicacions.") }}
+
+Notes addicionals:
 
-El `title` és el títol que apareix a sobre de les publicacions.
+- El `title` al front matter estableix el títol que apareix sobre les publicacions.
+- Utilitza la ruta completa a l'arxiu `_index.md` de la secció per a `section_path`. Usar `section_path = "blog/"` no funcionarà.
 
 ##### Mostrar la data dels articles al llistat
 

diff --git a/content/blog/mastering-tabi-settings/index.es.md b/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-09-17
+updated = 2024-10-20
 description = "Descubre las múltiples maneras en que puedes personalizar tabi."
 
 [taxonomies]
@@ -110,37 +110,48 @@ header = {title = "¡Hola! Soy tabi~", img = "blog/mastering-tabi-settings/img/m
 
 La descripción es contenido Markdown normal, escrito fuera del front matter.
 
-#### Mostrando publicaciones recientes
+#### Listando publicaciones recientes
 
-Si deseas mostrar publicaciones en la página principal, primero necesitas decidir si su ruta será `/` o algo como `/blog`.
+Para mostrar publicaciones en la página principal, primero debes decidir de dónde se servirán: de la ruta raíz (`/`) o de un subdirectorio (por ejemplo, `/blog`).
 
-Si quieres servir las publicaciones desde `/`, necesitas configurar `paginate_by = 5` en el front matter de tu archivo `_index.md`. **Nota**: esto no se configura en el apartado `[extra]`, sino en el front matter principal. Ejemplo:
+**Opción A: Servir publicaciones desde la ruta raíz (`/`)**
+
+Configura `paginate_by` en el front matter de tu archivo `content/_index.md`:
 
 ```toml
+title = "Últimas publicaciones"
 sort_by = "date"
 template = "section.html"
-paginate_by = 5
+paginate_by = 5  # Muestra 5 publicaciones por página.
 
 [extra]
-header = {title = "¡Hola! Soy tabi~", img = "img/main.webp", img_alt = "Óscar Fernández, el autor del tema" }
+header = {title = "¡Hola! Soy tabi~", img = "img/main.webp", img_alt = "Tu nombre" }
 ```
 
-Si prefieres servir las publicaciones desde `/blog`, puedes configurar `section_path = "/blog"` en la sección `[extra]`. Esta es la configuración de esta demo:
+{{ admonition(type="note", text="La configuración `paginate_by` va en el front matter principal, no en la sección `[extra]`.") }}
+
+**Opción B: Servir publicaciones desde un subdirectorio (por ejemplo, `/blog`)**
+
+Utiliza `section_path` en la sección `[extra]` de tu archivo `content/_index.md`:
 
 ```toml
-title = "Publicaciones recientes"
+title = "Últimas publicaciones"
 sort_by = "date"
 template = "section.html"
+# No configures `paginate_by` aquí.
 
 [extra]
-header = {title = "¡Hola! Soy tabi~", img = "img/main.webp", img_alt = "Óscar Fernández, el autor del tema" }
-section_path = "blog/_index.es.md"
-max_posts = 4
+header = {title = "¡Hola! Soy tabi~", img = "img/main.webp", img_alt = "Tu nombre" }
+section_path = "blog/_index.md"  # Dónde encontrar tus publicaciones.
+max_posts = 5  # Muestra hasta 5 publicaciones en la página principal.
 ```
 
-Fíjate que si configuras `section_path`, no necesitas configurar `paginate_by`. Puedes establecer `max_posts` para determinar el número de publicaciones que deseas mostrar en la página principal.
+{{ admonition(type="warning", title="ALERTA", text="No configures `paginate_by` y `section_path` a la vez. Estas configuraciones son mutuamente excluyentes y usarlas juntas puede resultar en que no se muestren publicaciones.") }}
+
+Notas adicionales:
 
-El `title` es el encabezado que aparece sobre las publicaciones.
+- El `title` en el front matter establece el título que aparece sobre las publicaciones.
+- Usa la ruta completa al archivo `_index.md` de la sección para `section_path`. Usar `section_path = "blog/"` no funcionará.
 
 ##### Mostrar la fecha de los artículos en el listado
 

diff --git a/content/blog/mastering-tabi-settings/index.md b/content/blog/mastering-tabi-settings/index.md
@@ -1,7 +1,7 @@
 +++
 title = "Mastering tabi Settings: A Comprehensive Guide"
 date = 2023-09-18
-updated = 2024-09-17
+updated = 2024-10-20
 description = "Discover the many ways you can customise your tabi site."
 
 [taxonomies]
@@ -112,35 +112,46 @@ The description is regular Markdown content, set outside the front matter.
 
 #### Listing Recent Posts
 
-If you'd like to show posts on the main page, you first need to decide whether their path will be `/` or something like `/blog`.
+To show posts on your main page, you first need to decide where these posts will be served from: the root path (`/`) or a subdirectory (e.g., `/blog`). 
 
-If you want to serve the posts from `/`, you need to set `paginate_by = 5` in the front matter of your `_index.md` file. **Note**: this is not in the `[extra]` section, but in the main front matter. Example:
+**Option A: Serve posts from the root path (`/`)**
+
+Set `paginate_by` in the front matter of your `content/_index.md` file:
 
 ```toml
+title = "Latest posts"
 sort_by = "date"
 template = "section.html"
-paginate_by = 5
+paginate_by = 5  # Show 5 posts per page.
 
 [extra]
-header = {title = "Hello! I'm tabi~", img = "img/main.webp", img_alt = "Óscar Fernández, the theme's author" }
+header = {title = "Hello! I'm tabi~", img = "img/main.webp", img_alt = "Your Name" }
 ```
 
-If you'd rather serve the posts from `/blog`, you can set `section_path = "/blog"` in the `[extra]` section. This is the setup of this demo:
+{{ admonition(type="note", text="The `paginate_by` setting goes in the main front matter, not in the `[extra]` section.") }}
+
+**Option B: Serve posts from a subdirectory (e.g., `/blog`)**
+
+Use `section_path` in the `[extra]` section of your `content/_index.md` file:
 
 ```toml
 title = "Latest posts"
 sort_by = "date"
 template = "section.html"
+# Do not set `paginate_by` here.
 
 [extra]
-header = {title = "Hello! I'm tabi~", img = "img/main.webp", img_alt = "Óscar Fernández, the theme's author" }
-section_path = "blog/_index.md"
-max_posts = 4
+header = {title = "Hello! I'm tabi~", img = "img/main.webp", img_alt = "Your Name" }
+section_path = "blog/_index.md"  # Where to find your posts.
+max_posts = 5  # Show up to 5 posts on the main page.
 ```
 
-Notice how if you set `section_path`, you don't need to set `paginate_by`. You can set `max_posts` to the determine the number of posts you want to show on the main page.
+{{ admonition(type="warning", text="Do not set both `paginate_by` and `section_path`. These settings are mutually exclusive and using both may result in no posts being displayed.") }}
+
+Additional notes:
 
-The `title` is the header that appears above the posts.
+- The `title` in the front matter sets the header that appears above the posts.
+- Use the full path to the section's `_index.md` file for `section_path`. Using `section_path = "blog/"` will not work.
 
 ##### Display the Date of Posts in Listing
 

diff --git a/templates/partials/main_page_posts_list.html b/templates/partials/main_page_posts_list.html
@@ -4,6 +4,32 @@
             {{ macros_page_header::page_header(title=section.title) }}
         </div>
 
+        {# Check if both paginate_by and section_path are set #}
+        {%- set both_settings_set = paginator and extra_section -%}
+        {%- 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 #}
+        {%- 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>
+                <div class="admonition-content">
+                    <strong class="admonition-title">WARNING: Conflicting Configuration</strong>
+                    <p>
+                        No posts are displayed due to conflicting settings in your <code>_index.md</code>:
+                    </p>
+                    <ul>
+                        <li><code>paginate_by</code> is set, but there are no posts to paginate in the current section.</li>
+                        <li><code>section_path</code> is set, and posts are available in that section.</li>
+                    </ul>
+                    <p>
+                        <strong>Solution:</strong> Remove <code>paginate_by</code> from your <code>_index.md</code>.
+                        To limit the number of displayed posts, use <code>max_posts</code> in the <code>[extra]</code> section instead.
+                    </p>
+                </div>
+            </div>
+        {%- endif -%}
+
         {%- if paginator %}
             {%- set pages = paginator.pages -%}
         {% else %}
@@ -14,7 +40,7 @@
         {{ macros_list_posts::list_posts(posts=pages, max=max_posts, language_strings=language_strings, section_path=path) }}
     </div>
 
-    {% if paginator %}
+    {% if paginator and paginator.pages | length > 0 %}
         {%- include "partials/paginate.html" -%}
     {% endif %}
 {%- endif -%}