Skip to content

scripts: sync-website-docs can flatten docs and break Docusaurus build #1096

Description

@wayyoungboy

Evidence

Recent commit: cb52e3017ab68b619fa1dd9cc69804a5a01ea8a4 / PR #1090 added scripts/sync-website-docs.sh and changed scripts/deploy-frontend.sh to call it.

The new script iterates source directories with a trailing slash:

for dirname in "$SOURCE_DOCS_DIR"/*/; do
    ...
    cp -R "$dirname" "$WEBSITE_DOCS_DIR/"
done

In a local reproduction, that copied each documentation directory's contents into docs/website/docs/ instead of preserving category directories like docs/website/docs/guides/ and docs/website/docs/api/.

Reproduction

git checkout cb52e3017ab68b619fa1dd9cc69804a5a01ea8a4
cd docs/website
npm ci
cd ../..
./scripts/sync-website-docs.sh
find docs/website/docs -maxdepth 2 -type d | sort
cd docs/website
npm run build

Observed copied files were flattened at docs/website/docs/, for example docs/website/docs/0001-getting_started.md, with no docs/website/docs/guides/ directory.

The Docusaurus build then fails because docs/website/sidebars.ts still autogenerates sidebars from category directories:

[WARNING] No docs found in "guides": can't auto-generate a sidebar.
[ERROR] Sidebar category Guides has neither any subitem nor a link.

Expected

./scripts/sync-website-docs.sh should preserve the source directory names under docs/website/docs/, so guides, api, examples, etc. remain available to the Docusaurus autogenerated sidebars.

Minimal fix

Copy the directory path without the trailing slash, for example:

cp -R "$SOURCE_DOCS_DIR/$name" "$WEBSITE_DOCS_DIR/"

or strip the trailing slash before copying:

src="${dirname%/}"
cp -R "$src" "$WEBSITE_DOCS_DIR/"

I verified the minimal copy-path change preserves docs/website/docs/guides, docs/website/docs/api, etc., and npm run build then completes for both en and zh locales.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type
    No fields configured for issues without a type.

    Projects

    Status
    In progress

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions