Doxygen does not copy Markdown images with relative paths

[jkriege2]

Hi!

I have a project with several markdown files that link to image within the same repo with relative paths, e.g.: ![jkqtplotter_simpletest1](../../screenshots/jkqtplotter_simpletest1.png) (see https://github.com/jkriege2/JKQtPlotter/blob/master/examples/simpletest/README.md).

For a better overview, here is the file structure:

|
+- doc   <-- I run doxygen from this directory
|   |
|   +- Doxyfile   <-- my Doxyfile (see https://github.com/jkriege2/JKQtPlotter/blob/master/doc/Doxyfile)
|   +- html   <-- here my output is written to
|   
+- screenshots   <-- here my images reside
|  |
|  +- jkqtplotter_simpletest1.png  <-- one of my images
|   
+- examples
   |
   +- simpletest
      |
      +- README.md <-- here I link to an image with ![](../../screenshots/jkqtplotter_simpletest1.png)

My Doxyfile contains ../screenshots in the IMAGE_PATH.

Now here is my problem:

• If I use \image html jkqtplotter_simpletest1.png anywhere, all works fine and the image is copied to my HTML output directory.
• If I use in my README.md above, all works fine and the image is copied to my HTML output directory.
• BUT: If I write ![](../../screenshots/jkqtplotter_simpletest1.png) in my README.md above, the image is NOT COPIED to the output directory, but the path above is transformed into this HTML-Tag: <img src="../../../../screenshots/jkqtplotter_simpletest1.png" alt="jkqtplotter_simpletest1" class="inline">

When I run this through doxygen in my local windows machine, this transformed path works, because my HTML-output is in /doc/html/..., but if I only copy the HTML output to a webserver it fails: http://jkriege2.github.io/JKQtPlotter/d9/d6c/a02903.html

So could it be that doxygen does not correctly resolve these relative pathes? From my understanding, even if I use a relative path to an image that resides within the documentation directory structure (even within a path in IMAGE_PATH that should produce correct HTML output, i.e. also copy the file, or AT LEAST throw an error message ... correct?

For reference my doxygen output can be found here (if it helps): https://api.travis-ci.org/v3/job/481784330/log.txt

Best and hope you can help, JAN

[albert-github]

Thanks for the report. In the log file I see that you are using (1.8.11-1) this version is from December 2015, can you test what happens with the current (1.8.15) version?

Regarding the source, can you please attach a, small, self contained example (source+config file in a tar or zip) that allows us to reproduce the problem? A reference to an external repository (and log file) is not a good idea as these can be moving targets and so the problem might not be reproducible in the future.

[jkriege2]

Hi!

actually I used 1.8.15 ... 1.8.11 is what's available on Travis CI by default, but I installed 1.8.15 before processing my files (also locally I used a current Windows build).

Here's a self-contained example (including output generated on windows with 1.8.15): test_doxygenimages.zip

It also demonstrates that a comparable problem exists, when the image is placed in the same directory as a DOX- or MD-file, but the directory is not part of the IMAGE_PATH.

Best, JAN

[albert-github]

I've just pushed a proposed patch, pull request #6787

[jkriege2]

Can I somewhere get a binary of your fix to test it (Unfortunately I don't have the time to get the doxygen build-environment up and running :-(?

Stiil: Thanks a lot for the quick fix ...

[albert-github]

There are no builds saved of the individual, proposed, patches. They are run Travis CI and appveyor but these builds are not saved.

[Lecrapouille]

When I tested the patch of this issue https://github.com/doxygen/doxygen/pull/6913 I did not check for pictures. Code like this in RADME.md does not work ![alt tag](https://github.com/xxx/yyy/blob/development/doc/foobar.png) the html page simply shows alt tag. I tried your current patch but it does not work (I did not update the whole code since I tried issue 6913).

[albert-github]

@Lecrapouille Can you create a new issue for it with (this issue is about copying images and you are talking about a construct that doesn't work for you):

• attached a, small, self contained example (source+configuration file in a tar or zip) that allows us to reproduce the problem? Please don't add external links as they might not be persistent.
• Please also specify the doxygen version used.

[emmenlau]

I'm affected by the same problem with doxygen 1.8.18.

[albert-github]

Which problem? The original or the one from Lecrapouille? Anyway a small example would always be beneficial.

[emmenlau]

Which problem? The original or the one from Lecrapouille? Anyway a small example would always be beneficial.

Sorry for not being more explicit. I have the same problem as the original poster @jkriege2, but reproduced with doxygen 1.8.18. For any relative path to images in markdown, the images are not copied to the (html) output directory. I've reproduced this:

• with and without setting IMAGE_PATH, and
• with relative paths below the current directory or leaving the current directory.

As far as I could see, the copy of images starts working if (and only if) I use absolute paths to images. I've tested this by setting IMAGE_PATH to a full absolute path. It may also work by using the full absolute path in the markdown, but I did not test this.

Since paths are relative to the user home directory for us, our current workaround is to set in bash export IMAGE_PATH=$PWD/img/ and then use the environment variable in doxygen:

IMAGE_PATH = $(IMAGE_PATH)

I wanted to test your proposed patch from #6787, but I currently can not build doxygen too easily (problem with our setup).

[codeblooded]

Any update on this issue? My org is experiencing the same problem with relative paths in markdown images.

[esutton]

doxygen --version
1.9.3

When including github markdown (*.md) documents, IMAGE_PATH copies image files to the root folder of the doxygen html output folder.

• My doxyfile and *.md documents are contained in /docs/ folder
• Images are contained in folder:

/docs/images/

Image path in doxyfile is set to:

IMAGE_PATH             = images

This works fine in GitHub but breaks in doxygen because "images/mfl2

# I am using HTML <img> as GitHub markdown does not support image size width
<img src="images/mfl2rx-jtag-ribbon-cable.png" alt="Relative path" width="100">

This works fine in Doxygen output but breaks GitHub viewing in repo:

# I am using HTML <img> as GitHub markdown does not support image size width
<img src="mfl2rx-jtag-ribbon-cable.png" alt="No path" width="100">

Are there any solutions that work in ** both ** GitHub and Doxygen output?

The only solution seems to put all image files, in same folder contain markdown documents (*.md) which results in a lot of cluttering of image files and *.md files in same folder.

[albert-github]

@esutton

Did you try to use the markdown syntax for including images [...](...) (see e.g. https://spec.commonmark.org/0.30/#images) Furthermore:

• Can you please attach a, small, self contained example (source+configuration file in a tar or zip) that allows us to reproduce the problem? Please don't add external links as they might not be persistent.
• Please also specify the full doxygen version used (doxygen -v).

[esutton]

@albert-github

See attached using Doxygen 1.9.3 doxygen-use-images-in-markdown.zip

I cannot use markdown syntax to include images as there is no support for rendering image size.

Problem: When using HTML syntax in a *.md document, I can find no solution that works in both Doxygen and Github markdown rendering, that supports organizing image files into image folder.

I am using VS Code to render the markdown, or viewing source repo using GitHub, BitBucket, etc.

Work-around:

1. Put all image files and *.md documents in same folder.
2. Use only image file name as the HTML image src

<img src="image-a.png" width="200">

3. This succeeds in rendering desired size and works for both Doxygen and Github

Problem is all image files and *.md documents must be cluttered into same folder.

Thanks!

[Levi-Lesches]

Hi, I am having the same issue. For a directory structure like this:

project  <-- running Doxygen here
├─ src/
├─ libraries/
│  ├─ Doxyfile
│  ├─ library1/
│  │  ├─ README.md
│  │  ├─ extras/
│  │  │  ├─ diagram.png

and an image in README.md like this:

<img alt="This is a diagram" src="extras/diagram.png" height=50% width=50%/>

This loads fine in GitHub and other Markdown apps but not Doxygen's generated HTML. Here is my version info:

1.9.4 (5d15657a55555e6181a7830a5c723af75e7577e2)

The issue is that the README is trying to refer to the extras directory, but when Doxygen generates its does, it doesn't copy the extras folder, even if it's included in the IMAGES_PATH option. So the only references that will work are those without folders at all. There doesn't seem to be any workaround besides keeping the README and the images in the same folder.

This does work when using markdown syntax (![caption](extras/diagram.png)), as well as the \image command (\image html extras/diagram.png), but it stops at HTML. I guess this is because the former two commands have to be translated to HTML, in which their paths are translated too (stripping out extras/). But Doxygen leaves raw HTML tags untouched, which means it ends up with an invalid path. This is a problem since the \image command does not render in general Markdown, and the Markdown syntax does not support custom image sizes.

A general solution would be for Doxygen to mirror output directories so that all syntaxes work without modification. Specifically, it would be best if all images listed in IMAGES_PATH were copied (along with their respective directories) to a new folder relative to OUTPUT_DIRECTORY the same way the original image was relative to the file that referenced it. In my example above, assuming IMAGE_PATH=libraries/library1/extras, then the generated folder should be:

project/
├─ docs/
│  ├─ index.html
│  ├─ extras/
│  │  ├─ diagram.png

That way, the HTML in index.html can safely refer to extras/diagram.png just as it would in the original README.

[Levi-Lesches]

@albert-github, what do you think of my proposal above?

[albert-github]

There is still the proposed pull request #6787 but this will solve your problem as it is geared to markdown constructs.

The situation you describe (and esutton did) is about the <img> HTML tag (note the weight in your example should probably be width). I don't think copying the tree would be a good idea, my solution would be:

• copy the image file still to the html directory
• adjust the path in the resulting output so it can be found

[emmenlau]

@albert-github I'd love to test pull request https://github.com/doxygen/doxygen/pull/6787 but I can't easily build doxygen myself. Is there an easy way for you to provide a binary for Linux x86_64 from that branch? Or can anyone else test?

[albert-github]

@emmenlau there are no executables available of the mentioned proposed pull request (the available artifacts from the GitHub Actions have expired in the mean time). Building doxygen is not that difficult, you need a (recent) Cpp compiler, a (recent) cmake and git (to extract the sources get the master version and apply the the proposed patch, though in this case you could also apply proposed patch easily on the 1.9.4 source distribution).

[GJCav]

This issue was opened back to 2019 and pops to be the first link from the google search but no admiring answers were found.

now it is 2023 and I found a possible solution from doxygen-awesome. Reading its doxygen file, IMAGE_PATH is configured to contains path to folders containing images. And it works well.

refer to: doxygen

may this comment solve this question

[MangaD]

@GJCav That solution is not good enough, because it does not work if we are using relative paths on GitHub, using the <img> tag because we want to specify the image size. Doxygen can find the image if you provide only the filename and set IMAGE_PATH, but we want it to recognize relative paths so that we can also use it on GitHub, without having the .md file in the same directory as the image file.