✨ Complete rewrite of pagination logic

- Add a new `paginationWidth` parameter to control how many links are output
- Fix pagination links overflow page

Fixes #299

CHANGELOG.md

@@ -9,6 +9,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 ### Added
 
 - Traditional Chinese (Taiwan) translation ([#262](https://github.com/jpanther/congo/pull/262))
+- New `list.paginationWidth` parameter to specify how many pagination links are generated before they are truncated
 - Tailwind plugin for Prettier to standardise the order of CSS classes ([#268](https://github.com/jpanther/congo/pull/268))
 - External links in article content will now open in a new browser tab ([#312](https://github.com/jpanther/congo/pull/312))
 - Independent control over the display of taxonomy listings on article and list pages ([#326](https://github.com/jpanther/congo/pull/326))
@@ -28,6 +29,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 
 - Appearance switcher title doesn't update when switching appearance ([#235](https://github.com/jpanther/congo/issues/235))
 - Article updated date logic doesn't consider formatted date values ([#259](https://github.com/jpanther/congo/issues/259))
+- Pagination links overflow the page area on large datasets ([#299](https://github.com/jpanther/congo/issues/299))
 - Order of articles on list pages would not follow Hugo conventions when grouped by year ([#313](https://github.com/jpanther/congo/issues/313))
 - Button shortcode overlaps table of contents when at the top of the article content ([#337](https://github.com/jpanther/congo/issues/337))
 - Providing a `colorScheme` value containing uppercase characters breaks some deployments ([#347](https://github.com/jpanther/congo/issues/347))

config/_default/params.toml

@@ -53,6 +53,7 @@ enableCodeCopy = false
   showTableOfContents = false
   showTaxonomies = false
   groupByYear = true
+  paginationWidth = 1
 
 [sitemap]
   excludedKinds = ["taxonomy", "term"]

exampleSite/config/_default/params.toml

@@ -53,6 +53,7 @@ mainSections = ["samples"]
   showTableOfContents = true
   showTaxonomies = false
   groupByYear = false
+  paginationWidth = 1
 
 [sitemap]
   excludedKinds = ["taxonomy", "term"]

exampleSite/content/docs/configuration.md

@@ -152,6 +152,7 @@ Many of the article defaults here can be overridden on a per article basis by sp
 |`list.showTaxonomies`|`false`|Whether or not the taxonomies related to this article are displayed on list pages.|
 |`list.showSummary`|`false`|Whether or not article summaries are displayed on list pages. If a summary is not provided in the [front matter]({{< ref "front-matter" >}}), one will be auto generated using the `summaryLength` parameter in the [site configuration](#site-configuration).|
 |`list.groupByYear`|`true`|Whether or not articles are grouped by year on list pages.|
+|`list.paginationWidth`|`1`|How many pagination links to output either side of the current page when the page list needs to be truncated. A width of `1` will output one link either side of the current page when the list needs to be truncated. Links to the current, first and last pages are always displayed and are in addition to this value.|
 |`sitemap.excludedKinds`|`["taxonomy", "term"]`|Kinds of content that should be excluded from the generated `/sitemap.xml` file. Refer to the [Hugo docs](https://gohugo.io/templates/section-templates/#page-kinds) for acceptable values.|
 |`taxonomy.showTermCount`|`true`|Whether or not the number of articles within a taxonomy term is displayed on the taxonomy listing.|
 |`fathomAnalytics.site`|_Not set_|The site code generated by Fathom Analytics for the website. Refer to the [Analytics docs]({{< ref "partials#analytics" >}}) for more details.|

layouts/partials/pagination.html

@@ -1,39 +1,92 @@
-{{ $paginator := .Paginator }}
-{{ if gt $paginator.TotalPages 1 }}
-  <ul class="flex flex-row mt-8">
-    {{ if $paginator.HasPrev }}
-      <li>
-        <a
-          href="{{ $paginator.Prev.URL }}"
-          class="mx-1 block min-w-[1.8rem] rounded text-center hover:bg-primary-600 hover:text-neutral"
-          rel="prev"
-        >
-          &larr;
-        </a>
-      </li>
-    {{ end }}
-    {{ range $paginator.Pagers }}
-      <li>
-        <a
-          href="{{ .URL }}"
-          class="{{ if eq . $paginator }}
-            bg-primary-200 dark:bg-primary-400 dark:text-neutral-800
-          {{ end }} mx-1 block min-w-[1.8rem] rounded text-center hover:bg-primary-600 hover:text-neutral"
-        >
-          {{ .PageNumber }}
-        </a>
-      </li>
-    {{ end }}
-    {{ if $paginator.HasNext }}
-      <li>
-        <a
-          href="{{ $paginator.Next.URL }}"
-          class="mx-1 block min-w-[1.8rem] rounded text-center hover:bg-primary-600 hover:text-neutral"
-          rel="next"
-        >
-          &rarr;
-        </a>
-      </li>
-    {{ end }}
-  </ul>
-{{ end }}
+{{- with .Paginator }}
+  {{- $width := $.Site.Params.list.paginationWidth | default 1 }}
+  {{- $currentPageNumber := .PageNumber }}
+  {{- if gt .TotalPages 1 }}
+    {{- $start := math.Max 1 (sub .PageNumber $width) }}
+    {{- $end := math.Min .TotalPages (add $start (mul $width 2)) }}
+
+    <ul class="flex flex-row mt-8">
+      {{- with .Prev }}
+        <li>
+          <a
+            href="{{ .URL }}"
+            class="mx-1 block min-w-[1.8rem] rounded text-center hover:bg-primary-600 hover:text-neutral"
+            aria-label="Previous page"
+            rel="prev"
+          >
+            &larr;
+          </a>
+        </li>
+      {{- end }}
+
+      {{- with .First }}
+        {{- if gt $currentPageNumber (add 1 $width) }}
+          <li class="mx-1 min-w-[1.8rem] text-center">
+            <a
+              href="{{ .URL }}"
+              class="block rounded hover:bg-primary-600 hover:text-neutral"
+              aria-label="First page"
+            >
+              {{ .PageNumber }}
+            </a>
+          </li>
+          {{- if gt $currentPageNumber (add 2 $width) }}
+            <li>&ctdot;</li>
+          {{- end }}
+        {{- end }}
+      {{- end }}
+
+      {{- range $i := seq $start $end }}
+        <li class="mx-1 min-w-[1.8rem] text-center">
+          {{- if eq $.Paginator.PageNumber $i }}
+            <span
+              aria-current="page"
+              aria-label="Page {{ $i }}"
+              class="block font-semibold rounded bg-primary-200 text-primary-700 dark:bg-primary-400 dark:text-neutral-800"
+            >
+              {{ $i }}
+            </span>
+          {{- else }}
+            <a
+              href="{{ (index $.Paginator.Pagers (sub $i 1)).URL }}"
+              class="block rounded hover:bg-primary-600 hover:text-neutral"
+              aria-label="Page {{ $i }}"
+            >
+              {{ $i }}
+            </a>
+          {{- end }}
+        </li>
+      {{- end }}
+
+      {{- with .Last }}
+        {{- if lt $currentPageNumber (sub .TotalPages $width) }}
+          {{- if lt $currentPageNumber (sub .TotalPages (add $width 1)) }}
+            <li>&ctdot;</li>
+          {{- end }}
+          <li class="mx-1 min-w-[1.8rem] text-center">
+            <a
+              href="{{ .URL }}"
+              class="block rounded hover:bg-primary-600 hover:text-neutral"
+              aria-label="Last page"
+            >
+              {{ .PageNumber }}
+            </a>
+          </li>
+        {{- end }}
+      {{- end }}
+
+      {{- with .Next }}
+        <li>
+          <a
+            href="{{ .URL }}"
+            class="mx-1 block min-w-[1.8rem] rounded text-center hover:bg-primary-600 hover:text-neutral"
+            aria-label="Next page"
+            rel="next"
+          >
+            &rarr;
+          </a>
+        </li>
+      {{- end }}
+    </ul>
+  {{- end }}
+{{- end }}