[youyongsong]

A documentation site that added a shell script under docs/scripts/ failed every build from then on, with an error that says nothing about the directory.

What happens

AlaudaDevops/tektoncd-operator added docs/scripts/test-doc-branding.sh to both its main and release-4.6 branches. From that commit on, every docs build of both branches failed — 65 runs over two days, none green — while rendering the site:

error   Page "/scripts/products" SSG rendering failed.
    File: /workspace/source/node_modules/@alauda/doom/lib/products/index.js
    TypeError: Cannot read properties of undefined (reading 'all_product_documentation')

Moving the script out of docs/ — to the repository root, or into docs/shared/ — made the build pass with nothing else changed.

Why

getCommonConfig lists the docs root and makes every directory a language, apart from dist, node_modules, public and shared. The global plugin gives each language a /<lang>/login and a /<lang>/products page, and the products page takes its heading from TRANSLATIONS[lang], which only has en, zh and ru. So scripts became a language, its products page looked up TRANSLATIONS.scripts, and rendering threw.

A site cannot work around this in its config. Only -I / -E on the command line choose languages, and a themeConfig.locales list in doom.config.yml is appended to the detected list by mergeRsbuildConfig rather than replacing it: en then appears twice and the build stops at routePath /login has already been added.

The rest of doom already treats SUPPORTED_LANGUAGES as the list of languages — doom lint only lints those directories, doom translate only accepts those languages, and the i18n guide describes en/zh subfolders. Locale detection was the one place that took any directory.

The fix

After -I / -E have picked the candidates, a directory whose name is not one of SUPPORTED_LANGUAGES is not a language. It stays in allLanguages, so it lands in unusedLanguages and its routes are excluded exactly like an unselected language's. None of its files becomes a page, which matters because rspress treats .js, .ts and .tsx files as pages too. A warning names the directory:

Skipped `docs/scripts`: not a language directory (doom builds en, zh, ru), so no pages are built from it, like `shared`

Deliberate behaviours, all covered by tests:

• -I / -E are applied first, unchanged. A directory they leave out was already excluded and still is, silently. The warning only fires for a directory that would otherwise have become a language in this build.
• A directory of pages in a language doom does not support, such as docs/ja/, is skipped the same way, and the build goes on. Its pages are not on the site, and the warning is the only sign of it.
• Sites that set lang to an empty value (the Chinese-only mode) never run locale detection and are not affected.

Verification

• New test/cli/load-config.spec.ts, 7 tests, lays out docs roots in a temp directory and runs loadConfig on them: scripts, images and ja directories are not languages and their routes are excluded; the global plugin no longer adds /scripts/products; -I behaves as before and stays silent; shared and public are untouched; every supported language keeps its display name; and TRANSLATIONS covers exactly SUPPORTED_LANGUAGES.

• The new tests were run against the unmodified source first. The scripts, images and ja tests fail there on the language list (["en", "scripts", "zh"] and so on), so they test the bug rather than a fixture.

• yarn build, yarn test (665 passed), yarn typecov (100%), yarn lint and yarn docs:build pass locally.

• End to end on the site that failed: a copy of tektoncd-operator release-4.6 at 11ddf575, with dependencies installed and package.json scripts rewritten the way its docs pipeline does it, built with the pipeline's own scripts. "This PR" is packages/doom/lib built from this branch, which differs from the published 2.8.2 package only in lib/cli/load-config.js.

  doom	script	result
  2.8.2 (published)	build-exports (-E ru)	fails after 81 s with the pipeline's error, line for line
  this PR	build-exports (-E ru)	passes in 76 s; products pages /products and /zh/products only; one warning, for docs/scripts
  this PR	build-exports-russian (-I ru -I en)	passes in 74 s; no warning, since -I leaves scripts out before it is judged
  this PR	build-exports with an added docs/ja/index.md	passes in 72 s; warnings for docs/ja and docs/scripts; nothing from either directory in dist

🤖 Generated with Claude Code

[changeset-bot]

🦋 Changeset detected

Latest commit: 54e418c

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@alauda/doom	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[pkg-pr-new]

Open in StackBlitz

yarn add https://pkg.pr.new/@alauda/doom@365.tgz

yarn add https://pkg.pr.new/@alauda/doom-export@365.tgz

commit: 54e418c

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 65.94%. Comparing base (8a42d57) to head (54e418c).

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #365      +/-   ##
==========================================
+ Coverage   65.39%   65.94%   +0.54%     
==========================================
  Files          99      100       +1     
  Lines        3893     3900       +7     
  Branches     1153     1151       -2     
==========================================
+ Hits         2546     2572      +26     
+ Misses       1070     1056      -14     
+ Partials      277      272       -5     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.