Is there a way to permanently link to a page even if the page changes?

[MrF3lix]

Hi, at my work we've been using mkdocs and mkdocs-material now for a while on multiple documentation pages and we're very happy with how easy and flexible it is!

We reference our documentation pages quite a lot in PDFs, chats, and other documentation sites. Since a while I noticed that some of our links get outdated because pages get moved, renamed or deleted.

I've been wondering, is there a way around this?

I know that there are external services like Perma.cc or PermanentLink but I'd like to prevent using an external service.

So my questions would be:

• Since mkdocs is a tool to build static sites would it even be possible to implement such a feature?
• Is there another existing solution I have overlooked?

[squidfunk]

What I do on the official docs is use the redirects plugin when I move pages, which should also fulfill most of your requirements. It does not work with anchors (yet?) which I already reported in mkdocs/mkdocs-redirects#16, but it should be enough for most cases. Thus, when moving a page, always create a redirect:

mkdocs-material/mkdocs.yml

Lines 92 to 98 in 88cfda4

	- redirects:
	redirect_maps:
	changelog/insiders.md: insiders/changelog.md
	reference/meta-tags.md: reference/index.md
	reference/variables.md: https://mkdocs-macros-plugin.readthedocs.io/
	sponsorship.md: insiders/index.md
	upgrading.md: upgrade.md

[remipregh]

Hi @MrF3lix,
We've encountered the same issue when we moved to mkdocs and mkdocs-material.*
As our products have context-sensitive help, we went for the following solution:

1. Addition of UIIDs in each .md files

---
context_ids:
  - 30c6926f-ae00-48d6-b823-5ec25aa05031
_description: 'Description'
---
# Alerts

2. Creation of a .json file with the UIID/path correspondence during build time (we have created a dedicated plug in that runs alongside mkdocs-material)

{
"30c6926f-ae00-48d6-b823-5ec25aa05031": "Alerts/",

3. Injection of javascript code in the template that generates the root index page of the static site

We now try to always use the following URL format (using the example above):
www.mysite.com/index.html?id=30c6926f-ae00-48d6-b823-5ec25aa05031
which automatically redirects to
www.mysite.com/Alerts/index.html

Hope that gives you some implementation ideas

@squidfunk, happy to share the code with you if you want to implement it in your implementation at some point!

[skeller1]

Hi, thank you for sharing your solution.

In my company we used Help & Manual crap with the same context-sensitive help approach.

Inspired by your comment we came up with this "javascript free" approach:

mkdocs.yml

...
hooks:
  - ./hook.py

hook.py

import logging
import mkdocs.plugins

log = logging.getLogger('mkdocs')

@mkdocs.plugins.event_priority(-50)

def on_page_content(html, page, config, files):

    # get redirect config
    redirect_plugin = config.get('plugins', {}).get('redirects')
    redirects = redirect_plugin.config.get('redirect_maps',{})

    if "context_id" in page.meta:
        context_id = page.meta.get("context_id")
        key = f"{context_id}.md"
        if key in redirects:
            log_context_id_warning(page.meta.context_id, page.file.src_path, redirects[key])
        redirects[key] = page.file.src_path

    for item in page.toc.items:
        # maybe implement check for UUID or something else
        if item.id.isdigit():
            key = f"{item.id}.md"
            if key in redirects:
                log_context_id_warning(item.id, page.file.src_path, redirects[key])
            redirects[key] = f"{page.file.src_path}{item.url}"

def log_context_id_warning(context_id, markdown1,  markdown2):
    log.warning(f"Context ID {context_id} used in {markdown1} and {markdown2}")

Usage:

1. Set context_id in page meta data

---
context_id: 30c6926f-ae00-48d6-b823-5ec25aa05031
---

or

2. Define headline with custom id

# My h1 Headline
Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.

## My h2 Headline {#30c6926f-ae00-48d6-b823-5ec25aa05031}
At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet.

...

At the end mkdocs is generating the redirect for us

localhost:8000/30c6926f-ae00-48d6-b823-5ec25aa05031 => redirect to the correct markdown file

This is my first mkdocs hook, so maybe there's some place for optimization

Thank you for the inspiration

[squidfunk]

This is an awesome solution, thanks for sharing! 🚀

[darksidemilk]

Another thanks to all the people sharing these solutions!
I'm trying to find more documentation on the context-id property and not finding anything, can anyone direct me to where I can read up on that.
@skeller1 @remipregh Are you manually making a uuid for each page, or have you found a way to do it programmatically that you can share?
I'm looking to add this uuid linking to a mkdocs material site I'm helping with, https://docs.fogproject.org
One thing that's needed for it to work in a public site is to display the permanent link to a given page somewhere. Ideally this could be embedded in the toc.permalink, or in the header or footer. I was able to use the mkdocs macros plugin to grab the context-id out of metadata and then display that as a link at the top of a page (see https://docs.fogproject.org/en/latest/b4ddda2f-b9b6-46c2-a881-8bcd082b47db ) but that's a bit ugly and manual to have at the top of every single page. It's just a proof of concept and I borrowed @skeller1's hook script to make it work.

Just wondering if any of the people in this thread have a solution they can share before I go down a rabbit hole. This seems like something someone may have already made a plugin for, especially since context-id seems to be built in to some part of markdown or mkdocs. Just want to make sure I'm not about to re-invent the wheel.

[skeller1]

@skeller1 @remipregh Are you manually making a uuid for each page, or have you found a way to do it programmatically that you can share?

Our XAML/CSharp application has other 2000 forms. Each form has its one name (e.g. 32115). The help url is simply generated through the redirect:

- context_id = 32115
- page redirect: URL: https://host.name/<context_id> => https://host.name/path/can/change
- headline redirect: URL: https://host.name/<context_id> => https://host.name/path/can/change#<context_id>

So it's not neccessary to generate the uuid or context id - the authors have to add the correct context_id to the headline or page meta data. This is a mandatory step.

For your specific problem:

AFAIU: Overriding the header template and adding a link with page.meta.context_id is the way to go.

The generation of the UUID must always be deterministic (after restructuring the markdown files, renaming, moving, deleting).
This is not possible without storing some information. 🤔

Maybe its possible to store the redirect data and reuse it for each build (git diff usage). But this feels hacky!!!!

[skeller1]

the latest version of the hook with minor bugfixing:

import logging
import mkdocs.plugins
import os

log = logging.getLogger('mkdocs')

@mkdocs.plugins.event_priority(-50)

def on_page_content(html, page, config, files):
    redirect_plugin = config.get('plugins', {}).get('redirects')
    redirects = redirect_plugin.config.get('redirect_maps',{})

    if "context_id" in page.meta:
        context_id = page.meta.get("context_id")
        key = f"{context_id}.md"
        if key in redirects:
            log_context_id_warning(page.meta.context_id, page.file.src_path.replace(os.sep, "/"), redirects[key])
        redirects[key] = page.file.src_path.replace(os.sep, "/")

    for item in page.toc.items:
        add_redirect(item, page, redirects)

def add_redirect(item, page, redirects):
    if item.id.isdigit():
        key = f"{item.id}.md"
        if key in redirects:
             log_context_id_warning(item.id, page.file.src_path.replace(os.sep, "/"), redirects[key])
        redirects[key] = f"{page.file.src_path}{item.url}".replace(os.sep, "/")
    for child in item.children:
        add_redirect(child, page, redirects)    

def log_context_id_warning(context_id, markdown1,  markdown2):
    log.warning(f"Context ID {context_id} used in {markdown1} and {markdown2}")