From 3442fd9ff0c0a093f08bb27aaa0d92e5993df29b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=93scar?= Date: Sun, 20 Oct 2024 22:59:17 +0200 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20docs:=20clarify=20instructions?= =?UTF-8?q?=20for=20listing=20recent=20posts=20(#418)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 48 +++++++++++++------ .../blog/mastering-tabi-settings/index.ca.md | 37 +++++++++----- .../blog/mastering-tabi-settings/index.es.md | 37 +++++++++----- content/blog/mastering-tabi-settings/index.md | 33 ++++++++----- templates/partials/main_page_posts_list.html | 28 ++++++++++- 5 files changed, 130 insertions(+), 53 deletions(-) diff --git a/README.md b/README.md index 6e9ce9ba3..995e6dbaf 100644 --- 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 index 6bc2a356e..8963629e7 100644 --- 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 index 298b4f079..5bf1e6b83 100644 --- 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 index ffc5805b2..ee880bc7a 100644 --- 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 index 0d62f03d7..67412208c 100644 --- 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) }} + {# 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 -%} +
+
+
+ WARNING: Conflicting Configuration +

+ No posts are displayed due to conflicting settings in your _index.md: +

+
    +
  • paginate_by is set, but there are no posts to paginate in the current section.
    • +
  • section_path is set, and posts are available in that section.
    • +
+

+ Solution: Remove paginate_by from your _index.md. + To limit the number of displayed posts, use max_posts in the [extra] section instead. +

+
+
+ {%- 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) }} - {% if paginator %} + {% if paginator and paginator.pages | length > 0 %} {%- include "partials/paginate.html" -%} {% endif %} {%- endif -%}