Common assets/images not showing in the non-default site locale.

TGD-HW commented 3 days ago

Hi, I'm trying to translate my documentation site (MkDocs Material) from my native language CZ-cs (default=true) into EN using i18n. After few days of testing and trying different settings I partially made it. But there is one (maybe more) catch. The EN site does not load some images.

The project repo is public here.

I use mkdocs serve command to run the docs at local 127.0.0.1/8000. For example, when I navigate to

http://127.0.0.1:8000/tgmanGH/en/Manual/CZ/TGZ/TGZ-D-48-13/md/description/

The server fails to load some image from the common dir: ENimgLoadWarning

whereas after switching to the default (CZ) locale it shows OK: LoadOK

The same problem is with some .md files that I include as snippets. It just doesn't load even in default locale: mdIncludeComp

The common files that are missing are located at /docs/Manual/source folder within /img/ and /md/ subfolders Some MD files are not common within locales but within different products (TGZ-xx-yy/zz) so it is also in the /source/ subfolder.

Can anyone help how to solve this issue please. I've given it hours of trying and searching but with no luck. I even tried go through -v (verbose) output of mkdocs log but I'm not an expert and couldn't spot the problem there.

Thank you!

Vaclav

kamilkrzyskow commented 3 days ago

Hello @TGD-HW, you're using HTML img tags in your Markdown files:

https://github.com/TGD-HW/TGi18n/blob/06e4fa51d67e4082af9ae20552128055810f235a/docs/Manual/CZ/TGZ/TGZ-D-48-13/md/description.md?plain=1#L18

<img src="../../../../../source/img/TGZ-D-48-13_26_enetCon.png" alt="ENET/ECAT/LogicPWR connectors" style="width:50%;">

Those tags are constant, they're not being processed by MkDocs, just copied over, and in turn they're not being processed by the mkdocs-static-i18n plugin to take the added lang prefix (in your case /en/) into consideration.

There are multiple ways to solve it:

Use the recommended Markdown way to include images together with attr_list: https://python-markdown.github.io/extensions/attr_list/
```
![alt_title_text](../../../path_to_the_file_in_the_filesystem.png){: style="width: 50%;" }
```
this should be converted into the correct path depending on the language. Or to make it simpler with the width part, perhaps specify CSS classes for small, medium, large images, that you'd use here {: .ext-small-img }.
Add a hook to your MkDocs project that at the end of a specific language build would copy the files from the /Manual/source/img/ directory to the /en/Manual/soruce/img/ directory of the built site. Someone could argue this should be the default behaviour of the plugin, I even think there was such a thing in the 0.56 version of the plugin, but currently the plugin tries to limit the amount of duplication of files via this approach where assets are only stored once under the default language path, and later on the plugin maps the paths if they're written in the format in point 1. https://www.mkdocs.org/user-guide/configuration/#hooks
Add a hook to your MkDocs project that would modify the <img> paths on-the-fly. Probably would add too much processing time, so can't really recommend it.

kamilkrzyskow commented 3 days ago

As for the snippets example, which doesn't work: https://github.com/TGD-HW/TGi18n/blob/06e4fa51d67e4082af9ae20552128055810f235a/docs/Manual/CZ/TGZ/TGZ-D-48-13/md/mark.md

--8<-- "CZ/md/marking.md"

You have defined those base paths:

 - pymdownx.snippets:
      base_path:
        - docs/Manual/source
        - docs/Manual/CZ/TGZ/
        - docs/Manual/CZ/TGS/
        - docs/Manual/CZ/TGM/
        - docs/Manual/CZ/ETC/
        - docs/Manual/CZ/SW/

and no file exists with this path:

        - docs/Manual/source/CZ/md/marking.md
        - docs/Manual/CZ/TGZ/CZ/md/marking.md
        - docs/Manual/CZ/TGS/CZ/md/marking.md
        - docs/Manual/CZ/TGM/CZ/md/marking.md
        - docs/Manual/CZ/ETC/CZ/md/marking.md
        - docs/Manual/CZ/SW/CZ/md/marking.md

therefore the snippets doesn't load.

Also the docs/Manual/source path doesn't have the / at the end, it likely doesn't matter, but it's worth pointing out.

Also be aware that Snippets aren't MkDocs-aware, all base_paths are relative to your current working directory / pwd, so where you run the mkdocs build command, they won't work if you do something like mkdocs build --config-file my_configs/mkdocs.yml

ultrabug / mkdocs-static-i18n

Common assets/images not showing in the non-default site locale. #310