Client side redirects from #

[StarfallProjects]

Hi! I am hoping to move my new employer to MkDocs + Material, but the main sticking point is client side redirects.

I found Mkdocs redirects, but it doesn't support URLs with '#' in (there's an open issue about it from Martin) That issue led me to mkdocs gen files, which looks super useful - and let's you redirect TO a URL with a '#', but I can't figure out how to redirect FROM one (have opened an issue)

I'm asking here as well as I suspect it's a larger audience and I'd like to hear any way people have solved this.

Any help greatly appreciated!

[squidfunk]

I agree that this is definitely a use case and I was hoping that support would be added to mkdocs-redirects, which hasn't happened yet. What's missing is some client-side JavaScript that analyzes the URL, checks if there's a valid anchor mapping, and then redirects to that anchor or redirects to the page if the anchor doesn't match. Furthermore, anchors should be passed through as a fallback.

It shouldn't be too hard, but I'm not sure it's worth the trouble, as mkdocs-redirects was last updated 11 months ago and doesn't look active. Furthermore, in mkdocs/mkdocs-redirects#32 (comment) it's stated that the original developer left the company and @oprypin said he wanted to take ownership, so maybe he has some ideas how to proceed here.

[StarfallProjects]

Would the best workaround just be a bunch of JS in the of the 404 page then? That doesn't seem very nice.

I was hoping there was a way to handle it with mkdocs-gen-files.

[squidfunk]

It might be possible to add the logic via theme extension to the 404 page, yes. However, I'm not sure whether search engines will correctly pick up the redirects as they've already seen the 404 status code, possibly ignoring further client-side redirects. But to a user surfing the page with a browser, observed behavior should be as desired.

[StarfallProjects]

Our head of marketing is going to kill me if I make our SEO even worse 😬

[squidfunk]

That would be the risk. I guess it could probably be handled with mkdocs-gen-files, but you would need to extend the JavaScript part to handle anchors in redirect mappings, so basically the same that would need to be implemented in mkdocs-redirects. I'm afraid I don't have enough spare time on my hands right now to fiddle with your code snippets, maybe someone else can provide a working example. If not and you absolutely need it, ping me – I can also offer professional support.

[StarfallProjects]

Thank you!

[StarfallProjects]

Swinging back to this in case anyone else is searching for the same. After making a nuisance of myself on the Netlify forums trying to find workarounds, and some strenuous copy-pasting, I've reluctantly fallen back on the hit 404 -> then redirect option:

Client-side redirects using the 404 page

Create an overrides directory, add a 404.html, and add the following:

{% extends "main.html" %}
{% block extrahead %}
<script>
    // Create an object containing all your redirects
    const redirects = {
        "/about": "/",
        "/nonpage/#oldAnchor": "/test3/1/#anchor"
    };

    (function redirect(){
            const currentPath = window.location.pathname + (window.location.hash ? window.location.hash : '');
            const redirectUrl = redirects[currentPath];
            if (redirectUrl) {
                window.location.href = `${window.location.origin}${redirectUrl}`;
                return;
            }
    })();		
</script>
{% endblock %}
{% block content %}
  <h1>404 - Customised</h1>
{% endblock %}

Limitations:

• If the page exists, this never triggers. So if you want to go from /existing-page/#deleted-anchor -> /another-existing-page/, you're out of luck. Existing page is still there, you never hit the 404.
• All redirects will be recorded as 404s. Your head of marketing may kill you. Implement at your own risk.

The 'better' option

Honestly, at the moment, the best option might be to just do page-to-page and accept anyone relying on particular anchor tags lands up in roughly the right place, rather than precisely where they want to be.

[squidfunk]

Thanks for sharing!