Make a filter similar to MkDocs' url filter

[Andre601]

I want to make a filter similar to MkDocs' url filter, since it seems like it is not available through the macros plugin itself.

Looking at the code of MkDocs, it seems to be structured like this:

class TemplateContext(TypedDict):
    nav: Navigation
    pages: Sequence[File]
    base_url: str
    extra_css: Sequence[str]  # Do not use, prefer `config.extra_css`.
    extra_javascript: Sequence[str]  # Do not use, prefer `config.extra_javascript`.
    mkdocs_version: str
    build_date_utc: datetime.datetime
    config: MkDocsConfig
    page: Page | None

@contextfilter
def url_filter(context: TemplateContext, value: str) -> str:
    """A Template filter to normalize URLs."""
    return normalize_url(str(value), page=context['page'], base=context['base_url'])

The issue I see right now is, that recreating the filter like this:

from mkdocs.utils.templates import TemplateContext
from mkdocs.utils import normalize_url

def define_env(env):
    
    @env.filter
    def correct_url(context: TemplateContext, value: str) -> str:
        return normalize_url(str(value), page=context['page'], base=context['base_url'])

...would result in a filter that requires the value to be provided, which is not ideal for me...
I basically want a carbon-copy of the url filter, meaning I could do {{ page.url | url }} and it properly filters the URL to work.

What is a recommended aproach here? Or does the plugin offer a filter for this functionality? I'm aware the fix_url method exists in python, but I would like to have a filter usable for jinja2 templating...

[fralau]

I would need to know more about the context. What issue do you wish to solve and when does it occur?

• Where is the MkDocs url filter and what does it do??
• Why does normalize_url`need a value?

[Andre601]

• It's located here (And imported here) and is normalizing urls, which from what I found out returns a URL relative to the given page or uses the base (See here).
• It's the macro reporting to need a required value 'value'. Not sure if I can pass whatever is given as variable through the env or smth...? Like I have no knowledge of how filters work and the jinja2 doc was no big help here...

[fralau]

A jinja2 filter is basically a Python function that processes its first argument (string) as input. It is syntactic sugar (clearly inspired by shell "pipe" syntax).

[Andre601]

Managed to get a working filter using this:

from mkdocs.utils import normalize_url

def define_env(env):

    @env.filter
    def url(path: str):
        return normalize_url(path=path, page=env.page)

Allows me to have {{ page.url | url }}

[SuibianP]

I feel it might be good to have in the global namespace by default, since it is of common use when building custom navigation, and also matches MkDocs behaviour.

[fralau]

@SuibianP You're welcome to open an issue suggesting that, refering to this discussion!

[SuibianP]

#236 :)