From 46290e10e71d23c0ac4cfd280986dd8ebcfce00f Mon Sep 17 00:00:00 2001
From: Xin <5097752+imfing@users.noreply.github.com>
Date: Thu, 24 Jul 2025 22:26:17 +0100
Subject: [PATCH] feat(pagination): add blog pagination component (#725)

* feat(pagination): add blog pagination component

- Introduced a new blog pagination component for improved navigation on list pages.
- Updated the blog list layout to utilize pagination, allowing for better content organization.
- Added a new parameter for pagination size in the configuration file.

* chore: increase pager size for blog
---
 exampleSite/hugo.yaml                        |  2 +
 exampleSite/hugo_stats.json                  |  1 +
 i18n/en.yaml                                 |  2 +
 i18n/fa.yaml                                 |  2 +
 i18n/ja.yaml                                 |  2 +
 i18n/zh-cn.yaml                              |  2 +
 layouts/_partials/components/blog-pager.html | 39 ++++++++++++++++++++
 layouts/blog/list.html                       |  8 +++-
 8 files changed, 57 insertions(+), 1 deletion(-)
 create mode 100644 layouts/_partials/components/blog-pager.html

diff --git a/exampleSite/hugo.yaml b/exampleSite/hugo.yaml
index 25a3d5b..6d884ef 100644
--- a/exampleSite/hugo.yaml
+++ b/exampleSite/hugo.yaml
@@ -170,6 +170,8 @@ params:
       # date | lastmod | publishDate | title | weight
       sortBy: date
       sortOrder: desc # or "asc"
+      # Pagination
+      pagerSize: 20
 
     article:
       displayPagination: true
diff --git a/exampleSite/hugo_stats.json b/exampleSite/hugo_stats.json
index 438d2cf..4f3944d 100644
--- a/exampleSite/hugo_stats.json
+++ b/exampleSite/hugo_stats.json
@@ -440,6 +440,7 @@
       "hx:max-w-[min(calc(100vw-2rem),calc(100%+20rem))]",
       "hx:max-w-none",
       "hx:max-xl:hidden",
+      "hx:mb-1",
       "hx:mb-10",
       "hx:mb-12",
       "hx:mb-16",
diff --git a/i18n/en.yaml b/i18n/en.yaml
index cd9115c..2ff6b7c 100644
--- a/i18n/en.yaml
+++ b/i18n/en.yaml
@@ -13,3 +13,5 @@ tags: "Tags"
 poweredBy: "Powered by Hextra"
 readMore: "Read more →"
 searchPlaceholder: "Search..."
+previous: "Prev"
+next: "Next"
diff --git a/i18n/fa.yaml b/i18n/fa.yaml
index 9264a08..7747e6c 100644
--- a/i18n/fa.yaml
+++ b/i18n/fa.yaml
@@ -13,3 +13,5 @@ tags: "برچسب‌ها"
 poweredBy: "طراحی شده توسط هگزترا"
 readMore: "ادامه مطلب ←"
 searchPlaceholder: "جستجو..."
+previous: "قبلی"
+next: "بعدی"
diff --git a/i18n/ja.yaml b/i18n/ja.yaml
index 6f86af4..360ef59 100644
--- a/i18n/ja.yaml
+++ b/i18n/ja.yaml
@@ -12,3 +12,5 @@ tags: "タグ"
 poweredBy: "提供元 Hextra"
 readMore: "もっと読む →"
 searchPlaceholder: "検索..."
+previous: "前へ"
+next: "次へ"
diff --git a/i18n/zh-cn.yaml b/i18n/zh-cn.yaml
index cc7f64e..9d929fd 100644
--- a/i18n/zh-cn.yaml
+++ b/i18n/zh-cn.yaml
@@ -12,3 +12,5 @@ tags: "标签"
 poweredBy: "由 Hextra 驱动"
 readMore: "更多 →"
 searchPlaceholder: "搜索文档..."
+previous: "上一页"
+next: "下一页"
diff --git a/layouts/_partials/components/blog-pager.html b/layouts/_partials/components/blog-pager.html
new file mode 100644
index 0000000..1b6b130
--- /dev/null
+++ b/layouts/_partials/components/blog-pager.html
@@ -0,0 +1,39 @@
+{{/*
+  Blog pagination component for list pages (e.g., blog list, category list)
+  
+  Usage: {{ partial "components/blog-pager.html" $paginator }}
+  
+  Parameters:
+  - . (context): Hugo paginator object
+*/}}
+
+{{- $paginator := . -}}
+{{- $prevText := (T "previous") | default "Prev" -}}
+{{- $nextText := (T "next") | default "Next" -}}
+{{- $prevLabel := printf "%s %d/%d" $prevText (sub $paginator.PageNumber 1) $paginator.TotalPages -}}
+{{- $nextLabel := printf "%s %d/%d" $nextText (add $paginator.PageNumber 1) $paginator.TotalPages -}}
+
+{{- if or $paginator.HasPrev $paginator.HasNext -}}
+  <div class="hx:mb-8 hx:flex hx:items-center hx:border-t hx:pt-8 hx:border-gray-200 hx:dark:border-neutral-800 hx:contrast-more:border-neutral-400 hx:dark:contrast-more:border-neutral-400 hx:print:hidden">
+    {{- if $paginator.HasPrev -}}
+      <a
+        href="{{ $paginator.Prev.URL }}"
+        title="{{ $prevLabel }}"
+        class="hx:flex hx:max-w-[50%] hx:items-center hx:gap-1 hx:py-4 hx:text-base hx:font-medium hx:text-gray-600 hx:transition-colors [word-break:break-word] hx:hover:text-primary-600 hx:dark:text-gray-300 hx:md:text-lg hx:ltr:pr-4 hx:rtl:pl-4"
+      >
+        {{- partial "utils/icon.html" (dict "name" "chevron-right" "attributes" "class=\"hx:inline hx:h-5 hx:shrink-0 hx:ltr:rotate-180\"") -}}
+        {{ $prevLabel }}
+      </a>
+    {{- end -}}
+    {{- if $paginator.HasNext -}}
+      <a
+        href="{{ $paginator.Next.URL }}"
+        title="{{ $nextLabel }}"
+        class="hx:flex hx:max-w-[50%] hx:items-center hx:gap-1 hx:py-4 hx:text-base hx:font-medium hx:text-gray-600 hx:transition-colors [word-break:break-word] hx:hover:text-primary-600 hx:dark:text-gray-300 hx:md:text-lg hx:ltr:ml-auto hx:ltr:pl-4 hx:ltr:text-right hx:rtl:mr-auto hx:rtl:pr-4 hx:rtl:text-left"
+      >
+        {{ $nextLabel }}
+        {{- partial "utils/icon.html" (dict "name" "chevron-right" "attributes" "class=\"hx:inline hx:h-5 hx:shrink-0 hx:rtl:-rotate-180\"") -}}
+      </a>
+    {{- end -}}
+  </div>
+{{- end -}}
\ No newline at end of file
diff --git a/layouts/blog/list.html b/layouts/blog/list.html
index 5527ba8..78d6afc 100644
--- a/layouts/blog/list.html
+++ b/layouts/blog/list.html
@@ -8,7 +8,9 @@
         {{ if .Title }}<h1 class="hx:text-center hx:mt-2 hx:text-4xl hx:font-bold hx:tracking-tight hx:text-slate-900 hx:dark:text-slate-100">{{ .Title }}</h1>{{ end }}
         <div class="content">{{ .Content }}</div>
         {{- $pages := partial "utils/sort-pages" (dict "page" . "by" site.Params.blog.list.sortBy "order" site.Params.blog.list.sortOrder) -}}
-        {{- range $pages }}
+        {{- $pagerSize := site.Params.blog.list.pagerSize | default 10 -}}
+        {{- $paginator := .Paginate $pages $pagerSize -}}
+        {{- range $paginator.Pages }}
           <div class="hx:mb-10">
             <h3><a style="color: inherit; text-decoration: none;" class="hx:block hx:font-semibold hx:mt-8 hx:text-2xl " href="{{ .RelPermalink }}">{{ .Title }}</a></h3>
             {{ if site.Params.blog.list.displayTags }}
@@ -23,6 +25,10 @@
             <p class="hx:opacity-50 hx:text-sm hx:mt-4 hx:leading-7">{{ partial "utils/format-date" .Date }}</p>
           </div>
         {{ end -}}
+        
+        {{- if gt $paginator.TotalPages 1 -}}
+          {{ partial "components/blog-pager.html" $paginator }}
+        {{- end -}}
       </main>
     </article>
     <div class="hx:max-xl:hidden hx:h-0 hx:w-64 hx:shrink-0"></div>