Relative links in snippets?

[feasgal]

So I'm using pymdownx.snippets, but my problem is that I want to put a link in the snippet, to one of the other pages in my docs set. Of course this doesn't work if the markdown files I use the snippet in don't all have the same relative path to the link destination.

I could begin the link url with a / to start all the way back at the domain and make it absolute (within the docs set), but the problem with that is that I generate two different docs sites from this set (one lite and one pro) and they have different site_dirs. So starting from the domain doesn't work. It would have to start from the site_dir.

So what I really want is for my link to basically be this pseudocode, but I haven't been able to find a way because the markdown source files can't 'see' the config values:

[My Destination](/{{ config.site_dir }}/rest/of/path.md)

Any ideas? I thought of somehow pulling config.site_dir into the template via my existing main.html override, but I couldn't quite wrap my head around how that would work.

[squidfunk]

You're at Markdown processing stage, not at template rendering which comes later, so moving anything inside main.html will likely not help. However, what you're aiming for is definitely achievable, either with the macros plugin, or with a custom hook that replaces a placeholder of your choosing before rendering the Markdown of the page. The latter solution, i.e., a simple string replacement, is likely faster, so depending on the size of your documentation it might be the desirable path to follow. Example:

def on_page_markdown(markdown, *, page, config, files):
    return markdown.replace("__DOCS_DIR__", config.docs_dir)

Note that I'm not sure if that's already sufficient to resolve the correct link location. Some fiddling might be necessary 😅 You should the be able to use this placeholder in your Markdown then:

[My Destination](__DOCS_DIR__/rest/of/path.md)

[feasgal]

Unfortunately, mkdocs_macros_plugin and pymdownx.snippets are not compatible in this way. I've been fighting with the config on both of those half of the day, trying to somehow get their functionality to fire off in the correct order to do what I need, but I've exhausted my knowledge and I'm giving up.

I'll fiddle with your custom hook example and come back here to let the community know if I get it to work. Thank you.

[squidfunk]

I was also struggeling with the macros plugin as well – it was impossible to get working for us – and decided to go for a simple hook (heavily WIP) for our docs rewrite (that's still in progress). We'll be using shortcodes of the following form from now on:

mkdocs-material/docs/setup/setting-up-the-header.md

Lines 52 to 54 in 45c7e17

	<!-- md:version 8.4.0 --> ·
	<!-- md:flag feature --> ·
	<!-- md:flag experimental -->

Maybe that can guide you or other users through the process of how to pull something of like that.

[feasgal]

This was solved by MkDocs in version 1.6, with Validation of absolute links.

validation:
  links:
    absolute_links: relative_to_docs