Using the plug-in for maintaining different sites from a source directory (including images)

[Erfan-nia]

Hi,

First, many thanks for developing this useful plug-in.

I'm trying to use the plug-in for a documentation system. The way it is going to be organized would be that there are some source files as markdown files and there would be different sites that would use a combination of source files to generate a document.
There are different directories for different sites which then it should be directed back to the source markdown file. This works perfectly for text, but Images do not work and are not displayed in the sites.

I have made a simple example in the following GitHub page if mine: https://github.com/Erfan-nia/Include-markdown-test
You can see that in the site1 directory, inside the docs folder and index.md file, there is the following reference:
{% include-markdown "../../Sources/docs/index.md" %}
Which goes back to the sources directory and imports the index.md from that directory that includes text and Image:

It can be seen that the text is successfully imported but the picture is not being shown.
I have also attached the directory structure of this example is it helps clarify the question:

Is there any solution to this issue?
I would appreciate it if you could help me on this :)

[mondeja]

Thanks for opening this and the complete report.

As you can see, this plugin is doing what is supposed to do. The relative link to the image is converted from download.jpg to ../../Sources/docs/download.jpg which is the real relative location of the image. Mkdocs is triggering the next warning:

WARNING -  Doc file 'index.md' contains a relative link '../../Sources/docs/download.jpg', but the target is not found among documentation files.

Indicates that your image is not part of your documentation files and that makes sense. If you don't agree, then where should Mkdocs put that file inside the generated site/ directory in case that we conclude that it should be added?

Note that you don't need to use this plugin to report the same behaviour.

[Erfan-nia]

Thank you for your quick answer! Maybe I can explain what we intend to do another way with a more comprehensive example and what we exactly intend to do.
I can see that there can be issues copying the linked images to the site directory. However, perhaps it would be possible to add the images to a separate directory in the ‘doc/img’ directory, and then modify the reference in the markdown files accordingly? I am not sure how to best implement this, but I am thinking in the same line as pandoc’s “—resource_path”. For example:

{%
include-markdown "../../common/common.md"
resource-path="../../common/"
%}

Any images in the resource path would be copied into a directory with the same name in ‘doc/img’. In this case ‘doc/img/common’ - or perhaps, ‘doc/img/resource/common’.
The specific use case we are looking at, is having several separate sites with specific documents, but the sites are also sharing common documents that is only maintained in one place. We have made a mock-up of the case to better illustrate what we are trying to do.
The directory structure:

There is also a ‘_pandoc’ directory with a bash-script example of how we are making pdfs of the markdown files in different directories. We will use the same markdown files to make different documents, so we very much prefer the documents to have as clean markdown as possible. The mkdocs specific documents will contain as little information as possible – preferably only metadata (e.g. including-files). This will be the same for the metadata-files for pandoc. We want to keep those as minimal as possible, with all the relevant information in the clean markdown files.

You can see what I mean by pandoc compared to mkdocs when it comes to this application which displays the pictures:

You can also see the code for this new example in this repository: https://github.com/Erfan-nia/Include-markdown-test.git

Hope this clarifies more of our intention :-)

[mondeja]

I'm totally aware of your intention. That solution is not consistent because what happens if another folder is included pointing to the same resource path? And this can be replicated without the plugin, so it is a Mkdocs limitation.

I'm not going to implement something like that, it breaks Mkdocs' security and encapsulation. As a workaround, use URLs in includes.

[Erfan-nia]

OK, thanks for your help 👍.