maven-pdf-plugin: How to define document root to use relative references

Question

I am using the maven-pdf-plugin to generate a PDF file from a markdown document. I have the markdown file in /src/site/markdown along with included image files. I have a pdf.xml file in /src/site.

When I run mvn pdf:pdf, I get a PDF file generated in /target/pdf. The PDF file is formatted fine from the markdown file but does not include the images. The output has errors indicating that it could not find the images most likely because of the warning:

[warn] No document root specified, local links will not be resolved correctly!

I have searched through everything that I can find on maven-pdf-plugin and found no references for how to set this elusive document root. I would like to keep the image files in the same directory and use relative references in the markdown file, i.e. in this case the reference is just the filename.

Any help or pointers to where to find what I need to do will be appreciated.

EDIT to add pdf.xml Here is the contents of /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>

The markdown file is in /src/site/markdown. The image files to be included are in that same directory.

This is an example of how an image is included in the markdown file:

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

EDIT to add results of further investigation
Two ways that I can generate a PDF with the images rendered is to either place the image files at the top-level project root, or change the image specification in the markdown file to be relative to the project root directory. The former is a lousy solution. The latter could be a temporary workaround, but would break other way that we use the markdown file.

Answer 1

There is no way to change the relative location for images in maven-pdf-plugin. It generates a PDF file from the site context. To make images available for PDF they should be available for the site. According to the documentation, images should be in the resources directory.

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

Image will be available in markdown with following tag:

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

PDF content will be generated with images. But images won't be found in repository view in BitBucket or Github where document root is used as a relative reference. I fixed it by duplicating images to the markdown directory.

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

It is a duplication of images, but with such approach they are available in both, pdf generation and repository view.