Site configuration: default handling of language-specific keys

tifenak · October 21, 2025, 11:42pm

This method overrides the pagerSize in configuration. I spent a lot of hours wondering why it was not working until I cloned this project and saw the hard coded pager size that needed to be added.

jmooring · October 21, 2025, 11:56pm

The approach that I outlined does not have to override the configured pager size. I just chose to do that for my examples.

tifenak · October 22, 2025, 12:10am

What I meant is the default pager does not work with that code when the hard coded pager is removed. Just run the project without the hard coded pager and see.

jmooring · October 22, 2025, 12:20am

I made these changes and it works great:

diff --git a/hugo.toml b/hugo.toml
index 102b6fb6e..51aa10030 100644
--- a/hugo.toml
+++ b/hugo.toml
@@ -3,6 +3,16 @@ baseURL = 'https://example.org/'
 defaultContentLanguage = 'en'
 defaultContentLanguageInSubdir = true
 
+# -----------------------------------------------------------------------------
+# Pagination
+# -----------------------------------------------------------------------------
+
+
+[pagination]
+  disableAliases = false
+  pagerSize = 13
+  path = 'p'
+
 # -----------------------------------------------------------------------------
 # Languages: en
 # -----------------------------------------------------------------------------
diff --git a/layouts/books/section.html b/layouts/books/section.html
index 534c8f0ec..bfb34254f 100644
--- a/layouts/books/section.html
+++ b/layouts/books/section.html
@@ -1,6 +1,6 @@
 {{ define "pagination" }}
   {{ $pages := .Pages.ByTitle }}
-  {{ .Store.Set "paginator" (.Paginate $pages 5) }}
+  {{ .Store.Set "paginator" (.Paginate $pages) }}
 {{ end }}
 
 {{ define "main" }}
diff --git a/layouts/films/section.html b/layouts/films/section.html
index ef1152dae..a14786325 100644
--- a/layouts/films/section.html
+++ b/layouts/films/section.html
@@ -1,6 +1,6 @@
 {{ define "pagination" }}
   {{ $pages := .Pages.ByDate.Reverse }}
-  {{ .Store.Set "paginator" (.Paginate $pages 4) }}
+  {{ .Store.Set "paginator" (.Paginate $pages) }}
 {{ end }}
 
 {{ define "main" }}
diff --git a/layouts/home.html b/layouts/home.html
index f0386c47d..1b9a83baa 100644
--- a/layouts/home.html
+++ b/layouts/home.html
@@ -1,6 +1,6 @@
 {{ define "pagination" }}
   {{ $pages := site.Sections }}
-  {{ .Store.Set "paginator" (.Paginate $pages 5) }}
+  {{ .Store.Set "paginator" (.Paginate $pages) }}
 {{ end }}
 
 {{ define "main" }}

tifenak · October 22, 2025, 1:37am

Add this to your code and test again.

 [languages.en.pagination]
      path = 'page'

Copied from here Configure languages.

Edit: ~~It appears to be a recent bug. 0.150.0 is fine. 152.0 causes the issue.~~
The setting above does not break pagination when language pagerSize is added. Is that by design or a bug? tested on 0.150.0 and 0.152.0

jmooring · October 22, 2025, 3:28am

If “breaks pagination” means that it is using the default pager size of 10, that’s what I would expect.

You’ve redefined the pagination object for each language.

tifenak · October 22, 2025, 9:57am

Are we really communicating the same thing?

[pagination]
  pagerSize = 4

[languages]
  [languages.en]
    languageCode = 'en-US'
    languageName = 'English'
    timeZone = 'America/New_York'
    title = 'Project Documentation'
    weight = 1
    [languages.en.pagination]
      path = 'page'

Please test that code.

jmooring · October 22, 2025, 3:05pm

With these changes:

diff

diff --git a/hugo.toml b/hugo.toml
index 102b6fb6e..71a9a4488 100644
--- a/hugo.toml
+++ b/hugo.toml
@@ -3,6 +3,9 @@ baseURL = 'https://example.org/'
 defaultContentLanguage = 'en'
 defaultContentLanguageInSubdir = true
 
+[pagination]
+  pagerSize = 4
+
 # -----------------------------------------------------------------------------
 # Languages: en
 # -----------------------------------------------------------------------------
@@ -15,6 +18,9 @@ languageName = 'English'
 weight = 1
 title = 'Hugo Forum Topic #50340 (en)'
 
+[languages.en.pagination]
+  path = 'page'
+
 [[languages.en.menus.main]]
 name = 'Home (en)'
 pageRef = '/'
@@ -47,6 +53,9 @@ languageName = 'Deutsch'
 weight = 2
 title = 'Hugo Forum Topic #50340 (de)'
 
+[languages.de.pagination]
+  path = 'seite'
+
 [[languages.de.menus.main]]
 name = 'Home (de)'
 pageRef = '/'
diff --git a/layouts/books/section.html b/layouts/books/section.html
index 534c8f0ec..bfb34254f 100644
--- a/layouts/books/section.html
+++ b/layouts/books/section.html
@@ -1,6 +1,6 @@
 {{ define "pagination" }}
   {{ $pages := .Pages.ByTitle }}
-  {{ .Store.Set "paginator" (.Paginate $pages 5) }}
+  {{ .Store.Set "paginator" (.Paginate $pages) }}
 {{ end }}
 
 {{ define "main" }}
diff --git a/layouts/films/section.html b/layouts/films/section.html
index ef1152dae..a14786325 100644
--- a/layouts/films/section.html
+++ b/layouts/films/section.html
@@ -1,6 +1,6 @@
 {{ define "pagination" }}
   {{ $pages := .Pages.ByDate.Reverse }}
-  {{ .Store.Set "paginator" (.Paginate $pages 4) }}
+  {{ .Store.Set "paginator" (.Paginate $pages) }}
 {{ end }}
 
 {{ define "main" }}
diff --git a/layouts/home.html b/layouts/home.html
index f0386c47d..1b9a83baa 100644
--- a/layouts/home.html
+++ b/layouts/home.html
@@ -1,6 +1,6 @@
 {{ define "pagination" }}
   {{ $pages := site.Sections }}
-  {{ .Store.Set "paginator" (.Paginate $pages 5) }}
+  {{ .Store.Set "paginator" (.Paginate $pages) }}
 {{ end }}
 
 {{ define "main" }}

…Hugo is doing what I expect it do to; it’s paginating the Books and Films sections with 10 pages per pager (the default) because we’ve redefined the pagination config map for each language without specifying the pager size.

The same thing occurs with other config objects:

[markup.tableOfContents]
startLevel = 4
endLevel = 6

[languages.en.markup.tableOfContents]
ordered = true

$ hugo config | grep tableofcontents -A3

  [markup.tableofcontents]
    endlevel = 3
    ordered = true
    startlevel = 2

irkode · October 22, 2025, 3:53pm

mmh, I guess when coming from outside the hugo config world one would rather expect

hardcoded default -> global default -> local values and every unset value is taken from the direct level above.

regardless of expectations - unless I missed that in the docs it imho would be a valuable addition.

# [pagination]                    <- hardcode values
#   pagerSize = 10
#   path = 'page'

[pagination]                      <-- my global default
  pagerSize = 4

[languages.en.pagination]         <-- my changed settings for en
  path = 'pagedpage'

my expectation would that the global setting is taken to the specialized site

[languages.en.pagination] 
  pagerSize = 4
  path = 'pagedpage'

# allother pages
  pagerSize = 4
  path = 'page'

tifenak · October 22, 2025, 4:56pm

Exactly! And herein lies my problem. I spent over 6 frustrating hours diagnosing ad tearing apart all my templates.

This is not obvious as @irkode pointed above. I am not knowledgeable enough to put together a discussion, but I hope it is picked up. Otherwise, I was about to tear all my hair out on this issue.

jmooring · October 22, 2025, 8:04pm

To make sure we’re all on the same page, this discussion is about the handling of language-specific site configuration settings, and if/how they are merged with settings that are not language-specific.

Take this site configuration:

[markup.tableOfContents]
startLevel = 3
endLevel = 6

[languages.en]
weight = 1

[languages.de]
weight = 2

[languages.en.markup.tableOfContents]
# _merge = 'deep'
endLevel = 4

[languages.de.markup.tableOfContents]
# _merge = 'deep'
endLevel = 5

When we build the project:

Tables of content in the en site will start with level 2 (the default value) and end with level 4
Tables of content in the de site will start with level 2 (the default value) and end with level 5

Now, in the site configuration, uncomment the two instances of _merge = 'deep'. When we build the project:

Tables of content in the en site will start with level 3 and end with level 4
Tables of content in the de site will start with level 3 and end with level 5

With this change, Hugo merges the markup.tableOfContents key in the same way that it merges the params key.

See https://gohugo.io/configuration/introduction/#merge-configuration-settings.

[languages]
  _merge = 'none'
  [languages.en]
    _merge = 'none'
    [languages.en.menus]
      _merge = 'shallow'
    [languages.en.params]
      _merge = 'deep'

Try it:

git clone --single-branch -b hugo-forum-topic-56129 https://github.com/jmooring/hugo-testing hugo-forum-topic-56129
cd hugo-forum-topic-56129
hugo && cat public/en/index.html public/de/index.html

irkode · October 23, 2025, 7:33am

Many thanks for taking the time pointing to that - overseen by me - merge settings which at a quick view allows to get the stuff behave as OP wants.

first quick shot here:

the merge configuration settings page talks about project and theme(module) merging.

Hugo merges configuration settings from themes and modules, prioritizing the project’s own settings. Given this simplified project structure with two themes:

needing “_merge” for within the project wasn’t on my radar.
on the localized settings we read

The following configuration keys can be defined separately for each language:
… list of keys pagination, markup …
Any key not defined in a languages object will fall back to the global value in the root of the site configuration.

this works perfectly for simple key-value pairs, but for the table value pagination not taking over the project defaults but the hardcoded values was surprising.

I would say for “non native speakers”, “non techies”, “freshers” and me the expectation did not match actual behavior. Might be worth being discussed more verbose in the docs. maybe later in some “explanation” section.

Topic		Replies	Views
Couldn't control the pager-size in paginator support pagination	21	466	July 20, 2024
'pager size' must be a positive integer support pagination	5	1087	February 27, 2022
Translate paginate path support i18n	3	627	July 22, 2022
Disabling pagination aliases in languages.toml support	3	127	June 28, 2024
Paginator page limit broken support pagination	0	405	July 13, 2020

Site configuration: default handling of language-specific keys

Related topics