Maven PDF插件忽略Asciidoc文件问题求助

不用弃用Markdown，通过以下两种常见方法就能让Asciidoc内容纳入PDF：

方法一：调整Maven PDF插件的配置，指定扫描Asciidoc生成的HTML #

Maven PDF插件默认不会自动识别Asciidoc文件，但它可以基于Asciidoc转换后的HTML生成PDF。既然你已经能用mvn site正常生成包含Asciidoc的站点，说明Asciidoc已经被转换成HTML存到target/site目录下了，只要让PDF插件扫描到这些文件就行。

修改pom.xml里的maven-pdf-plugin配置，添加对Asciidoc生成HTML的扫描规则：

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-pdf-plugin</artifactId>
  <version>3.3.0</version>
  <executions>
    <execution>
      <id>generate-pdf</id>
      <phase>site</phase>
      <goals>
        <goal>pdf</goal>
      </goals>
      <configuration>
        <!-- 同时包含markdown源文件和Asciidoc生成的HTML -->
        <sources>
          <source>src/site/markdown/**/*.md</source>
          <source>target/site/asciidoc/**/*.html</source>
        </sources>
        <!-- 开启资源包含，确保样式、图片等正常加载 -->
        <includeResources>true</includeResources>
      </configuration>
    </execution>
  </executions>
</plugin>

注意替换target/site/asciidoc为你实际的Asciidoc HTML输出目录。

方法二：完善站点导航配置（site.xml） #

如果你的Asciidoc页面没被加入站点导航，PDF插件可能会忽略这些内容——因为它默认是根据site.xml里的导航结构来收集页面生成PDF的。

打开src/site/site.xml，把Asciidoc生成的页面加入到菜单中：

<menu name="文档">
  <item name="Markdown说明" href="markdown-docs.html"/>
  <item name="Asciidoc指南" href="asciidoc-guide.html"/>
</menu>

这里的href要对应Asciidoc转换后的HTML文件名，配置后再执行mvn site pdf:pdf，PDF就会包含导航里的所有页面内容。

如果以上方法都不生效，再考虑备选方案：用pandoc这类工具批量把Markdown转成Asciidoc，再用Asciidoctor PDF插件直接生成统一的PDF，但完全没必要直接弃用Markdown。

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