Intermittent 404 with navigation links and images in Azure Static Web Apps

[seankearon]

I have a really strange and intermittent problem and I'd appreciate any guidance as to where to start, please.

Sometimes I see it in the browser. Sometimes I don't. I use Moz Pro and it picks up the links as 404s.

Background

I host my docs on Azure Static Web Apps (SWA) here:

https://docs.shineforms.co.uk

SWA gives you a domain OOTB, so you can also access that via:

https://yellow-ocean-019829903.azurestaticapps.net

I have set up a custom domain as per the documentation here using a CNAME in my UK domain host with the default TTL:

Problem

My custom domain nav URLs are missing a section. Instead of:

https://docs.shineforms.co.uk/pirform/getting-started

The site renders it without the pirform section:

https://docs.shineforms.co.uk/getting-started

When this happens, images also don't render.

When this happens, the default SWA domain renders correctly:

It always works perfectly when running locally!

[kamilkrzyskow]

Hello @seankearon,
MkDocs navigation works based on relative paths, and generates static HTML files, so the relative paths in the loaded file remain always the same no matter how it's loaded.

MkDocs by default enables the directory url setting and based on that it generates those relative paths:

• https://www.mkdocs.org/user-guide/configuration/#use_directory_urls

The issue you're facing is that your URL on the screenshot doesn't have the final /.
Your server is configured to load the correct HTML file despite the path being wrong, but the relative paths inside the source now resolve to different things.

All of the generated paths should be correct with the / at the end, so the paths without / were either created by you (bad copy-paste) or something else happened.

I'm not an Azure expert, but you need to reconfigure it to redirect paths not ending with / to paths ending with /, except for the assets of course.
Or add client-side JavaScript to fix the path, but I'm not sure if that would work, as in, change how the paths behave.🤔

TLDR
Good: https://docs.shineforms.co.uk/pirform/intelligence-ring-a3-2024-pre/
Bad: https://docs.shineforms.co.uk/pirform/intelligence-ring-a3-2024-pre

[alexvoss]

@kamilkrzyskow was referring to the first screenshot, I think, where the URL in the browser bar has no slash at the end. https://docs.shineforms.co.uk/pirform/intelligence-ring-a3-2024-pre does not work, while https://docs.shineforms.co.uk/pirform/intelligence-ring-a3-2024-pre/ does.

[alexvoss]

It looks like the slash is indeed important to how browsers resolve relative paths. So, a 301 from the web server is indeed a solution as @kamilkrzyskow suggested. My web hoster does this automatically for me, so I never noticed the difference.

I do wonder about the head/base tag mentioned in the SOF post. Would adding this to the Jinja template be a solution - or is there perhaps a reason for not using it?

[seankearon]

OMG! That is indeed what is happening. It's not intermittent at all, it just depends on whether there is a trailing slash in the browser.

I will see if there is something in Azure SWA or the head/base tag that fixes this.

Thanks very much. I thought I was going mad! 🤯

[seankearon]

And, here's the documentation for how to get Azure Static Web Apps to add the trailing slash. Works like a dream!

https://learn.microsoft.com/en-us/azure/static-web-apps/configuration#trailing-slash

[kamilkrzyskow]

I do wonder about the head/base tag mentioned in the SOF post. Would adding this to the Jinja template be a solution - or is there perhaps a reason for not using it?

Oh, I forgot about base, there was a discussion about this upstream and it seems that redirects are better, but nonetheless can be added with customization:

• HTML "base" header tag support mkdocs/mkdocs#3723
• https://squidfunk.github.io/mkdocs-material/customization/#overriding-blocks