Asciidoc中docdatetime与localdatetime值为何始终相同？如何显示修改日期？

问题原因 #

1. VSCode预览插件的处理逻辑：默认情况下，VSCode的Asciidoc预览插件每次打开预览时都会重新解析文档，它不会缓存文件的修改时间，而是把当前解析文档的时间同时赋值给{docdatetime}和{localdatetime}，导致两者显示一致。
2. Antora的默认行为：如果Antora项目没正确配置源文件时间追踪，会把文档构建时的时间当作{docdatetime}的值，而非文件在系统中的实际修改时间。尤其是文件来自本地目录而非Git仓库时，Antora可能不会主动读取文件的修改时间，直接用构建时间填充。
3. Windows系统适配问题：部分Asciidoc工具在Windows下读取文件修改时间存在兼容性问题，无法正确获取资源管理器中显示的文件实际修改时间。

解决办法 #

针对VSCode预览 #

• 手动指定文档修改时间：在文档顶部添加静态属性定义，示例：

  :docdatetime: 2024-05-20 14:30:00
  Last modified: {docdatetime}
  Last converted: {localdatetime}
  

  这种方式需要每次修改文档后手动更新该值，适合对修改时间精度要求不高的场景。
• 调整插件配置：打开VSCode设置，找到Asciidoc插件的相关选项，查看是否有“使用文件修改时间”（类似asciidoc.preview.useFileModifiedTime）的配置项，启用后插件会读取文件系统的修改时间作为{docdatetime}的值。

针对Antora构建 #

• 利用Git提交时间（推荐）：如果文档存放在Git仓库中，Antora默认会使用文件最后一次Git提交的时间作为{docdatetime}，只要确保文档修改记录已提交到Git，构建时就能正确显示最后修改时间。
• 强制读取文件系统修改时间：在Antora的playbook文件中，为content源添加配置，强制Antora读取文件的修改时间。示例：

  content:
    sources:
      - url: ./docs
        branches: HEAD
        start_path: modules/ROOT/pages
        attributes:
          docdatetime: '{git.commit.timestamp}' # 基于Git提交时间
  

  若本地文件不在Git仓库，可使用Antora扩展（如antora-file-attributes）读取文件系统的修改时间并赋值给{docdatetime}。
• 手动设置文档属性：和VSCode的方式一致，在每个文档顶部手动定义:docdatetime:属性，确保构建时使用固定的修改时间。

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