Paths in ing tags under MkDocs serve

[pitosalas]

In my main.html override I have:

{% extends "base.html" %}
{% block header %}
  <div class="banner">
    <img src="images/banner/banner-00.jpg" alt="Banner">
  </div>
  {{ super() }}
{% endblock %}

I am having trouble with the path of the image source. I have the images stored under docs/images/banner. I have tried that path with a / in front "/images/banner/banner-00.jpg" and without. It seems to work in different cases, i.e. for blog posts vs. blog pages and it also behaves different for running on localhost vs. when I deploy to GitHub. Thoughts?

https://pitosalas.github.io/wp-convert/pages/Recommendations.md
https://github.com/pitosalas/wp-convert

Thanks!

[alexvoss]

It looks like you have not set the site_url to match the path on GitHub? If you do that then absolute paths in the template should work.

[kamilkrzyskow]

I don't think that setting site_url will help with absolute links 🤔.
Since the page is hosted on GitHub with the /wp-convert/ prefix then absolute links must include it, so @pitosalas use:
<img src="/wp-convert/images/banner/banner-00.jpg" alt="Banner">
or if you plan to later change the prefix use relative links with the url filter:
<img src="{{ 'images/banner/banner-00.jpg' | url }}" alt="Banner">
just like the assets in the theme templates:

mkdocs-material/src/templates/base.html

Line 102 in e8504fd

<link rel="stylesheet" href="{{ 'assets/stylesheets/main.css' | url }}" />

[alexvoss]

The site_url is used by MkDocs to decide where to mount the site when mkdocs serve is being used. So, if you want absolute links to work, this would be the way to do it.

Of course, the suggestion to use the url filter makes that unnecessary as the paths can remain relative. @pitosalas, for context: relative paths are favoured by MkDocs so that the base_url can be changed. With the filter there is a mechanism to automatically adjust relative paths, so @kamilkrzyskow is right to recommend that. I was not aware of its existence (wonders never cease in the MkDocs world...)

[kamilkrzyskow]

site_url will change the canonical address of the site, and will change the base prefix when hosted with mkdocs serve, however absolute links are resolved in the browser from the domain base like github.com. Absolute links don't take site_url into consideration, sorry for not being clear with my initial response.
Thanks for the link to the url filter, searching for mkdocs url filter on google doesn't reveal anything, so I had to find it in the code xD
Good to know it's documented.

[alexvoss]

@kamilkrzyskow ok, perhaps I should have been more precise in what I was saying by using "absolute path", not "absolute URL". Of course, if you hard-code the domain name and protocol as well then you will run into problems.

[pitosalas]

Thanks all. I am still a little confused as to how to use the url filter. I have site_url: https://pitosalas.github.io/wp-convert/ repo_url: https://github.com/pitosalas/wp-convert Do I still need those? And how would I rewrite my img tag? I currently have this but I have tried other permutations and still it’s not working. It is definitely a relative url thing though. {% extends "base.html" %} {% block header %} <div class="banner"> <img src="images/banner/banner-00.jpg" alt="Banner"> </div> {{ super() }} {% endblock %} My home page which is docs/index.md generates with a working image tag but my pages, e.g. docs/pages/curacao.md. That is because the src= assumes docs/ as a base and it doesn’t work when it is a file in pages/… So we understand the problem but I can’t figure out how to use the features to fix it. Thanks, Pito

…

On Jan 19, 2024 at 10:11:49 AM, Alexander Voss ***@***.***> wrote: @kamilkrzyskow <https://github.com/kamilkrzyskow> ok, perhaps I should have been more precise in what I was saying by using "absolute path", not "absolute URL". Of course, if you hard-code the domain name and protocol as well then you will run into problems. — Reply to this email directly, view it on GitHub <#6664 (reply in thread)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAAK5CMBDBXEYRZQBB2ZAHDYPKELLAVCNFSM6AAAAABCBG5P6SVHI2DSMVQWIX3LMV43SRDJONRXK43TNFXW4Q3PNVWWK3TUHM4DCOBSGY3TC> . You are receiving this because you were mentioned.Message ID: ***@***.*** com>

[kamilkrzyskow]

I am still a little confused as to how to use the url filter

I provided the example above, did you try it or what is the issue?
<img src="{{ 'images/banner/banner-00.jpg' | url }}" alt="Banner">

Perhaps the comment got corrupted via email, maybe the HTML got parsed 🤔
GitHub allows to insert files and images in the comment editor, and from your other messages I saw that email doesn't allow for that.
So there is definitely a disparity when it comes to features or displaying the messages.

[pitosalas]

Hi Kamil That works! I did see that bit of html, I just thought it was an example not specifically what I needed! Can you take a moment and explain the syntax that you used? Thanks! PIto

…

On Jan 19, 2024 at 10:36:42 AM, Kamil Krzyśków ***@***.***> wrote: I am still a little confused as to how to use the url filter I provided the example above, did you try it or what is the issue? <img src="{{ 'images/banner/banner-00.jpg' | url }}" alt="Banner"> Perhaps the comment got corrupted via email, maybe the HTML got parsed 🤔 GitHub allows to insert files and images in the comment editor, and from your other messages I saw that email doesn't allow for that. So there is definitely a disparity when it comes to features or displaying the messages. — Reply to this email directly, view it on GitHub <#6664 (reply in thread)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAAK5CORB7UTN6B6EUZSES3YPKHIVAVCNFSM6AAAAABCBG5P6SVHI2DSMVQWIX3LMV43SRDJONRXK43TNFXW4Q3PNVWWK3TUHM4DCOBSHE2TI> . You are receiving this because you were mentioned.Message ID: ***@***.*** com>

[kamilkrzyskow]

MkDocs uses the Jijnja2 template processor, minimum v2.11
In the execution block {{ }} I passed the string 'images/banner/banner-00.jpg' into the url filter.
The url filter is a function that returns a normalized relative URL based on the one passed into it:
https://github.com/mkdocs/mkdocs/blob/7186f4ce9c88e7c445ef90fee85c065ca297a7c8/mkdocs/utils/templates.py#L37-L40
https://github.com/mkdocs/mkdocs/blob/7186f4ce9c88e7c445ef90fee85c065ca297a7c8/mkdocs/utils/__init__.py#L205-L216

Whatever the result is in the execution block it will be put in place of it in the template code src="RESULT"
I hope I didn't simplify the answer too much.

[pitosalas]

Kamil, Thanks. The part that confused me was the pipe | symbol. I understand it now Nice. Pito

…

On Jan 19, 2024 at 11:01:03 AM, Kamil Krzyśków ***@***.***> wrote: MkDocs uses the Jijnja v2.11 template processor. In the execution block {{ }} I passed the string 'images/banner/banner-00.jpg' into the url filter. The url filter is a function that returns a normalized relative URL based on the one passed into it: https://github.com/mkdocs/mkdocs/blob/7186f4ce9c88e7c445ef90fee85c065ca297a7c8/mkdocs/utils/templates.py#L37-L40 https://github.com/mkdocs/mkdocs/blob/7186f4ce9c88e7c445ef90fee85c065ca297a7c8/mkdocs/utils/__init__.py#L205-L216 Whatever the result is in the execution block it will be put in place of it in the template code src="RESULT" I hope I didn't simplify the answer too much. — Reply to this email directly, view it on GitHub <#6664 (reply in thread)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAAK5CPALC52DVJ7WXGTS6LYPKKD7AVCNFSM6AAAAABCBG5P6SVHI2DSMVQWIX3LMV43SRDJONRXK43TNFXW4Q3PNVWWK3TUHM4DCOBTGIZTM> . You are receiving this because you were mentioned.Message ID: ***@***.*** com>