如何在Asciidoctor PDF中每页显示脚注而非尾注？

问题描述 #

使用Asciidoctor PDF 2.3.19生成文档时，通过footnote:[Content]语法添加的注释会被统一收集到文档末尾（即尾注），但需求是让脚注显示在其引用所在页面的底部。尝试过主题配置但未生效，且无Ruby/OOP编程背景，希望找到无需编写自定义转换器的简单解决方案。

已尝试的无效配置 #

在theme.yml中添加以下配置后，脚注行为未改变：

extends: default
footnote:
  disposition: page

官方说明 #

所有AsciiDoc处理器（包括Asciidoctor）目前均将脚注实现为尾注。可通过自定义转换器自定义脚注的位置和编号。

文档头部配置 #

当前文档的头部设置如下：

:doctype: book
:toc: macro
:toclevels: 3
:icons: font
:sectnums:
:sectnumlevels: 3
:source-highlighter: rouge
:experimental:
:lang: en
:imagesdir: ./images
:chapters-path: contents/{lang}

:pdf-theme: ./theme.yml

环境信息 #

1. ruby 3.4.7 (2025-10-08 revision 7a5688e2a2) +PRISM [x86_64-linux]

2. Asciidoctor PDF 2.3.19 using Asciidoctor 2.0.20
   Runtime Environment (ruby 3.4.7 (2025-10-08 revision 7a5688e2a2) +PRISM [x86_64-linux]) (lc:UTF-8 fs:UTF-8 in:UTF-8 ex:UTF-8)

可行解决方案（无需自定义转换器） #

方案1：使用第三方扩展插件 #

有专门的第三方RubyGem扩展可以实现页脚式脚注功能，无需编写自定义转换器。

1. 安装扩展：

gem install asciidoctor-pdf-footnote

2. 生成PDF时加载该扩展：

asciidoctor-pdf -r asciidoctor-pdf-footnote 你的文档.adoc

该扩展会自动将脚注渲染到引用所在页面的底部，适配现有脚注语法。

方案2：手动模拟页脚脚注（无依赖） #

如果不想安装外部依赖，可以手动模拟页脚脚注，适合文档页数较少的场景：

1. 在需要脚注的位置添加引用标记，比如[1]
2. 在当前页面末尾（可通过<<<强制分页前）添加脚注内容，并通过自定义样式调整格式：

[.footnote]
^[1] 脚注内容文本

3. 在theme.yml中定义.footnote样式：

extends: default
styles:
  footnote:
    font-size: 8
    margin-top: 12
    border-top: solid 1px #ccc

需手动管理脚注编号和分页位置，确保脚注内容落在对应页面底部。

方案3：升级Asciidoctor PDF版本 #

部分新版本的Asciidoctor PDF可能已原生支持页脚脚注配置。先升级工具：

gem update asciidoctor-pdf

升级后再次尝试在theme.yml中配置footnote.disposition: page，验证是否生效。

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