Hugo分页未按预期生效，每页仅需显示5篇文章摘要

• 检查配置项位置与参数名

  • Hugo内置分页参数是根节点的paginate，而非部分主题用到的params.pagination，先在config.toml根节点添加：

    paginate = 5
    

  • 若主题依赖params.pagination，确保配置在[params]区块内：

    [params]
      pagination = 5
    

• 修正list.html的遍历逻辑

  • 直接基于.Paginator.Pages遍历，不要先对页面集合做全局过滤/排序后再分页。如需排序，应将排序逻辑传入分页函数：

    {{ define "main" }}
      {{ $sortedPages := .Pages.ByPublishDate.Reverse }}
      {{ range (.Paginate $sortedPages).Pages }}
        <!-- 文章摘要渲染代码 -->
      {{ end }}
      {{ template "_internal/pagination.html" . }}
    {{ end }}
    

  • 避免使用.Site.Pages替代.Pages，后者才是当前列表页的专属页面集合。

• 确认分页模板引入正确性

  • 内置分页模板需传入当前页面上下文，确保引入代码为：

    {{ template "_internal/pagination.html" . }}
    

  • 若主题有自定义分页模板（如themes/<theme_name>/layouts/partials/pagination.html），检查模板内是否正确判断.Paginator.HasPrev/.Paginator.HasNext等状态，且基于.Paginator生成分页链接。

• 验证页面集合范围

  • 确认所有6篇文章均符合列表页的筛选规则（如无draft: true未被-D参数包含，或未被主题的分类/标签过滤排除）。
  • 若使用了.Where等过滤逻辑，确保分页是基于过滤后的集合：

    {{ $filteredPages := .Pages.Where "Type" "post" }}
    {{ range (.Paginate $filteredPages).Pages }}
      <!-- 渲染代码 -->
    {{ end }}
    

• 清除缓存重新构建

  • 执行hugo clean清除旧缓存，再运行hugo server -D重新生成站点，避免缓存导致的配置不生效。

内容的提问来源于stack exchange，提问作者Molenpad