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

[TGD-HW]

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:

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

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

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]

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:

1. 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 }.

2. 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

3. 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]

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

[TGD-HW]

Hi @kamilkrzyskow , Thanks for your quick response.

As for the snippets I forgot to change the link in for the snippet while changing the folder structure so it makes sense and works nicely.

However I still can't make the plugin load the images correctly. I would like to do it the correct way, i.e. use the attr_list. I tested it on TGZ-D-48-13

![ENET/ECAT/LogicPWR connectors](../../../../../source/img/TGZ-D-48-13_26_enetCon.png){: style="width: 50%;" }

Removed the direct html tag in both CZ and EN version, the the image still fails to load in the EN version:

Any ideas here? Thanks

[kamilkrzyskow]

There is clearly a warning in the build:

WARNING -  Doc file 'Manual/CZ/TGZ/TGZ-D-48-13/md/description.md' contains a link
           '../../../../../source/img/TGZ-D-48-13_26_enetCon.png', but the target
           'source/img/TGZ-D-48-13_26_enetCon.png' is not found among documentation files. Did you mean
           '../../../../source/img/TGZ-D-48-13_26_enetCon.png'?

WARNING -  Doc file 'Manual/CZ/TGZ/TGZ-D-48-13/md/description.en.md' contains a link
           '../../../../../source/img/1940760000.svg', but the target 'source/img/1940760000.svg' is not
           found among documentation files.

the first warning gives a hint that you added too many ../, you can't just copy-paste the path from the img, you have to adjust it to use the filesystem path, but in general removing 1 ../ should be enough. So ../../../../source/img/1940760000.svg

I hope you're using some semi-automated generator for this structure, because otherwise it's not great to work in. You're using the fallback_to_default setting, so you don't have to define a .en.md file if the contents are the same as the original ❗ Same for assets and images, you don't have to copy every file with a .en.png suffix.

I'm not sure how well established your brand is, how many backlinks, how many google indexed pages you have. If it's not a lot then I would recommend cleaning up the structure a bit.

For example this link:

• /tgmanGH/en/Manual/CZ/TGZ/TGZ-D-48-13/md/description/ I'm assuming that CZ stands for Czech language and the md is the part for the md directory, I would move the files out of this structure into:
  • /tgmanGH/en/Manual/TGZ/TGZ-D-48-13/description/

    [!WARNING] This would of course break all paths etc., so it's just a suggestion.

---

Your main goal for now should be clearing up all of the WARNINGS. Try using the https://www.mkdocs.org/user-guide/configuration/#not_in_nav option, but I'm not sure if it's compatible and respected by the i18n plugin.

Read up on the validation aspect too:

• https://www.mkdocs.org/user-guide/configuration/#validation there is the absolute_links: relative_to_docs setting, but I don't know if it's compatible and respected by the i18n plugin.

You might also be interested in the awesome pages plugin to automate the navigation creation process a bit:

• https://github.com/lukasgeiter/mkdocs-awesome-pages-plugin

[kamilkrzyskow]

I made a quick PR here:

• https://github.com/TGD-HW/tgmanGH/pull/2

[TGD-HW]

Hello, Thank you for your support. The ../ removal was not that straightforward because it caused some errors, however I managed to remove the path errors.

It seems to work ok now. Thanks a lot!

Best regards Vaclav