PAYATHON 2026

如何获取 AsciiDoc 中被 include 文件的最后修改时间?

数据小许

结论

使用 Asciidoctor 或 Asciidoctor PDF 时,{docdatetime} 的值不会因 include 而变成章节文件的修改时间。要显示各章的更新时间,可以在构建前读取章节文件的修改时间,为每章生成自定义属性,再在章节中引用。

Asciidoctor 的文档属性说明指出,docdatetime 默认反映入口源文件的最后修改时间,不考虑被包含文件的修改时间。

为什么章节中的值仍然来自 top.adoc?

include 会把目标文件的内容插入当前文档,章节文件不会因此成为单独转换、拥有独立文档属性的文档。因此,把 {docdatetime} 放在章节中,也不会让它重新读取该章节文件的时间。具体处理方式见 include 文档。

{localdatetime} 表示转换发生的时间,也不能用来显示章节文件的修改时间。

用构建脚本生成章节时间属性

下面以两个章节为例,文件名和属性名可以按实际项目调整。

1. 读取章节文件的修改时间

将以下脚本保存为文档目录中的 generate_dates.py,与 top.adoc 放在同一目录:

from datetime import datetime, timezone
from pathlib import Path

root = Path(__file__).resolve().parent

chapters = {
    "chapter1-updated": root / "chapters" / "chapter1.adoc",
    "chapter2-updated": root / "chapters" / "chapter2.adoc",
}

lines = []
for attribute, path in chapters.items():
    updated = datetime.fromtimestamp(
        path.stat().st_mtime,
        tz=timezone.utc,
    ).strftime("%Y-%m-%d %H:%M:%S UTC")
    lines.append(f":{attribute}: {updated}")

(root / "chapter-dates.adoc").write_text(
    "\n".join(lines) + "\n",
    encoding="utf-8",
)

脚本使用文件系统的修改时间,统一输出为 UTC。它只生成时间属性文件,不改写章节源文件。

2. 在 top.adoc 的文档头中引入属性

= 协作文档
:doctype: book
include::chapter-dates.adoc[]

include::chapters/chapter1.adoc[]

include::chapters/chapter2.adoc[]

生成的属性文件需要在章节内容之前引入。这里将它放在文档头中,与其他属性一起定义。

在 chapters/chapter1.adoc 中使用对应属性:

== 第一章

最后更新时间:{chapter1-updated}

章节正文。

第二章则使用 {chapter2-updated}。每个章节使用独立的属性名,可以避免共享同一个属性时发生覆盖。

3. 每次转换前重新生成

在文档目录中依次运行:

python3 generate_dates.py
asciidoctor-pdf top.adoc

以上命令假设环境已安装 Python 3 和 Asciidoctor PDF。应把生成步骤加入现有构建流程,否则显示的可能是上一次生成的时间。

使用时需要注意什么?

  • 文件系统修改时间不一定等于内容最后一次修改或提交的时间。复制文件、检出仓库或重新生成文件都可能改变它。如果需要“最后一次 Git 提交时间”,应改为从 Git 历史读取,并明确是否计入未提交修改。
  • 示例只读取每个章节文件自身的时间。如果章节内部还有 include,这些依赖文件的变化不会自动计入。若需要显示整个章节及其依赖的最后更新时间,需要收集相关文件后取最大时间。
  • 独立转换某个章节时,也需要提供对应的时间属性;这里的示例按从 top.adoc 统一构建设计。
  • 如果构建环境设置了 SOURCE_DATE_EPOCH,内置日期属性可能使用该固定时间。上述脚本直接读取文件修改时间,不会自动遵循这个环境变量;有可复现构建要求时,应统一时间来源策略。相关属性说明

备注:内容仅供参考。