python-pdfkit(wkhtmltopdf) TOC分页顶部边距设置问题

我之前也遇到过类似的wkhtmltopdf TOC分页边距问题，结合XSL和wkhtmltopdf的特性，有几个可行的方案可以尝试：

方案1：使用CSS命名页面（@page）精准控制TOC分页边距 #

这是最推荐的方法，能单独给TOC所在的页面设置顶部边距，不会影响PDF其他内容。

首先在XSL生成的HTML中，给整个TOC容器添加专属类：

<!-- 你的XSL模板中 -->
<div class="toc-container">
  <!-- TOC列表内容 -->
</div>

然后在对应的CSS中添加命名页面规则：

@page toc-page {
  margin-top: 2.5cm; /* 替换成你需要的顶部边距值 */
  /* 可按需设置其他边距，比如margin-bottom、margin-left等 */
}

.toc-container {
  page: toc-page; /* 将TOC容器绑定到命名页面 */
  page-break-inside: avoid; /* 尽量避免TOC项被拆分到两页，可选但推荐 */
}

注意：确保wkhtmltopdf版本不低于0.12.5，旧版本对@page命名页面支持有限。python-pdfkit无需额外配置，只要CSS正确加载即可生效。

方案2：XSL中手动插入分页边距占位元素 #

如果@page方法不生效，可在XSL生成TOC时，预估每页容纳的项数，在分页位置插入带边距的占位元素：

<!-- XSL的列表项循环逻辑 -->
<xsl:for-each select="your-toc-nodes">
  <!-- 每10个项插入分页和顶部边距（可根据实际调整数量） -->
  <xsl:if test="position() mod 10 = 1 and position() != 1">
    <div style="page-break-before: always; margin-top: 2cm; height: 0;"></div>
  </xsl:if>
  <li class="toc-item">
    <!-- TOC项内容 -->
  </li>
</xsl:for-each>

这种方法适合内容结构固定的场景，需要你提前测试每页能容纳的TOC项数量。

方案3：全局边距+内容容器兜底抵消 #

如果以上方法都不行，可通过全局边距设置+非TOC内容抵消的方式快速解决：

在python-pdfkit中传递全局边距选项：

import pdfkit

options = {
    'margin-top': '2.5cm',
    # 其他PDF生成选项
}

pdfkit.from_file('your-html-file.html', 'output.pdf', options=options)

然后在CSS中给非TOC内容容器设置负margin抵消全局边距：

.content-container {
  margin-top: -2.5cm; /* 抵消全局顶部边距 */
  padding-top: 0;
}

.toc-container {
  /* TOC保留全局边距，分页后新页面会自动继承 */
}

额外注意事项 #

• 确保CSS内联在XSL生成的HTML中，或通过--enable-local-file-access选项让wkhtmltopdf加载外部CSS文件。
• 不要用nth-child定位分页后的元素，wkhtmltopdf的分页是渲染阶段处理的，CSS选择器无法感知分页后的页面结构。
• 测试时可单独生成TOC的PDF，验证CSS和XSL效果后再整合到完整文档中。

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