feat(listings): customise pagination options for website listings

news/changelog-1.9.md

@@ -79,6 +79,7 @@ All changes included in 1.9:
 - ([#13570](https://github.com/quarto-dev/quarto-cli/pull/13570)): Replace Twitter with Bluesky in default blog template and documentation examples. New blog projects now include Bluesky social links instead of Twitter.
 - ([#13716](https://github.com/quarto-dev/quarto-cli/issues/13716)): Fix draft pages showing blank during preview when pre-render scripts are configured.
 - ([#13847](https://github.com/quarto-dev/quarto-cli/pull/13847)): Open graph title with markdown is now processed correctly. (author: @mcanouil)
+- ([#12031](https://github.com/quarto-dev/quarto-cli/issues/12031)): Add customisable pagination options for listings via `pagination` configuration. Users can control how page numbers appear using `inner-window`, `outer-window`, `outer-window-left`, and `outer-window-right` settings. (author: @mcanouil)
 
 ### `book`
 

src/project/types/website/listing/website-listing-read.ts

@@ -68,6 +68,11 @@ import {
   kListing,
   kMaxDescLength,
   kPageSize,
+  kPaginationOptions,
+  kInnerWindow,
+  kOuterWindow,
+  kLeftOuterWindow,
+  kRightOuterWindow,
   kSortAsc,
   kSortDesc,
   kSortUi,
@@ -82,6 +87,7 @@ import {
   ListingSharedOptions,
   ListingSort,
   ListingType,
+  PaginationOptions,
   PreviewImage,
   renderedContentReader,
 } from "./website-listing-shared.ts";
@@ -147,6 +153,13 @@ const kDefaultFields = [
   kFieldDescription,
 ];
 
+const kDefaultPaginationOptions: PaginationOptions = {
+  [kInnerWindow]: 2,
+  [kOuterWindow]: 0,
+  [kLeftOuterWindow]: 0,
+  [kRightOuterWindow]: 0,
+};
+
 const defaultFieldDisplayNames = (format: Format) => {
   return {
     [kFieldImage]: " ",
@@ -619,6 +632,7 @@ function hydrateListing(
     [kFieldFilter]: hydratedFields,
     [kFieldRequired]: kDefaultFieldRequired,
     [kPageSize]: defaultPageSize(),
+    [kPaginationOptions]: kDefaultPaginationOptions,
     [kFilterUi]: listing[kFilterUi] !== undefined
       ? listing[kFilterUi]
       : listing.type === ListingType.Table,

src/project/types/website/listing/website-listing-shared.ts

@@ -57,6 +57,29 @@ export const kFieldFilter = "field-filter";
 // The number of rows to display per page
 export const kPageSize = "page-size";
 
+// Pagination options
+export const kPaginationOptions = "pagination";
+
+// How many pages should be visible on each side of the current page. list.js default: 2
+export const kInnerWindow = "inner-window";
+
+// How many pages should be visible on from the beginning and from the end of the pagination. list.js default: 0
+export const kOuterWindow = "outer-window";
+
+// Same as outerWindow but only from left. list.js default: 0
+export const kLeftOuterWindow = "outer-window-left";
+
+// Same as outerWindow but only from right. list.js default: 0
+export const kRightOuterWindow = "outer-window-right";
+
+// Pagination options interface
+export interface PaginationOptions {
+  [kInnerWindow]?: number;
+  [kOuterWindow]?: number;
+  [kLeftOuterWindow]?: number;
+  [kRightOuterWindow]?: number;
+}
+
 // The maximum number of items to include
 export const kMaxItems = "max-items";
 
@@ -169,6 +192,7 @@ export interface Listing extends ListingDehydrated {
   [kFieldFilter]: string[];
   [kFieldRequired]: string[];
   [kPageSize]: number;
+  [kPaginationOptions]: PaginationOptions;
   [kMaxItems]?: number;
   [kFilterUi]: boolean;
   [kSortUi]: boolean;

src/project/types/website/listing/website-listing-template.ts

@@ -31,12 +31,18 @@ import {
   kMaxDescLength,
   kMaxItems,
   kPageSize,
+  kPaginationOptions,
+  kInnerWindow,
+  kOuterWindow,
+  kLeftOuterWindow,
+  kRightOuterWindow,
   kSortAsc,
   kSortDesc,
   Listing,
   ListingItem,
   ListingSort,
   ListingType,
+  PaginationOptions,
 } from "./website-listing-shared.ts";
 import { resourcePath } from "../../../../core/resources.ts";
 import { localizedString } from "../../../../config/localization.ts";
@@ -522,13 +528,24 @@ export function templateJsScript(
   itemCount: number,
 ) {
   const pageSize = listing[kPageSize] as number || 50;
+  const listingPaginationOptions = listing[kPaginationOptions] as PaginationOptions || {};
 
   // If columns are present, factor that in
   const columns = listing[kFields] as string[] || [];
 
+  const paginationOptions = [
+    listingPaginationOptions[kInnerWindow] !== undefined ? `innerWindow: ${listingPaginationOptions[kInnerWindow]}` : "",
+    listingPaginationOptions[kOuterWindow] !== undefined ? `outerWindow: ${listingPaginationOptions[kOuterWindow]}` : "",
+    listingPaginationOptions[kLeftOuterWindow] !== undefined ? `leftOuterWindow: ${listingPaginationOptions[kLeftOuterWindow]}` : "",
+    listingPaginationOptions[kRightOuterWindow] !== undefined ? `rightOuterWindow: ${listingPaginationOptions[kRightOuterWindow]}` : "",
+    'item: "<li class=\'page-item\'><a class=\'page page-link\' href=\'#\'></a></li>"',
+  ]
+    .filter((v) => v !== "")
+    .join(", ");
+
   const pageOptions = itemCount > pageSize
     ? `${pageSize ? `page: ${pageSize}` : ""},
-    pagination: { item: "<li class='page-item'><a class='page page-link' href='#'></a></li>" },`
+    pagination: { ${paginationOptions} },`
     : "";
 
   const filterOptions = `searchColumns: [${

src/resources/editor/tools/vs-code.mjs

@@ -10570,6 +10570,37 @@ var require_yaml_intelligence_resources = __commonJS({
                   long: "Display item categories from this listing in the margin of the page.\n\n  - `numbered`: Category list with number of items\n  - `unnumbered`: Category list\n  - `cloud`: Word cloud style categories\n"
                 }
               },
+              pagination: {
+                object: {
+                  closed: true,
+                  properties: {
+                    "inner-window": {
+                      number: {
+                        description: "The number of pages to display on each side of the current page.",
+                        default: 2
+                      }
+                    },
+                    "outer-window": {
+                      number: {
+                        description: "The number of pages to display at the start and end of the pagination control.",
+                        default: 0
+                      }
+                    },
+                    "outer-window-left": {
+                      number: {
+                        description: "The number of pages to display at the start of the pagination control.",
+                        default: 0
+                      }
+                    },
+                    "outer-window-right": {
+                      number: {
+                        description: "The number of pages to display at the end of the pagination control.",
+                        default: 0
+                      }
+                    }
+                  }
+                }
+              },
               feed: {
                 anyOf: [
                   "boolean",
@@ -22067,6 +22098,10 @@ var require_yaml_intelligence_resources = __commonJS({
           short: "Display item categories from this listing in the margin of the\npage.",
           long: "Display item categories from this listing in the margin of the\npage."
         },
+        "The number of pages to display on each side of the current page.",
+        "The number of pages to display at the start and end of the pagination\ncontrol.",
+        "The number of pages to display at the start of the pagination\ncontrol.",
+        "The number of pages to display at the end of the pagination\ncontrol.",
         "Enables an RSS feed for the listing.",
         "The number of items to include in your feed. Defaults to 20.",
         {
@@ -23772,6 +23807,10 @@ var require_yaml_intelligence_resources = __commonJS({
           short: "Shift heading levels by a positive or negative integer. For example,\nwith <code>shift-heading-level-by: -1</code>, level 2 headings become\nlevel 1 headings.",
           long: "Shift heading levels by a positive or negative integer. For example,\nwith <code>shift-heading-level-by: -1</code>, level 2 headings become\nlevel 1 headings, and level 3 headings become level 2 headings. Headings\ncannot have a level less than 1, so a heading that would be shifted\nbelow level 1 becomes a regular paragraph. Exception: with a shift of\n-N, a level-N heading at the beginning of the document replaces the\nmetadata title."
         },
+        {
+          short: "Schema to use for numbering pages, e.g.&nbsp;<code>1</code> or\n<code>i</code>, or <code>false</code> to omit page numbering.",
+          long: 'Schema to use for numbering pages, e.g.&nbsp;<code>1</code> or\n<code>i</code>, or <code>false</code> to omit page numbering.\nSee <a href="https://typst.app/docs/reference/model/numbering/">Typst\nNumbering</a> for additional information.'
+        },
         {
           short: "Sets the page numbering style and location for the document.",
           long: 'Sets the page numbering style and location for the document using the\n<code>\\setuppagenumbering</code> command.\nSee <a href="https://wiki.contextgarden.net/Command/setuppagenumbering">ConTeXt\nPage Numbering</a> for additional information.'
@@ -24903,11 +24942,7 @@ var require_yaml_intelligence_resources = __commonJS({
         "Disambiguating year suffix in author-date styles (e.g.&nbsp;\u201Ca\u201D in \u201CDoe,\n1999a\u201D).",
         "Manuscript configuration",
         "internal-schema-hack",
-        "List execution engines you want to give priority when determining\nwhich engine should render a notebook. If two engines have support for a\nnotebook, the one listed earlier will be chosen. Quarto\u2019s default order\nis \u2018knitr\u2019, \u2018jupyter\u2019, \u2018markdown\u2019, \u2018julia\u2019.",
-        {
-          short: "Schema to use for numbering pages, e.g.&nbsp;<code>1</code> or\n<code>i</code>, or <code>false</code> to omit page numbering.",
-          long: 'Schema to use for numbering pages, e.g.&nbsp;<code>1</code> or\n<code>i</code>, or <code>false</code> to omit page numbering.\nSee <a href="https://typst.app/docs/reference/model/numbering/">Typst\nNumbering</a> for additional information.'
-        }
+        "List execution engines you want to give priority when determining\nwhich engine should render a notebook. If two engines have support for a\nnotebook, the one listed earlier will be chosen. Quarto\u2019s default order\nis \u2018knitr\u2019, \u2018jupyter\u2019, \u2018markdown\u2019, \u2018julia\u2019."
       ],
       "schema/external-schemas.yml": [
         {
@@ -25136,12 +25171,12 @@ var require_yaml_intelligence_resources = __commonJS({
         mermaid: "%%"
       },
       "handlers/mermaid/schema.yml": {
-        _internalId: 218561,
+        _internalId: 219145,
         type: "object",
         description: "be an object",
         properties: {
           "mermaid-format": {
-            _internalId: 218553,
+            _internalId: 219137,
             type: "enum",
             enum: [
               "png",
@@ -25157,7 +25192,7 @@ var require_yaml_intelligence_resources = __commonJS({
             exhaustiveCompletions: true
           },
           theme: {
-            _internalId: 218560,
+            _internalId: 219144,
             type: "anyOf",
             anyOf: [
               {