maven-pdf-plugin:如何定义文档根以使用相对引用

Question

我正在使用 maven-pdf-plugin 从 Markdown 文档生成 PDF 文件。我在 /src/site/markdown 中有 Markdown 文件以及包含的图像文件。我有一个 pdf.xml文件在 /src/site .

当我跑 mvn pdf:pdf , 我得到一个在 /target/pdf 中生成的 PDF 文件. PDF 文件从 Markdown 文件格式化得很好，但不包括图像。输出有错误表明它很可能由于警告而找不到图像:

[warn] 未指定文档根目录，本地链接将无法正确解析!

我已经搜索了所有可以在 maven-pdf-plugin 上找到的内容，但没有找到有关如何设置这个难以捉摸的文档根目录的引用资料。我想将图像文件保存在同一目录中，并在 Markdown 文件中使用相对引用，即在这种情况下，引用只是文件名。

任何帮助或指示在哪里可以找到我需要做的事情将不胜感激。

编辑添加 pdf.xml这是/src/site/pdf.xml的内容

<document outputName="DesignDoc">
<meta>
  <title>Design Documentation</title>
  <author>Team A</author>
</meta>
<toc name="Table of Contents">
  <item name="Design Documentation" ref="DesignDoc.md"/>
</toc>
<cover>
  <coverTitle>${project.name}</coverTitle>
  <coverSubTitle>v. ${project.version}</coverSubTitle>
  <coverType>Design Documentation</coverType>
  <projectName>${project.name}</projectName>
</cover>
</document>

Markdown 文件在 /src/site/markdown .要包含的图像文件位于同一目录中。

这是图像如何包含在 Markdown 文件中的示例:
![Domain Model](domain-model-placeholder.png)
编辑以添加进一步调查的结果
生成带有渲染图像的 PDF 的两种方法是将图像文件放在顶级项目根目录中，或者将 Markdown 文件中的图像规范更改为相对于项目根目录。前者是一个糟糕的解决方案。后者可能是一种临时解决方法，但会破坏我们使用 Markdown 文件的其他方式。

Answer 1

无法更改 maven-pdf-plugin 中图像的相对位置。它从站点上下文生成一个 PDF 文件。要使图像可用于 PDF，它们应该可用于站点。根据documentation ，图像应该在 resources目录。

+- src/
      +- markdown/
      |  +- docs.md
      |
      +- resources/
      |  +- images/
      |     +- domain-model-placeholder.png
      |
      +- site.xml

图片将在 Markdown 中可用，带有以下标签:

![Domain Model](images/domain-model-placeholder.png)

PDF 内容将与图像一起生成。但是在 BitBucket 或 Github 的存储库 View 中找不到图像，其中文档根用作相对引用。我通过将图像复制到 markdown 目录来修复它。

+- src/
      +- markdown/
      |  +- images/
      |  |  +- domain-model-placeholder.png
      |  |
      |  +- docs.md
      |
      +- resources/
      |  +- images/
      |     +- domain-model-placeholder.png
      |
      +- site.xml

这是图像的重复，但通过这种方法，它们可以在 pdf 生成和存储库 View 中使用。