How do I use a page URL in a header?

[akutz]

I want to add a header that references a page for more information. The problem is the URL to the page is different depending on the page the reader is currently viewing. Moreso, depending on whether the site is launched locally or hosted somewhere, the root changes, so parsing the current URL is difficult, for example:

{% extends "base.html" %}

{% block announce %}
<div style="text-align: center;">
  ✨ Please check out
  <em>
    <a href="./concepts/images/vm-image/#image-names">Image Names</a>
  </em> and
  <em>
    <a href="./concepts/images/vm-image/#name-resolution">Name Resolution</a>
  </em>
  to learn about changes to <code>VirtualMachineImage</code> and
  <code>ClusterVirtualMachineImage</code> resources in vSphere 8.0U2+ ✨
</div>
{% endblock %}

I feel like the instructions for https://squidfunk.github.io/mkdocs-material/setup/setting-up-the-header/ should include how to reference a page, since I can see a common use case for the header to be to indicate Look here for more information.

[kamilkrzyskow]

There is the site_url MkDocs config option that helps to set the same URL root on localhost and when deployed.
https://www.mkdocs.org/user-guide/configuration/#site_url

Thanks to that in our docs we create the links via absolute paths like this /root-dir-repository-name/path/to/asset.
Notice there is no ./ at the beginning just the / and the root part is the same as in site_url
https://github.com/Gothic-Modding-Community/gmc/blob/8e15b7922228dc961557c9f1570eba14ffb47e32/overrides/main.html#L38

---

Additionally there is the Jinja2 url filter function provided by MkDocs, it's used in the theme together with the assets:
{{ "relative_path_from_the_docs_directory" | url }}

mkdocs-material/src/templates/base.html

Lines 101 to 111 in b777690

	{% block styles %}
	<link rel="stylesheet" href="{{ 'assets/stylesheets/main.css' | url }}" />
	<!-- Extra color palette -->
	{% if config.theme.palette %}
	{% set palette = config.theme.palette %}
	<link
	rel="stylesheet"
	href="{{ 'assets/stylesheets/palette.css' | url }}"
	/>
	{% endif %}

---

I guess you could also reference the site_url config option directly in the Jinja2 template like so:

<a href="{{ config.site_url }}/concepts/images/vm-image/#image-names">Image Names</a>

but then localhost would still point to the address set in site_url 🤔

[alexvoss]

@akutz, IMHO the documentation is already complicated enough and adding more detail will potentially cause more harm than help. Instead, I would suggest developing a cookbook on using URLs. I might cover the question of relative URLs versus the solution @kamilkrzyskow suggested but also how to configure external links to always open in a new tab/window and checking for broken links. I know that @squidfunk is interested in getting more use cases described well, at least those that lead to recurring questions. This seems like a good candidate.

[squidfunk]

From what I understand, what @kamilkrzyskow suggested should achieve what was asked for when you're in template land:

Additionally there is the Jinja2 url filter function provided by MkDocs, it's used in the theme together with the assets:
{{ "relative_path_from_the_docs_directory" | url }}

If you're referencing an URL inside your project, the url filter will ensure that the URL is resolved from the current page.

[akutz]

Ack, thank you all. Let me try the above ideas and see which works. I could not find a good reference for the templating used inside of the overrides and partials. Perhaps I missed it?

[akutz]

Thanks @squidfunk, the following worked great:

{% extends "base.html" %}

{% block announce %}
<div style="text-align: center;">
  ✨ Please check out
  <em>
    <a href="{{ 'concepts/images/vm-image/#image-names' | url }}">Image Names</a>
  </em> and
  <em>
    <a href="{{ 'concepts/images/vm-image/#name-resolution' | url }}">Name Resolution</a>
  </em>
  to learn about changes to <code>VirtualMachineImage</code> and
  <code>ClusterVirtualMachineImage</code> resources in vSphere 8.0U2+ ✨
</div>
{% endblock %}

[squidfunk]

Thanks for sharing!