disabling the implicit use_directory_urls renders plugin useless for most

[ssbarnea]

Describe the bug

As mkdocs default/implicit settings are use_directory_urls = true for good reasons, most people will use that, as it does produce nice, human-friendly URLs without useless html extension.

Still, this plugin fails to perform testing for these, which is likely >95% of mkdocs users. Exact numbers can easily be computed using a https://sourcegraph.com/ query that checks how many do disable these.

Is there any chance to make the plugin work for those using directory urls?

[manuzhang]

@ssbarnea Thanks for reporting the issue. @johnthagen Do you have time to take a look?

[johnthagen]

It's been a bit since I've looked at this code, but if I recall, use_directory_urls only affects the anchor validation, not internet URL validation (what this project was originally designed for). So I believe the internet URLs should still be able to be validated in either case.

If I recall use_directory_urls = false was important for anchor validation because this plugin has to go look up the source markdown file to do anchor validation and use_directory_urls = true might have made that more challenging?

[johnthagen]

Also, it looks like there is at least some CI targeting use_directory_urls = true?

• https://github.com/manuzhang/mkdocs-htmlproofer-plugin/blob/main/.github/workflows/ci.yml#L40
• Fix issue with use_directory_urls = True configuration #26

Is there a particular problem you have hit with this setting, @ssbarnea?

[johnthagen]

Okay, so looking at this more deeply, the cross-page anchor checking is not enabled if use_directory_urls = true, but checking of external links is still enabled.

[johnthagen]

One solution for this is to conditionally turn off use_directory_urls when you want to check the anchors:

plugins:
  ...
  - htmlproofer:
      validate_external_urls: !ENV [HTMLPROOFER_VALIDATE_EXTERNAL_URLS, false]
      raise_error: True
use_directory_urls: !ENV [MKDOCS_MATERIAL_USE_DIRECTORY_URLS, true]

And then invoke mkdocs build with something like Nox:

def docs_check_urls(s: Session) -> None:
    s.run("mkdocs", "build", env={
        "HTMLPROOFER_VALIDATE_EXTERNAL_URLS": str(True),
        "MKDOCS_MATERIAL_USE_DIRECTORY_URLS": str(False)
    })

[benoliver999]

My solution is to have a 'dev' config that enables this plugin. I use a build server for the site anyway so it's no big deal.

You have your mkdocs.yml as normal.

Then create mkdocs_dev.yml:

INHERIT: mkdocs.yml
use_directory_urls: False
plugins:
  - search
  - htmlproofer

Then when you serve your site from a local environment:

mkdocs serve -f mkdocs_dev.yml

It also means you don't have to install this plugin on your production server.