How do i describe a dir path for loading pngs?

[Knight-of-Code]

I am trying to use this plugin so I can use variables instead of typing relative or absolute path for PNG files under mkdocs/docs/assets/images/applications/

extra:
  app_images: /assets/images/applications/

I did above in mkdocs.yml and ![]({{ app_images }}syncthing.png) in MD file, but it doesn't work as I wanted. Although PNG loads, but It's just guessing the path.

INFO    -  Doc file 'wiki/Docker/compose/applications/syncthing.md' contains an absolute link '/assets/images/applications/syncthing.png', it was left as is. Did you mean '../../../../assets/images/applications/syncthing.png'?

How to do this correctly?

[github-actions[bot]]

Welcome to this project and thank you!

[fralau]

A '/' at the start of a path denotes a path relative to the root of your server, and it will likely not work.

Remove the initial '/' to get a path relative to your docs directory.

[Knight-of-Code]

it doesnt work with that.

WARNING -  Doc file 'wiki/Docker/compose/applications/syncthing.md' contains a link 'assets/images/applications/syncthing.png', but the target 'wiki/Docker/compose/applications/assets/images/applications/syncthing.png' is not found among documentation files.

[fralau]

@Knight-of-Code That should be easy to debug, since you should be able to check whether: wiki/Docker/compose/applications/assets/images/applications/ exists and the file you are looking for exists.

There is often a little work to do, to get it right.

[Knight-of-Code]

Let me explain in more detail.

So I have my mkdocs dir at /mnt/path/to/mkdocs. Inside mkdocs i have docs which has both dir for PNG files and MD files.

PNG at mkdocs/docs/assets/images/applications/syncthing.png and MD at mkdocs/docs/wiki/Docker/compose/applications/syncthing.md

mkdocs structure:

mkdocs$ tree -L 2
.
├── docs
│   ├── assets
│   ├── blog
│   ├── index.md
│   └── wiki
├── mkdocs.yml

PNG & MD dir

mkdocs$ tree -L 6
.
├── docs
│   ├── assets
│   │   ├── images
│   │   │   ├── applications
│   │   │   │   └── syncthing.png
│   └── wiki
│       ├── Docker
│       │   ├── compose
│       │   │   └── applications
│       │   │       └── syncthing.md

This wiki/Docker/compose/applications/assets/images/applications/syncthing.png path doesn't exist. What's happening is that when I dont use /, it just tries to look for assets/images/applications/syncthing.png inside the dir where syncthing.md is stored because i m calling the var from this md file. And when i do use / mkdocs tries to guess the path and gives warning message and actually works.

If I want to use syncthing.png in syncthing.md, I can do relative path like ../../../../assets/images/applications/syncthing.png inside md file, and it works without issues and warning message. But I want to use the PNG dir for lots of images and reference them in lots of md files which will be located somewhere else too like wiki/test.md or wiki/test2/test2.md etc.

Instead of typing relative path in each file which will be different for each file's locations and makes it more complicated, or using / and get warning message for each png i describe in each md file, I want to define the PNG dir in one place and use that with a var everywhere without getting the warning/guessing system.

Is that possible?

Hope I was able to explain my issues properly. English is not my primary language. Hope u can help with what i am trying to achieve using this plugin.

[fralau]

Sorry, you were not using the include directive, but the standard hyperlink feature of MkDocs.

And the hyperlink feature is relative to the .md file itself. That's tricky, because you have a very deep directory structure.

I don't know any solution that would be elegant and simple... except changing the directory structure of your project (but I'm not sure you wish or can do that).

[Knight-of-Code]

What will u suggest for me to do?

[ndonkoHenri]

You could make use of mkdocs-external-images.

See it here in action here step-by-step:

• https://github.com/flet-dev/flet/blob/main/sdk/python/packages/flet/pyproject.toml#L102
• https://github.com/flet-dev/flet/blob/main/sdk/python/packages/flet/mkdocs.yml#L157
• https://github.com/flet-dev/flet/blob/main/sdk/python/packages/flet/docs/controls/banner.md?plain=1#L5
• macro: https://github.com/flet-dev/flet/blob/main/sdk/python/packages/flet/docs/extras/macros/__init__.py#L54

Hope it helps!

[Knight-of-Code]

Thank you, but my files are inside docs directory.

Also, the banner.md u shared seems to need me to define the relative path and use the image() function to generate it. I'm trying to avoid typing the relative paths using vars in md files.

---
class_name: flet.Banner
examples: ../../examples/controls/banner
example_images: ../test-images/examples/material/golden/macos/banner
example_media: ../examples/controls/banner/media
---

{{ class_summary(class_name, example_images + "/image_for_docs.png", image_caption="Basic Banner") }}

## Examples

[Live example](https://flet-controls-gallery.fly.dev/dialogs/banner)

### Basic example

```python
--8<-- "{{ examples }}/basic.py"

{{ image(example_media + "/basic.gif", alt="basic", width="80%") }}

{{ class_members(class_name) }}

[Knight-of-Code]

Solved it!

After searching the internet, I decided to search mkdocs documentation and found a solution. Below seems to be working for my use case.

mkdocs.yml:

plugins:
  - search
  - macros:
      on_undefined: strict

validation:
  links:
    absolute_links: relative_to_docs

extra:
  app_images: '/assets/images/applications/' 

MD file:

![Syncthing Logo]({{ app_images }}syncthing.png)

Now it loads and there are no warning messages with relative paths showing inside logs.

[fralau]

Brilliant!

If you set the setting validation.links.absolute_links to the new value relative_to_docs, all Markdown links starting with / will be understood as being relative to the docs_dir root. The links will then be validated for correctness according to all the other rules that were already working for relative links in prior versions of MkDocs. For the HTML output, these links will still be turned relative so that the site still works reliably.

https://www.mkdocs.org/about/release-notes/#validation-of-hyperlinks-between-pages