{"id":16475135,"url":"https://github.com/ncdc/mkdocs-material-mike-lang-repro","last_synced_at":"2026-03-05T10:31:24.495Z","repository":{"id":66603043,"uuid":"602657554","full_name":"ncdc/mkdocs-material-mike-lang-repro","owner":"ncdc","description":null,"archived":false,"fork":false,"pushed_at":"2023-02-16T17:42:24.000Z","size":3,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-01-18T18:35:10.645Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ncdc.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-02-16T17:10:56.000Z","updated_at":"2023-02-16T17:10:56.000Z","dependencies_parsed_at":null,"dependency_job_id":"e211567f-c713-4d9a-9046-0abf744ce965","html_url":"https://github.com/ncdc/mkdocs-material-mike-lang-repro","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/ncdc/mkdocs-material-mike-lang-repro","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ncdc%2Fmkdocs-material-mike-lang-repro","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ncdc%2Fmkdocs-material-mike-lang-repro/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ncdc%2Fmkdocs-material-mike-lang-repro/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ncdc%2Fmkdocs-material-mike-lang-repro/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ncdc","download_url":"https://codeload.github.com/ncdc/mkdocs-material-mike-lang-repro/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ncdc%2Fmkdocs-material-mike-lang-repro/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30119427,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-05T09:35:22.236Z","status":"ssl_error","status_checked_at":"2026-03-05T09:35:20.028Z","response_time":93,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-11T12:36:21.905Z","updated_at":"2026-03-05T10:31:24.461Z","avatar_url":"https://github.com/ncdc.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# Example repo for mkdocs-material + mike + multiple languages\n\nThis is an example repo for reproducing some issues I've encountered trying to use mkdocs-material, `mike` for \nmultiple version support, and i8n.\n\nI'm trying to use this for `docs.kcp.io/kcp` and we'd like the following URL structure:\n\n- `docs.kcp.io/kcp/\u003cversion\u003e/\u003clanguage\u003e/...`\n\n## Structure\n\nThis is meant to work with a repo that contains code + docs. All docs live in `docs`.\n\n`docs/config` contains `mkdocs.yml` files, 1 per language, such as `docs/config/en/mkdocs.yml`.\n\n- `site_url` is set to e.g. `https://docs.kcp.io/kcp`. Ideally this would be something more like\n  `https://docs.kcp.io/kcp/{{ version }}/{{ language }}` or something along those lines.\n- `extra.alternate[*].link` ideally should not be needed, or be made optional. The language switcher URL should \n   be `{{ base_url }}/{{ version }}/{{ language }}/{{ current page path }}`\n\n`docs/content` contains per-language content, such as `docs/content/en`.\n\n`docs/generated/branch` is where `mkdocs build` outputs what it builds.\n\n`docs/mkdocs.yml` is just for `mike`. Its `docs_dir` is `generated/branch`, so it deploys everything generated above.\n\n## Workflow\n\n1. Run `mkdocs build` for each language. Output will go to `docs/generated/branch/\u003clanguage\u003e`\n2. After you've built all languages, run `mike deploy --config-file docs/mkdocs.yml`\n\n## Issues\n\n1. The TypeScript that queries `versions.json` assumes that it's located one level up from `base_url`. For a \n   URL such as `docs.kcp.io/kcp/main/en/index.html`, that translates to `docs.kcp.io/kcp/main/versions.json`, which \n   results in a 404. The file actually lives at `docs.kcp.io/kcp/versions.json`. `mike` is configured to deploy to \n   `docs.kcp.io/kcp`, so it places `versions.json` there. The problem arises because my language's `mkdocs.yml` has \n   a `site_dir` of `../../generated/branch/en` but `mike` is deploying `generated/branch`. This adds `en` into the path\n   but when I run `mkdocs build config/en/mkdocs.yml`, it doesn't know that it will end up being served one level \n   deeper. This is where being able to set `site_url` to `https://docs.kcp.io/kcp/{{ version }}/{{ language }}` \n   would be helpful.\n2. The site language selector in `header.html` doesn't seem to allow any dynamic content. It would be really helpful \n   if it were either version aware, or it was possible to customize the href without needing to override the entire \n   `header.html` partial.\n3. The generated canonical URL in the HTML for all pages is missing both the version and the language. For example,\n   `https://docs.kcp.io/kcp/main/en/developers/replicate-new-resource/` has\n```html\n\u003clink rel=\"canonical\" href=\"https://docs.kcp.io/kcp/developers/replicate-new-resource/\"\u003e\n```\n\n## Workarounds\n1. I wrote a [plugin](https://github.com/ncdc/mkdocs-modify-base-url) that lets you customize the `base_url` before\n   content is rendered. This lets me fix the dynamic version retrieval to account for the extra path segment. I added \n   this to the `plugins` section in my language `mkdocs.yml`:\n\n```yaml\n- modify-base-url:\n  prefix: '../'\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fncdc%2Fmkdocs-material-mike-lang-repro","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fncdc%2Fmkdocs-material-mike-lang-repro","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fncdc%2Fmkdocs-material-mike-lang-repro/lists"}