awesome-pages and i18n compatibility using .pages

[Argald0]

Hi there !

I have just read the issues on @ultrabug's i18n compatibility with awesome-pages from the end of 2021, and from what I read I understood that everything works fine unless there is something unexpected in the mkdocs.yml such as .... Knowing this issue, I decided to go for a .pages file, but I do get 404 errors.

I wasn't sure whether I should put it here or as ultrabug's plugin issue, but I believe I'm doing something wrong with the .pages file, that's why I'm posting here. Would you mind giving it a look plz ?

First of all, I have this project :

mkdocs.yml
docs/
├─ .pages 
├─ index.md
├─ index.fr.md
├─ file2.md
└─ file2.fr.md

With this mkdocs.yml :

site_name: My Docs
theme:
  name: material
  font:
    text: Ubuntu
    code: Ubuntu Mono
  palette:
    scheme: slate
    primary: blue grey
    accent: amber
extra:
  alternate:
    - name: English
      link: ./
      lang: en
    - name: Français
      link: ./fr/
      lang: fr
plugins:
    - search
    - awesome-pages
    - i18n:
        default_language: en
        languages:
          en: english
          fr: français
        nav_translations:
          fr:
            'Welcome': 'Bienvenue'
            'File 2 awesome pages': 'Fichier 2 awesome pages'

This is what my .pages file looks like :

nav:
    - Welcome: index.md
    - File 2 awesome pages: file2.md

While browsing the mkdocs serve, if I change the language from default (english) to french, and try to access one of the pages it outputs a 404 error :

Whereas if I stay in the default language it doesn't :

I also notice that when clicking on a page, the url is /file2.md whereas it should be /fr/file2 : back in the default language instead of staying in the fr part.

Thank you in advance ! 😄

[lukasgeiter]

Yeah I can absolutely reproduce this problem and I also understand what's happening.

When configuring the navigation in mkdocs.yml, the i18n plugin patches the entries to reflect the language it's currently processing. For example when building the French version, it will turn index.md into index.fr.md.

.pages files are not patched this way, so it's trying to find index.md which doesn't exist in the French version. As a fallback, awesome-pages treats Welcome: index.md as a relative link to index.md, resulting in the behavior you're seeing.

Unfortunately, I'm not sure how a good solution would look like. Maybe @ultrabug has an idea?

[Dryamov]

Any ideas?

[ultrabug]

Well @lukasgeiter is not wrong I guess tho i18n does not "turn" index.md to index.fr.md, it just uses as the source of the index file because that's how mkdocs build process works.

@Argald0 you should go fully with the .pages approach and use strict: false option of awesome-pages.

That's how I do it on my own website so you have a working example there.

Which means in your case that you should not use titles in your .pages nav, just use:

nav:
    - index.md
    - index.fr.md
    - file2.md
    - file2.fr.md

and

plugins:
    - search
    - awesome-pages:
        strict: false

EDIT: yes, the build process will complain for missing pages depending on the locale being built, but that's fine.

[kamilkrzyskow]

Using a more dynamic nav like this allows to prevent warnings:

nav:
    - ... | index*.md
    - section_dir
    - ...

I didn't run across any issues with this approach yet 🤔