Add a base_path option for image folders

[Valerie-ts]

Hi all,
I'm not sure if others would find this useful, so please let me know if this would be interesting for you:
I'd like to be able to define a base path for my image folder instead of using relative links when adding images (much like the base_path option for snippets / includes).

Use cases:

• I use a lot of snippets that contain images, but depending on where I use the snippets I have to use logic to adjust the relative link to the image folder. So having a fixed image folder would make things a lot easier / writer friendlier.
• Image links wouldn't need to be adjusted when moving files to / from subfolders -> reduce maintenance.
• This might also be a nice addition for the projects plugin (I have images that are used in all projects and I am looking into using symlinks to make my images available in the projects, but it's seems to be a real pain to do on Windows).

Any feedback is welcome :)

Kind regards,
Valerie

[kamilkrzyskow]

Hello @Valerie-ts,
since you're using snippets I guess that using the macros plugin isn't an option, but perhaps try it out. 🤔
Another idea I have is to use an absolute path starting with /assets/images/, but I don't remember now if there are no warnings doing it this way. Also the link to the image is ultimately processed by MkDocs via some function, so perhaps monkey-patching it with some kind of hook could work out. https://www.mkdocs.org/user-guide/configuration/#hooks

EDIT: Tough already solved with a plugin, a new finding pointed to the validation configuration option, which allows to disable warnings for the absolute links: https://www.mkdocs.org/user-guide/configuration/#validation

EDIT2: Further discussion on the topic of the hook override: #6784 (comment)

[alexvoss]

I can confirm that MkDocs prints a warning when using absolute paths, which I find annoying. IMHO this would be a very small change that would be very useful. Ideally, it would be done by MkDocs, though, rather than in Material. There is at least one discussion over there on this topic. The discussion shows that there are at least some people who assume that images reside next to the Markdown pages. Might depend on your project whether that is a good idea or not. I tend to put them under docs/assets/images.

I should be possible to write a hook that modifies the Markdown and insert relative paths based on a configured base directory. Perhaps someone has produced a plugin that I was not lucky enough to find with the search terms I used? If there isn't one, does anyone want to spend a weekend writing one?

Would be a good idea to discuss that over in the MkDocs discussions, though instead of just charging ahead. Perhaps this is the sort of thing that might fit into the Python Markdown extensions? I could imagine other image-related functionality that might go along nicely with this. Just my 2p.

[Valerie-ts]

Thank you all for your feedback.
I did some more digging and I found the mkdocs-site-urls plugin that that pretty much does what I need.

[alexvoss]

Thanks for posting this! I had not come across it and have the same problem with warnings about absolute URLs, which I tend to use as I put images into an assets folder.

[Valerie-ts]

Same, I also use the assets folder ;) Only downside is that there are no warnings for broken links when serving the project.

[alexvoss]

It does look like there is some movement on the side of MkDocs and with version 1.6.0 we might no longer need the plugin!? See this PR that has already been merged into the master branch.