Site language selector: Redirect incorrectly on Github Repository Pages

[ittuann]

Context

No response

Bug description

On GitHub Pages for repository projects (not personal sites like username.github.io), the Site Language Selector fails to redirect correctly. This issue is not occur for the same projects when they are deployed on Vercel or Netlify domains, even though they are also based on the same gh-pages branch.

When selecting a language from the navigation bar's Site Language Selector, the following behavior is observed:

• Select Chinese (default website language):
  • https://ittuann.github.io/Awesome-IntelligentCarRace/ -> https://ittuann.github.io/
• Select English:
  • https://ittuann.github.io/Awesome-IntelligentCarRace/ -> https://ittuann.github.io/en/

Related links

• Site language selector
• Changing the language

Reproduction

9.5.2-site-language-selector.zip

This Github Pages in the repository are all automatically built using GitHub Actions. If needs to track down additional issues or diagnose problems, refer to the workflow configuration files and logs of GitHub Actions, which may help you in understanding and reproducing the issue.

Steps to reproduce

When selecting a language from the navigation bar's Site Language Selector, the following behavior is observed:

• Select Chinese (default website language):

  • https://ittuann.github.io/Awesome-IntelligentCarRace/ -> https://ittuann.github.io/ (Incorrect Behavior)
  • https://awesome-intelligentcarrace.vercel.app/ -> https://awesome-intelligentcarrace.vercel.app/ (Expected Behavior)

• Select English:

  • https://ittuann.github.io/Awesome-IntelligentCarRace/ -> https://ittuann.github.io/en/ (Incorrect Behavior)
  • https://awesome-intelligentcarrace.vercel.app/ -> https://awesome-intelligentcarrace.vercel.app/en/ (Expected Behavior)

Expected Behavior

• Select Chinese:

  • https://ittuann.github.io/Awesome-IntelligentCarRace/ -> https://ittuann.github.io/Awesome-IntelligentCarRace/

    The URL remain https://ittuann.github.io/Awesome-IntelligentCarRace/ for the GitHub Pages site of this repository.

• Select English:

  • https://ittuann.github.io/Awesome-IntelligentCarRace/ -> https://ittuann.github.io/Awesome-IntelligentCarRace/en/

Browser

No response

Before submitting

• I have read and followed the bug reporting guidelines.
• I have attached links to the documentation, and possibly related issues and discussions.
• I assure that I have removed all customizations before submitting this bug report.
• I have attached a .zip file with a minimal reproduction.

[kamilkrzyskow]

Hello @ittuann,
I don't see an mkdocs.yml file in the reproduction zip 🤔
However from the example:

Select Chinese (default website language):
    https://ittuann.github.io/Awesome-IntelligentCarRace/ -> https://ittuann.github.io/
Select English:
    https://ittuann.github.io/Awesome-IntelligentCarRace/ -> https://ittuann.github.io/en/

I believe the issue is a lack of configured site_url MkDocs setting:
https://www.mkdocs.org/user-guide/configuration/#site_url

By default it expects the page to be located at / and in your case it's /Awesome-IntelligentCarRace/, therefore add:

site_url: https://ittuann.github.io/Awesome-IntelligentCarRace/

to your mkdocs.yml file.

[ittuann]

Hello @ittuann, I don't see an mkdocs.yml file in the reproduction zip 🤔 However from the example:

Select Chinese (default website language):
    https://ittuann.github.io/Awesome-IntelligentCarRace/ -> https://ittuann.github.io/
Select English:
    https://ittuann.github.io/Awesome-IntelligentCarRace/ -> https://ittuann.github.io/en/

I believe the issue is a lack of configured site_url MkDocs setting: https://www.mkdocs.org/user-guide/configuration/#site_url

By default it expects the page to be located at / and in your case it's /Awesome-IntelligentCarRace/, therefore add:

site_url: https://ittuann.github.io/Awesome-IntelligentCarRace/

to your mkdocs.yml file.

Thank you for your response and advice!

I followed the documentation to use the Built-in info plugin to generate this zip file:

plugins:
  - info

For site_url, I configured it just like you mentioned: https://github.com/ittuann/Awesome-IntelligentCarRace/blob/main/docs/mkdocs-base.yml#L3

I created mkdocs-base.yml, which contains the identical configuration for multilingual sites. I used INHERIT: mkdocs-base.yml in mkdocs.yml to inherit these settings.

As for why the mkdocs.yml isn't included in the zip, I'm not quite sure what happened.

[kamilkrzyskow]

OK, my mistake. Looking at the alternate.html partial:

mkdocs-material/src/templates/partials/alternate.html

Lines 35 to 45 in 6b690e9

	{% for alt in config.extra.alternate %}
	<li class="md-select__item">
	<a
	href="{{ alt.link | url }}"
	hreflang="{{ alt.lang }}"
	class="md-select__link"
	>
	{{ alt.name }}
	</a>
	</li>
	{% endfor %}

I thought that the url Jinja function would handle the site_url, but it turned out to be a feature of the i18n plugin:
https://github.com/ultrabug/mkdocs-static-i18n/blob/5f97ac28b9f67a3db0f196edf2a1a0059b718213/mkdocs_static_i18n/reconfigure.py#L334-L337

Therefore, currently you could set it like so:

  alternate:
    - name: Chinese
      link: /Awesome-IntelligentCarRace/
      lang: zh
    - name: English
      link: /Awesome-IntelligentCarRace/en/
      lang: en

However, this setting is global for the build, as in, once it starts to work as intended for GitHub Pages with the /Awesome-IntelligentCarRace/ suffix it will also break your other deployments on Vercel and Netlify as they don't create this structure and expect simple / 🤔
I believe you have to sync the web server deployment behavior for the link lookup to match, and as you can't really do anything about the GitHub Pages repository suffix you could try to modify Vercel and Netlify to match GitHub Pages ✌️

---

As for the info plugin, it also has a bug 😆. It expects the mkdocs.yml file to be in the directory next to the requirements.txt file, and it expects that the files are located in the location where you run mkdocs build:

mkdocs-material/src/plugins/info/plugin.py

Lines 117 to 120 in 6b690e9

	with ZipFile(archive, "a", ZIP_DEFLATED, False) as f:
	for path in ["mkdocs.yml", "requirements.txt"]:
	if os.path.isfile(path):
	f.write(path, os.path.join(example, path))

TBH your approach of putting the mkdocs.yml file in the docs directory seems rather non-standard.

I will later make a PR to use the config_file_path and docs_dir settings:
https://github.com/mkdocs/mkdocs/blob/b3f278ae73d7ef1b04630cb3851807fbc440671c/mkdocs/config/defaults.py#L41-L42
https://github.com/mkdocs/mkdocs/blob/b3f278ae73d7ef1b04630cb3851807fbc440671c/mkdocs/config/defaults.py#L76-L77

[kamilkrzyskow]

I have another idea @ittuann,
perhaps you don't want to or can't configure each web server to have the suffix, but you could create 2 gh-pages branches, 2 deployments. One using the default / and the other using /Awesome-IntelligentCarRace/ alternate links. You can make use of environmental variables to set it up and then use !ENV https://www.mkdocs.org/user-guide/configuration/#environment-variables
This would add to the CI time, but would allow you to keep the previous links on each hosting.

[ittuann]

Thank you for your suggestion!

Considering the potential need to support more languages in the future, I think a better long-term solution for the current version of our software is to move away from relying on GitHub Pages for Repository and instead shift to using own domain. This change will bring greater flexibility and scalability, allowing me to better adapt to various needs that may arise in the future.

[squidfunk]

Thanks for debugging this, @kamilkrzyskow, and thanks to @ittuann for reporting and providing the reproduction.

This issue looks like a problem with configuration, because the alternate links receive the wrong bases. I'm moving this to a discussion.

TBH your approach of putting the mkdocs.yml file in the docs directory seems rather non-standard.

There are some problems with the info plugin and multi-project builds. We'll try to fix them in the coming weeks, as we're starting to provide starter templates for multi-project builds, e.g., multilingual docs etc. So it's kind of an issue, albeit currently rather minor, but we should fix it nonetheless. PRs appreciated!