What front matter property or mkdocs config value will let me control the url?

[sheldonhull]

I prefer to setup slug on my hugo blog because I can move content around and as long as the slug is unique I never break links.

In mkdocs, I have subdirectories and these are automatically added to the slug.
Is there a way for me to set my url naming to just require unique slugs and not prefix the directory in the url? This would be prevent me from moving files around because I'd be concerned I'd break all the urls.

[squidfunk]

This is not natively supported by MkDocs. FWIW, the blog plugin allows for explicitly setting slug in front matter, but I don't know of a plugin that does the same for regular documents. Note that for moving content around, the mkdocs-redirects plugin can be used to set up proper redirects for stale URLs. You might also be able to implement this with a few lines of Python as part of a hook.

[sheldonhull]

To be clear the screenshot was live not what I put in codespace. The reproduction was in the codespace and using the urls I put in comments. It was more visually what I was trying to emulate. I’ll test the archive pages too so cheers for that

This is good info. I’ll digest and action as you mentioned. I’ll look at your config as well. Thanks for taking your time to help. 👍

[squidfunk]

Sorry, I don't use codespace 😅 You can call me a boomer, as I'm using VS Code on my bloody old notebook 👴

[sheldonhull]

Hey that's no problem. Just to be clear though, if you have docker on your notebook, the setup I gave is fully compatible with that too. Just does "codespace" as a local containerized environment.

Not saying you need to do it, but it's really great for contributors since everything (including python) can be prebaked in and ready to go. I won't call you a boomer either... not unless you said anyone who edits outside of neovim is a n00b. 🤣

ps: side note... the codespaces thing is nice for bugs if you have't tried it cause you can open the whole thing in the browser fully self contained no install or anything required. give it a try sometime if you feel adventurous 😉

[squidfunk]

I'll definitely give that a try!

[bitsondatadev]

Sorry, I don't use codespace 😅 You can call me a boomer, as I'm using VS Code on my bloody old notebook 👴

I compile my code on my laptop as God intended! 🤣 jk jk...

I'm really interested in codespaces as an elder millenial - which equates to boomer for any zoomers and beyond.

[shenweiyan]

I would like this functionality as well.
It would be great if mkdocs could read a slug from the metadata of each article as the URL for each document.

---
title: My Post Title
slug: my-custom-url
---

[kamilkrzyskow]

I've created an example hook, it has limitations but should be enough to point into the right direction @sheldonhull:
meta-slugs.zip

The main issue of this feature is the fact that the front matter header is loaded for each page sequentially in the on_page_markdown event. To avoid issues with internal link references it's required to read the front matter of all the pages before the MkDocs event. This duplicates the read task, so it decreases overall performance relative to the amount of files.

Current limitations of this solution:

• Primitive collision check for slugs and files, doesn't check if a file has a slug that voids the collision
• use_directory_urls was always True during testing, the hook will not handle False 🤷

meta_slugs.py

import os
from mkdocs.plugins import get_plugin_logger
from mkdocs.utils import meta

log = get_plugin_logger("meta_slugs")


class SlugCollision:
    """Container class to handle the slug collision logic"""

    file_urls: dict[str, str]
    """Dict mapping of file urls to file paths of the original file urls"""

    slug_urls: dict[str, str]
    """Dict mapping of slug urls to file paths of the custom meta slugs"""

    def __init__(self):
        self.file_urls = {}
        self.slug_urls = {}

    def is_valid(self, slug: str) -> bool:
        """Check the slug string for errors and check for collisions"""

        if slug is None:
            return False

        if not isinstance(slug, str):
            log.error(f"'slug' has to be a string not {type(slug)}")
            return False

        if slug.startswith("/") or not slug.endswith("/"):
            log.warning(f"'slug': '{slug}' can't start with a '/' and has to end with a '/'")
            return False

        if "\\" in slug:
            log.error(f"'slug' can't be a Windows path with '\\'")
            return False

        if slug in self.file_urls:
            log.warning(f"'slug': '{slug}' collides with the file: {self.file_urls[slug]}")
            return False

        if slug in self.slug_urls:
            log.warning(f"'slug': '{slug}' was already used in the file: {self.slug_urls[slug]}")
            return False

        return True


def on_files(files, config, **__):
    slug_collision = SlugCollision()

    # First load the ulrs
    for file in files:
        if file.is_documentation_page():
            slug_collision.file_urls[file.url] = file.abs_src_path

    # Second process the meta
    for file in files:
        if not file.is_documentation_page():
            continue

        slug = _load_meta(file).get("slug")

        if not slug_collision.is_valid(slug):
            continue

        # TODO Add handling for `use_directory_urls`
        file.url = slug
        file.dest_uri = slug + "index.html"
        file.abs_dest_path = os.path.normpath(os.path.join(config["site_dir"], file.dest_uri))

        slug_collision.slug_urls[slug] = file.abs_src_path


def _load_meta(file):
    """Local copy of mkdocs.structure.pages.Page.read_source"""

    try:
        with open(file.abs_src_path, encoding="utf-8-sig", errors="strict") as f:
            source = f.read()
        _, file_meta = meta.get_data(source)
        return file_meta
    except OSError:
        log.error(f"File not found: {self.file.src_path}")
        raise
    except ValueError:
        log.error(f"Encoding error reading file: {self.file.src_path}")
        raise

[shenweiyan]

Thank you very much! It seems like it indeed can solve my problem.

[shenweiyan]

meta_slugs.py

@kamilkrzyskow This is a very good method, but for the blog plugin, there will still be a blog prefix in the URL, such as https://example/blog/my_blog_slug/. I wonder if there is a way to change the URL directly to https://example/my_blog_slug/?

[squidfunk]

In order to remove the blog directory, you could move everything up by one level and build a standalone blog. Otherwise, the directory where your blog resides will always be prepended, which, IMHO, makes sense.

[kamilkrzyskow]

@shenweiyan
I did not confirm it, but looking at the hook code I guess the issue stems from the event priorities.

mkdocs-material/src/plugins/blog/plugin.py

Lines 98 to 107 in 4ba7a6d

	# Resolve and load posts and generate views (run later) - we want to allow
	# other plugins to add generated posts or views, so we run this plugin as
	# late as possible. We also need to remove the posts from the navigation
	# before navigation is constructed, as the entrypoint should be considered
	# to be the active page for each post. The URLs of posts are computed before
	# Markdown processing, so that when linking to and from posts, behavior is
	# exactly the same as with regular documentation pages. We create all pages
	# related to posts as part of this plugin, so we control the entire process.
	@event_priority(-50)
	def on_files(self, files, *, config):

The blog plugin processes files a bit late with priority set to -50, and the hook above uses the default priority of 0.
So even though the hook processes the slug from the front-matter it later gets overriden by the blog plugin.

To fix it set a priority of -75 or any lower than -50, but still capped by -100, as that's the convention.
Also as you increase the chance for URL collision, I would at least log a warning / raise a PluginError to immediately crash MkDocs if a collision appears.

All needed reference should be in the blog/plugin.py file above.

EDIT:
As a side note, in another project where such URL collision logic was also needed instead of doing it in on_files, I do it during the build process in on_page_markdown, this helps with the limitations I've pointed out previously, but also doesn't catch errors quickly. So if a collision occurs at a later point of the build (which could take 60s+ if all plugins are enabled) then it hurts a bit more 😅 In our docs with most plugins disabled by default, we build in 9s and such collisions don't happen too frequently, so I opted to using this other approach ✌️

[shenweiyan]

This can either be implemented in MkDocs, or as a hook or plugin.

Thank you very much for the ideas you provided. May I ask if you know of any plugins that can achieve this?

[squidfunk]

Nope, but maybe searching the discussion board will surface some ideas or useful links.

[hanniabu]

This is a pretty standard feature in alternatives, curious why such a feature wouldn't be enshrined

[squidfunk]

Because MkDocs does not support it. Alternatives exist.