How to suppress copying of certain directories under the static directory for certain locales while building the site

[allenscha]

We maintain documentation for a PaaS product that supports multiple platforms, and we are keeping API reference files generated from platform-specific tools such as Dokka, Jazzy, Doxygen, and Typedoc as static resources. While the documentation itself supports multiple locales, the API reference files are in English only and located under the static directory, as follows:

static/api-reference/*

Since the API reference is in English only, we use autoAddBaseUrl: false in the sidebar link config so that the link to the API reference is independent of the current locale.

    type: 'link',
    label: 'API Reference',
    href: 'pathname:///api-reference/*',
    autoAddBaseUrl: false,

However, we recently found out that the content of static/api-reference/* is copied to all locales during the build process, as follows:

// build result
build/api-reference/*
build/{locale1}/api-reference/*
build/{locale2}/api-reference/*
...

Among the files above, all the files in the locale-specific directories are unused and only take up storage space.

Is there a way to improve the current situation? (For your reference, the tested version of Docusaurus is 2.2.0.)

[slorber]

That's the behavior we choose for the static directory, and it makes sense for many other use-cases to keep it that way.

If you don't want one copy of the api ref per locale, then you can simply not use the static directory.

You could build your site and at the end do cp -R my-generated-api-ref website/build/api-reference.
The static folder basically only do that copy/paste for you (really, nothing more), except it does that for each locale.

You don't need Docusaurus in practice to "merge" static files of multiple tools, and cp -R is enough. Just make sure that static files do not conflict with each others to prevent unwanted overrides. Using a baseUrl is generally a good idea it prevent that, instead of having multiple static sites to be hosted at the site root.

[allenscha]

If you don't want one copy of the api ref per locale, then you can simply not use the static directory.

You could build your site and at the end do cp -R my-generated-api-ref website/build/api-reference. The static folder basically only do that copy/paste for you (really, nothing more), except it does that for each locale.

There's other considerations that prevent us from using this suggestion. We need to verify the API reference as part of the site URL while previewing the site with yarn start, and using the static directory and accessing the files through pathname:///api-reference/* seems to be the only option we have for that purpose.

If we keep using the static directory, a workaround would be to add a script to delete the API reference files copied to each locale directory and make the script run after yarn build in the deployment process, but that seems a bit unproductive.

So I'm wondering if it's feasible to add a configuration to exclude some directory under static from being copied to other local directories during build.

[slorber]

but that seems a bit unproductive.

Hey that solves your use-case and is easy so why isn't this good enough?

I feel like we are trying to achieve useless micro-optimisations here.

Is this really a problem in practice to deploy this duplicate api ref?

Is copying for each locale + deleting a perf issue of any kind that's worth us to fix?

---

There is not config to exclude static directories, but we have staticDirectories to let you provide your own list.

https://docusaurus.io/docs/3.0.1/api/docusaurus-config#staticDirectories

Combined with the locale env variable (#4542 (comment)), that could solve the same use-case.

You could for example only list an api-ref static directory if locale is undefined or english.

[allenscha]

Another thing to note is that, in order to use localized assets (images, diagrams, etc.) for each locale in a multi-language site, a typical method would be to place asset files by locale under static as follows:

static
  /{locale1}
  /{locale2}
  /{locale3}
...

or

static
  /img
    /{locale1}
    /{locale2}
    /{locale3}
...

and all these files would be copied to each locale directory during build, while most of them would be unused except in the corresponding locale.

This might be a more complicated case than the original inquiry, but I think it would be beneficial if there is some configuration to control the inclusion/exclusion of certain files under static for build.

[slorber]

This config should work:

export default {
  staticDirectories: [
    'static',
    'staticLocalized/' + (process.env.DOCUSAURUS_CURRENT_LOCALE ?? "en"),
  ],
};

Details in #4542 (comment)