Pass page.url to relativize_links() for consistent value when site_url not configured

[martinjoiner]

I observed that links in snippets would be generated correctly when using mkdocs serve locally, but if you ran mkdocs build to make the static HTML files, the links were missing their relative path prefixes (eg. ../).

After some debugging I noticed that when the site_url property is not set in mkdocs.yml, the value of page.abs_url differs between the 2 commands; it is None when running build, but it is a string path when running serve. (Note: If site_url is set in mkdocs.yml, page.abs_url is the same across both these commands).

This means that when I raised #7 a couple of weeks ago which added handling for current_path variable being empty I was actually not fixing the root cause of the problem.

This PR changes it to use page.url which I have observed being consistent between the 2 commands, regardless of if site_url is or is not set in mkdocs.yml

Sadly, I cannot contribute tests to cover all the logic in relativize_links() because I do not know the expected behaviour of functions like remove_mike_version_from_path().

[SaltyAimbOtter]

Hey Martin,
thank you for your suggestions! I cannot look into them during the work week - I will have a detailed look at the weekend.

[SaltyAimbOtter]

The behaviour of page.abs_url and page.file.src_uri is not identical.
When debugging, the following two results are printed:

Passing API/BukkitConfigurations.md (page.file.src_uri), usually /API/BukkitConfigurations/ (page.abs_url)

Therefore this change introduces bugs when parsing the path later on in the script. I think your last change needs to be improved further. However, tests would be much appreciated and would have helped to debug this issue!

[martinjoiner]

Yes I found the value of page.file.src_uri is different to the value of page.abs_url, but more importantly the value of page.file.src_url is consistent between running mkdocs build or mkdocs serve, whereas with page.abs_url the value is different.

Can I ask which command you were running in your testing? Could I request you run your manual debugging again but doing it for both the mkdocs build command and mkdocs serve and include the results in this thread?

[SaltyAimbOtter]

Sorry, I forgot about the issue when finding the other one 😅

However, I cannot reproduce it. This is what I did:
I always test with the documentation within the BetonQuest/BetonQuest repository as it is quite large and contains snippets.
Mkdocs Version 1.6.1

I added a debug statement to the plugin that prints page.abs_url for every invocation of resolve_snippet: logging.warn(f"DEBUGGING{page.abs_url}")

Then I build the plugin with python -m build and installed the freshly build plugin from my local BetonQuest work dir using pip install ../mkdocs-snippets/dist/mkdocs_snippets-1.3.1-py3-none-any.whl --force-reinstall.
I then saved the results (all lines with DEBUGGING) from mkdocs build and mkdocs serve and compared with git diff. No differences were found! Perhaps they only occur when the mkdocs docs_dir is empty? Which repository are you working on?

[SaltyAimbOtter]

By the way: I have restructured the project according to the PyTest docs. You can now write tests inside /tests and run them with pytest. Make sure to pip install pytest.

[martinjoiner]

Oh good work! Let me figure out what's going on with this inconsistency I am observing. I will make a new blank project and add in my config 1-by-1 until I discover what is the cause of this inconsistency.

[martinjoiner]

OK, I have made a discovery......

The site_url variable in mkdocs.yml is critical to revealing this behaviour. In the private repository which I maintain at work, we do not have this set at all because we serve our docs from both a staging environment for QAing and a production environment for public viewing which have different urls. It is in that project that I observed this behaviour where it would serve locally fine but generate broken links when building for deployment.

So @SaltyAimbOtter if you repeat your experiment in the BetonQuest/BetonQuest repo, but delete line 4 of mkdocs.yml, I think you will observe the same behaviour 🤞

[martinjoiner]

OK. I think the bug might be in this line https://github.com/mkdocs/mkdocs/blob/master/mkdocs/structure/pages.py#L72

self.abs_url is only None when running mkdocs build with site_url not set in mkdocs.yml. Line 72 attempts to coalesce that missing value and fall back to using self.file.url.... but the File class has no property named url property to refer to. I think maybe this should be referring to the src_uri property.

[martinjoiner]

Hi @SaltyAimbOtter, I have done some more debugging and discovered the page.url property which I believe gives us the consistent behaviour across all scenarios that we need. I have pushed another commit to this branch and edited the title and description of this PR.