Skip to main content

Docusaurus Single-Site Bilingual Deployment

This is the default deployment mode for this site. A single build output contains both Chinese and English locales. Chinese pages live at the root path, and English pages live under the /en prefix.

When To Use It​

Use this mode when the whole site has one entry domain, for example:

https://docs.nevergpdzy.cn

The route layout is:

/docs/intro        -> Chinese docs
/blog              -> Chinese blog
/en/docs/intro     -> English docs
/en/blog           -> English blog

This matches Docusaurus' default i18n output. Language switching uses the native localeDropdown, and English links keep the /en prefix.

Build Command​

The default build command is:

npm run build

It generates site stats first, then runs a full bilingual Docusaurus build:

npm run generate:site-stats && docusaurus build

The output directory is build. Chinese pages are emitted at the root of build, and English pages are emitted under build/en.

Environment Variable Fallback​

The repository also supports a split single-locale deployment for ESA Pages. To avoid accidental half-configuration, independent-domain single-locale mode is enabled only when both variables are present:

SITE_URL is set
SINGLE_LOCALE_DEPLOY is set

If either one is missing, the site falls back to single-site bilingual behavior.

That means:

  • url uses the default site URL.
  • Navbar continues to use the native Docusaurus localeDropdown.
  • Hand-written links in the English locale continue to emit /en/docs/intro and /en/blog.
  • Running npm run build still produces the full bilingual output.

The fallback controls configuration and link behavior only. The number of locales in the output is still controlled by the build command. To build the bilingual site, run npm run build.

ESA Pages File Count Risk​

A full bilingual build puts both locales into the same build directory. If a hosting platform counts files only, the current output is below 2000 files. If it counts directories as upload entries too, the total item count is higher.

Local counting commands:

Get-ChildItem build -Recurse -File | Measure-Object
Get-ChildItem build -Recurse -Directory | Measure-Object

If ESA Pages rejects the deployment because of total item count, use the split single-locale deployment.

Deployment Checks​

Before publishing, check:

  1. npm run build completes successfully.
  2. build/en exists.
  3. /docs/intro serves the Chinese docs.
  4. /en/docs/intro serves the English docs.
  5. Navbar still uses the native locale dropdown.
  6. English footer links still contain the /en prefix.
  7. sitemap.xml matches the site domain.