Add support to override repo_url and edit_uri mkdocs.yml settings through front matter

[pereorga]

Context

This feature would enhance flexibility for projects with content sourced from multiple repositories.

Description

By allowing repo_url and edit_uri to be overridden directly in front matter, we would be able to set source-specific edit links. Ideally, it should work with the Built-in Meta plugin to allow managing overrides across directories, without the need to update multiple documentation files.

Related links

• I could not find related issues, this discussion is related to page-specific overrides but for specific features: Override certain config.theme.features (namely navigation.expand) #4902
• Built-in Meta plugin

Use Cases

As mentioned, It would allow for greater flexibility in setting source-specific repository links and edit URIs, enabling per-page and per-directory overrides for projects where documents originate from multiple repositories.

Visuals

No response

Before submitting

• I have read and followed the change request guidelines.
• I have verified that my idea is a change request and not a bug report.
• I have ensured that, to the best of my knowledge, my idea will benefit the entire community.
• I have included relevant links to the documentation, related issues, and discussions to underline the need for my idea.

[squidfunk]

Thanks for suggesting! Honestly, this is an excellent case for customization via hooks, and will also be compatible with the meta plugin. I'm moving this to a discussion, as this can be solved in 5-10 lines of Python code.

[pereorga]

Thank you! This was very useful. For anyone interested, that's the code of the hook that worked for me:

"""
Replaces `repo_url` and `edit_uri` settings defined in .meta.yml files.
"""

import mkdocs.plugins

@mkdocs.plugins.event_priority(-50)
def on_page_context(context, page, config, nav):
    if "repo_url" in page.meta:
        config.repo_url = page.meta["repo_url"]

    if "edit_uri" in page.meta:
        config.edit_uri = page.meta["edit_uri"]

    if "repo_url" in page.meta or "edit_uri" in page.meta:
        page.edit_url = f"{config.repo_url.rstrip('/')}/{config.edit_uri}{page.file.src_uri}"

    return context

I had to manually build page.edit_url by concatenating config.repo_url and config.edit_uri for it to take effect. I imagine MkDocs may have generated the variable already by that stage.

[squidfunk]

Awesome, thanks for sharing! One recommendation is to rather use the on_page_markdown hook, if feasible, as this would make it integrate with the meta plugin. Otherwise, the meta plugin has already run.

[kamilkrzyskow]

on_page_markdown and on_page_content are both good choices, however you're not restoring the previous config value in on_post_page, so a single page modifies the global config for all of the project, I consider this an unwanted side effect.

Also I do not know what are your requirements for the granularity of the approach but I think that repo_url should be enough to automatically derive the edit_url from it.

[pereorga]

thank you both for your comments. I updated my code to not change the configuration. My first example using on_page_context seems to work well, manually building edit_url from repo_url and edit_uri. I actually added a third parameter to optionally strip directory components (in my scenario, the content can come from more than a dozen repositories). I haven't tried again with on_page_context or on_page_markdown, as this is working already with the Meta plugin:

import mkdocs.plugins

@mkdocs.plugins.event_priority(-50)
def on_page_context(context, page, config, nav):

    config_repo_url = config.repo_url
    if "repo_url" in page.meta:
        config_repo_url = page.meta["repo_url"]

    config_edit_uri = config.edit_uri
    if "edit_uri" in page.meta:
        config_edit_uri = page.meta["edit_uri"]

    file_src_uri = page.file.src_uri
    if "edit_uri_strip_levels" in page.meta:
        # Adjust how many directory levels are stripped when determining the
        # relative path within the documentation structure.
        file_src_uri = "/".join(file_src_uri.split("/")[page.meta["edit_uri_strip_levels"]:])

    if "repo_url" in page.meta or "edit_uri" in page.meta or "edit_uri_strip_levels" in page.meta:
        page.edit_url = f"{config_repo_url.rstrip('/')}/{config_edit_uri}{file_src_uri}"

    return context