Localized blog category names

[dragomano]

I'm using Mkdocs Material with Blog feature. Locale is 'ru'. How can I define category names to get similar behavior:

Category url: /articles/
Post url: /articles/post-slug/
Category link in the nav: Статьи (/articles)

When I define category via post metadata, I can only setup 'Статьи' (the url will be /stati, but I want to get '/articles`), or 'Articles' (but I want to see the 'Статьи' label in the nav). Any ideas? Is there any index file to define category name?

[squidfunk]

Thanks for asking. The category slug is generated from the name of the category. You could define a custom categories_slugify function that maps categories in Russian to anything else, so you would use Статьи in the front matter, and then map that to articles or whatever you like.

[dragomano]

Could you provide an example of such mapping?

I tried such a code, but it doesn't work:

      categories_slugify: !!python/object/apply:pymdownx.slugs.slugify
        kwds:
          case: lower
          mapping:
            'Статьи': 'articles'

[alexvoss]

You would need to write a custom Python function that does the mapping and that replaces the pymdownx.slugs.slugify function that is used by default. Note that the code needs to be in your PYTHONPATH, so you might need to set that environment variable when building your project.

Edit: something like the following would do the trick. Note that I call the slug-producing function from within the pymdownx.slugs module, so get the default behaviour except for the added substitution.

import functools
import pymdownx.slugs

def _make_slug(text, sep, **kwargs):
    slug = pymdownx.slugs._uslugify(text, sep, **kwargs)
    if slug == "hello":
        return "goodbye"
    return slug

def slugify(**kwargs):
    return functools.partial(_make_slug, **kwargs)

Put it into a subdirectory code or so and make sure it is on the PYTHONPATH, then configure mkdocs.yml:

plugins:
  - search
  - blog:
      categories_slugify: !!python/object/apply:slugs.slugify
        kwds:
          case: lower

[dragomano]

Finally, I found a solution to do it with a hook:

def on_pre_page(page, config, files):
    titles = {
        "some_slug/": "Custom Title 1",
        "another_slug/": "Custom Title 2",
    }
    if page.url in titles:
        page.title = titles[page.url]
    return page

def on_page_markdown(markdown, page, config, files):
    replacements = [
        ("# some_slug", "# Custom Title 1"),
        ("# another_slug", "# Custom Title 2"),
    ]
    for old, new in replacements:
        markdown = markdown.replace(old, new)
    return markdown

Will this solution have any side effects or is it safe?

[alexvoss]

Hooks are there to respond to build events, which is not what is needed here. The code provides a function that Material calls to get a slug.

Your suggestion made me wonder about the PYTHONPATH issue. My initial reaction was to suggest that registering the code as a hook (even though it is not really one) might help to ensure it gets imported. However, that does seem too hacky to me. Better to think of a more principled way to ensure that user code end up on the path.

[alexvoss]

I am not sure the hook version you posted solves the original problem? Was the idea not to have one string for the navigation and another for the slug?

[dragomano]

I just wanted to get category titles independent of their slugs. For example, by default, a blog category with the 'test' slug has the title 'Test'. What if I want to have 'Another title' without changing the slug? This is all the more relevant for multilingual versions of the blog.

It would be ideal to be able to define the title of blog category via frontmatter in .meta.yml, but I don't see how to do that in the free version.

Why not add support for such syntax in the future?

titles:
  example_slug: My title
  second_slug: My another title

[alexvoss]

There is only so much that can be made configurable without causing a maintenance and documentation nightmare. That is why there are plenty of ways to customize.

As you rightly point out, it would be possible to organize the posts into folders according to categories and use the Mate plugin to set both the category and the title. That is assuming that there is only one category per post or that you are happy to add other categories manually and that they don't lead to the same problem.

The Meta plugin is part of the Chipotle funding goal, so you could help push this feature into the public version.

In the meantime, does the code I posted not do what you need? Unless I misunderstood the original request, it seems that it should.