announcement bar - relative link?

[VladimirFokow]

Is it possible to use a link to a page in the same docs
in the announcement bar, that would work correctly when clicked from any page?

For example, if I have this in my main.html:

{% extends "base.html" %}

{% block announce %}
  <a href="path/to/page">Link</a>
{% endblock %}

then the path/to/page is just appended to the path that I currently have in my browser, leading to 404 not found on any non-starting page.

[kamilkrzyskow]

Hello @VladimirFokow,
should be possible, just like in the theme templates you can use the url filter to generate a relative link to the current page:

mkdocs-material/src/templates/base.html

Line 102 in 6b239db

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

The 'assets/stylesheets/main.css' is passed to the url filter and processed accordingly.
https://github.com/mkdocs/mkdocs/blob/e755aaed7ea47348a60495ab364d5483ab90a4a6/mkdocs/utils/templates.py#L38
https://github.com/mkdocs/mkdocs/blob/e755aaed7ea47348a60495ab364d5483ab90a4a6/mkdocs/utils/__init__.py#L205

[VladimirFokow]

Thanks! It worked:

main.html:

{% extends "base.html" %}

{% block announce %}
  <a href="{{ 'path/to/page' | url }}">Link</a>
{% endblock %}

where the path/to/page is relative to the docs directory

[kamilkrzyskow]

You're correct, I also saw another example in the file:

mkdocs-material/src/templates/base.html

Lines 53 to 56 in 6b239db

	<!-- Previous page -->
	{% if page.previous_page %}
	<link rel="prev" href="{{ page.previous_page.url | url }}" />
	{% endif %}

And the page.url is always relative to the docs with a / at the end when use_directory_urls is enabled, so blog/2023/10/12/a-second-post/ etc.

[VladimirFokow]

maybe this trick can be surfaced to the docs?

[kamilkrzyskow]

🤔 Perhaps and an explanation that absolute links using {{ config.site_url ~ 'relative/path/' }} should also work.
cc @alexvoss

[alexvoss]

thanks, @kamilkrzyskow, that might be a good thing to add to the example in the documentation. Would relative URLs not be more robust, though? My understanding is that that is what the url filter would produce?

Before we document this, we need to get clarity on what is and what is not part of the "API surface". I will check with squidfunk.