[morningman]

Archiving the historical documentation made thousands of aliases point to the same archive page. The publication optimizer combined each destination's aliases into one RewriteRule, producing a 263,259-byte line in the artifact from run 41149820126. Apache rejects .htaccess lines above 8,190 characters, so uncached website requests returned HTTP 500 while cached pages still showed the old 2.1 navigation entry.

This change splits grouped redirects into complete directives of at most 8,000 UTF-8 bytes, including escaped paths, targets and flags. It applies to both root and static-resource controls. Individual redirects that cannot fit fail the build. The existing publication verifier also rejects oversized control lines, including continued lines, before the artifact can be uploaded.

Validation

• DORIS_TEST_APACHE=true node --test scripts/publish/__tests__/*.test.cjs: 30 passed, zero skips. New regressions cover 9,000 archive/asset aliases across five locales, UTF-8 byte limits, oversized individual sources/targets, nested controls, continued lines, query/fragment handling and real Apache responses.
• node --test scripts/__tests__/build-locales.test.cjs: 11 passed, including preservation of the previous artifact after publication verification fails.
• NODE_OPTIONS=--max-old-space-size=2048 node scripts/publish/verify-fixture.cjs --apache: five-locale Rspack production fixture and Apache HTTP checks passed.
• Replayed all 92,059 redirect entries from deployment commit 8321964 locally, using its actual homepage/archive HTML and placeholder redirect destinations. The original controls reproduced HTTP 500 with Line too long; regenerated controls have a maximum line length of 8,000 bytes. All ten locale homepage/archive requests returned 200, and 479 sampled redirect requests matched their expected status and destination.
• git diff --check: passed. The full website build is left to the existing Build Check workflow.

Self-review

• Goal: the deployed failure is reproduced and resolved with the same redirect inventory.
• Scope: changes are confined to publication controls, artifact verification, regression tests and their README.
• Information architecture: active documentation versions, localized destinations and archive routing retain their existing behavior.
• URL compatibility: exact aliases, trailing-slash/index variants, query/fragment behavior and temporary asset redirects are covered by Apache checks.
• Frontend and workflow conventions: existing build/verification entry points are reused; React, styling and workflow permissions are outside this change.
• Verification: the tests cover the failure at both fixture and production-inventory scale; CI will run the complete publishing build.
• Other correctness, accessibility, SEO and maintainability checks: no additional issues found in this focused review.

Versions

• dev
• 4.x
• 3.x
• 2.1 or older (not covered by version/language sync gate)

Languages

• Chinese
• English

The common publication path also covers Japanese, Korean and Russian. No per-language documentation edits are required.

Docs Checklist

• Checked by AI
• Test Cases Built
• Updated required version and language counterparts, or explained why not
• If only one language changed, confirmed whether source/translation counterparts need sync