[GH-2867] Fix empty blog index under i18n suffix mode#2951
Merged
Conversation
The mkdocs-material blog plugin generates archive and pagination views in a tempfile.mkdtemp() directory, which mkdocs-static-i18n's reconfigure_files drops as "Unhandled file case" because they live outside docs_dir. The result on /latest/blog/ was an empty index with no individual posts and no per-post pages. This regression was introduced when i18n was wired up in apache#2920 and is a known incompatibility (ultrabug/mkdocs-static-i18n#283). Add a hook that disconnects blog files from the i18n plugin before its on_files runs and reconnects them after, so the blog renders once in the default language and is served identically under every language version. Remove the .zh.md blog files added in apache#2950 since the current i18n setup cannot serve translated blog content alongside the workaround; they were also confusing the blog plugin's pagination.
Contributor
There was a problem hiding this comment.
Pull request overview
Fixes MkDocs blog rendering under mkdocs-static-i18n suffix mode by adding a hook-based workaround so the Material blog plugin’s generated virtual pages aren’t dropped during i18n file reconfiguration. It also removes Chinese-translated blog sources to avoid duplicate post detection/pagination issues while the workaround forces a single-language blog.
Changes:
- Register a new MkDocs hook to temporarily remove blog-generated files from
Filesbefore i18n processing, then restore them afterward. - Wire the hook into
mkdocs.yml. - Remove
.zh.mdblog index and post translations to prevent duplicate post ingestion/pagination breakage.
Reviewed changes
Copilot reviewed 12 out of 12 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| mkdocs.yml | Registers the new hook module so it runs during MkDocs builds. |
| docs-overrides/hooks/i18n_blog_passthrough.py | Implements the blog/i18n compatibility workaround by disconnecting/reconnecting blog files around i18n processing. |
| docs/blog/index.zh.md | Removed to avoid translated blog index being treated as an additional blog page under the workaround. |
| docs/blog/posts/h3.zh.md | Removed to prevent translated posts being treated as duplicate posts (pagination/archive issues). |
| docs/blog/posts/intro-sedonadb.zh.md | Same as above (removal of translated post). |
| docs/blog/posts/intro-sedonadb-0-2.zh.md | Same as above (removal of translated post). |
| docs/blog/posts/intro-sedonadb-0-3.zh.md | Same as above (removal of translated post). |
| docs/blog/posts/intro-spatialbench.zh.md | Same as above (removal of translated post). |
| docs/blog/posts/intro-to-sedona-blog.zh.md | Same as above (removal of translated post). |
| docs/blog/posts/sedona-2025-year-in-review.zh.md | Same as above (removal of translated post). |
| docs/blog/posts/spatial-query-benchmarking-databricks.zh.md | Same as above (removal of translated post). |
| docs/blog/posts/spatial-tables-lakehouse.zh.md | Same as above (removal of translated post). |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| blog_prefixes.append(instance.config.blog_dir) | ||
|
|
||
| blog_prefix_tuple = tuple(p.rstrip("/") + "/" for p in blog_prefixes) | ||
| config.extra.i18n_blog_prefixes = blog_prefix_tuple |
Comment on lines
+34
to
+42
| BLOG_FILES: list = [] | ||
|
|
||
|
|
||
| @plugins.event_priority(-95) | ||
| def _on_files_disconnect_blog_files(files: Files, config, *_, **__): | ||
| """Remove blog files after the blog plugin's on_files (-50), before i18n's (-100).""" | ||
| global BLOG_FILES | ||
| BLOG_FILES = [] | ||
| non_blog_files: list[File] = [] |
Drop the carried-over config.extra.i18n_blog_prefixes assignment: it was intended for templates that consume the blog-prefix list, but no Sedona template reads it. Tighten the BLOG_FILES annotation to list[File] now that File is already imported.
jiayuasu
added a commit
that referenced
this pull request
May 12, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Did you read the Contributor Guide?
Is this PR related to a ticket?
[GH-XXX] my subject. References Add Chinese version of the documentation #2867.What changes were proposed in this PR?
The blog index at
/latest/blog/currently renders with no posts and no per-post pages get built. The mkdocs-material blog plugin generates its archive and pagination views as virtual files inside atempfile.mkdtemp()directory, butmkdocs-static-i18n'sreconfigure_filesonly handles files that either live underdocs_diror are non-documentation pages — these generated markdown views fall through both buckets and are silently dropped withWARNING - mkdocs_static_i18n: Unhandled file case - blog/archive/2026.md(and similar). This is a known upstream incompatibility tracked in ultrabug/mkdocs-static-i18n#283; it was introduced when i18n was wired up in #2920.This PR:
docs-overrides/hooks/i18n_blog_passthrough.py, an mkdocs hook (based on the workaround in Incompatibility with Mkdocs Material Blog plugin? ultrabug/mkdocs-static-i18n#283) that disconnects blog files from the Files collection between the blog plugin'son_files(priority -50) and the i18n plugin'son_files(priority -100), then reconnects them after. Net effect: the blog renders once in the default language and is served identically under every language version.hooks:entry inmkdocs.yml..zh.mdblog files added in [GH-2867] Translate blog posts to Chinese #2950. The current i18n + blog setup cannot serve translated blog posts alongside this workaround, and leaving the files in place causes the blog plugin to treat them as additional posts (breaking pagination — page 1 was rendering empty with the duplicates spilling to page 2). They can be re-added if upstream i18n + blog compatibility ships.How was this patch tested?
uv run mkdocs build:/blog/, 0 per-post pages generated, multipleUnhandled file casewarnings forblog/archive/*.mdandblog/page/2/index.md./blog/, 9 posts on/zh/blog/, 9 per-post pages under both language roots, noUnhandled file casewarnings.site/locally and browsing/blog/,/blog/2025/09/05/should-you-use-h3-..., and/zh/blog/.Did this PR include necessary documentation updates?