Locale-Aware Doc Exclusion via Frontmatter (enabled_languages); or similar – No Viable Hook?

[hussfelt]

❗️ Problem

We want to conditionally exclude Markdown docs based on a custom enabled_languages frontmatter field, matching the current locale.

For example:

enabled_languages: [en, sv]

This works in en and sv, but should be excluded in for example fi, pt-BR, etc.

🧪 What We Tried (but failed due to build model constraints)

1. Custom Plugin using contentLoaded()

• ✅ Reads frontmatter.
• ❌ Runs after content is loaded, too late to prevent inclusion.

2. Dynamic exclude list in plugin config

• ❌ docusaurus.config.js is only evaluated once, not per locale.
• So all locales inherit the exclusion list for en only.

3. remark plugin to set draft: true

• ❌ remarkPlugins lack access to locale or site config.
• ❌ Attempting to mutate frontmatter at this stage either breaks build or is too late.

4. Using multiple plugin instances (with unique IDs) per locale

• ❌ Leads to plugin ID conflict errors or unexpected behavior due to internal versioning assumptions.

5. File system deletion prebuild (as hack)

• ✅ Works in en, but
• ❌ Fails for i18n folders (i18n/LOCALE/docusaurus-plugin-content-docs/current/...) due to how Docusaurus copies and caches content.

A few other likely similar approaches have been tried during our experiments... :-)

💡 What We Would like

A clean and official hook or mechanism to conditionally exclude docs based on frontmatter per locale, before content is loaded or compiled. Or any other way we can simply "exclude" content per locale, and make sure those specific files are not included as the language specific site is built.

Has anyone attempted this and got it working?

[slorber]

Having locale-only docs/pages is a feature I often get asked about, but by design, it breaks assumptions Docusaurus makes that all locales all have the exact same pages, as I explained here: #11001

If you break this assumption, you are not really localizing an existing site. Instead, you are creating distinct sites for each locale.

❌ docusaurus.config.js is only evaluated once, not per locale.

That's not totally true.

You can access the current locale with process.env.DOCUSAURUS_CURRENT_LOCALE

Although the API is quite bad, it's evaluated once globally (DOCUSAURUS_CURRENT_LOCALE=undefined), and then once per locale (DOCUSAURUS_CURRENT_LOCALE=<currentLocale>.

See also #4542 (comment)

You can also use docusaurus build --config docusaurus.config.myLocale.js and share common plugins in a file like docusaurus.config.shared.js

❌ remarkPlugins lack access to locale or site config.

You can pass process.env.DOCUSAURUS_CURRENT_LOCALE to your custom remark plugins through the config file

Using multiple plugin instances (with unique IDs) per locale
❌ Leads to plugin ID conflict errors or unexpected behavior due to internal versioning assumptions.

Not sure what you mean 😅 need to see the attempt.

File system deletion prebuild (as hack)

Again, if you do this, you are not localizing your site. You are building distinct sites.

If the localized sites are mostly the same, I'd recommend to not delete the pages, but replace the content with some thing like "this content doesn't exist in this language", or adding code to perform a redirect to some other page.

This can eventually be automated using a remark plugin that replaces content with some placeholder/code based on the front matter.

A clean and official hook or mechanism to conditionally exclude docs based on frontmatter per locale, before content is loaded or compiled. Or any other way we can simply "exclude" content per locale, and make sure those specific files are not included as the language specific site is built.

We don't have an official way unfortunately.

I'm open to making things easier, as long as we keep the assumption that we need for i18n SEO that the structure of the localized Docusaurus site.

I created a dedicated issue/proposal: #11076

Can you please comment here and tell us what you think?

Would the "redirect solution" I suggested work for your use case? Before implementing anything, I need to see if all users share the same need, which is still not 100% clear right now.

[hussfelt]

@slorber first off, what a wonderful response. Detailed and with background into each obstacle. Thank you 🙏

Clarifying the usecase; We have a documentation portal that we are launching and some articles simply don't fit the markets. They are extremely local; whole chapters on very market specific content tied into sub-categories. This is why we are experimenting with basically ignoring the content (the most "almost" successful attempts was the plugin that marked .md files as drafts).

I realise after reading my own posts that it was drastically simplified in the experimentations and attempts - and that caused the level of detail in your post. Truly sorry about that.

You can also use docusaurus build --config docusaurus.config.myLocale.js and share common plugins in a file like docusaurus.config.shared.js

This could potentially work for us, and use the ignore pattern for certain documents; not optimal - but there are such few articles that it could work.

❌ remarkPlugins lack access to locale or site config.

You are correct, this slipped me while writing the post and was not the root cause - the root cause was that even if we finished the plugin we were unable to modify the document or remove it in certain languages because it was too late in the lifecycle.

Not sure what you mean 😅 need to see the attempt.

This was really confusing to us as well; we basically tried to hack the docusaurus docs plugin and inject our functions reducing the tree that was built. Let's not go deeper into this; it was a rabbit hole not worth exploring at all. :-)

File system deletion prebuild (as hack)

Again, if you do this, you are not localizing your site. You are building distinct sites.

Yes. We'd like to avoid this. I agree.

If the localized sites are mostly the same, I'd recommend to not delete the pages, but replace the content with some thing like "this content doesn't exist in this language", or adding code to perform a redirect to some other page.

I like this approach. A 301 to a specific page that explains it is not relevant, but it would lower the end user experience if they accidentally traverse and navigate the documentation and then suddenly arrive somewhere else in the tree. Simply "This article is not relevant to your language" could be it. Or maybe marking it as "Market specific" right from the start.

I actually like the approach you take here and the stance that Docusaurus has. I'd like to circle back and discuss this internally.
That said; the neatest feature that we would "like" is the same thing as marking a document as draft, make it available on only certain languages - but I totally see that it would break everything else; so I do not propose such a wide change for the project.

The best thing would be for me to convince the team that "if an article is not intended for a market or a language we show this banner at the top". Meaning localised partial content.

[slorber]

That said; the neatest feature that we would "like" is the same thing as marking a document as draft, make it available on only certain languages - but I totally see that it would break everything else; so I do not propose such a wide change for the project.

As you guessed, there are various ways to break the assumptions Docusaurus relies on (same site structure for each locale):

• if some locales have draft: true and others don't
• using process.env.DOCUSAURUS_CURRENT_LOCALE to create a locale-specific config (for example, compute include/exclude options in plugins)
• other fancy ideas

All these ideas lead Docusaurus to build distinct i18n sites with different structures, which can lead to subtle i18n problems like wrong hreflang headers and weird UX when switching locale on specific pages. It might not be a big deal for many sites, but still good to be aware of.

---

If you don't want to build distinct sites for each locale, you have to respect Docusaurus constraints.

If you agree with that and have a clear idea of the UX you want for your system, I can help implement a POC so that the community can get inspired by it. This should be possible with our current APIs, although not convenient.

If the POC is successfully deployed on various Docusaurus production sites, and we figure out it's satisfying most use cases, then we can think about introducing a first-class API to make all this easier to implement (ie, it wouldn't unlock anything, but it just make things easier, like a config shortcut)

Does it make sense?

[hussfelt]

It makes total sense!

After an internal meeting, where we discussed specifically what you have relayed above regarding Docusaurus vision, we have agreed to keep all articles in all languages - and instead focus on documenting the market specific articles with a clear banner that it is such a thing; market specific.

This will give the benefit that an English or Arabic speaking person living in Sweden can read the documentation in any language they want; even the Swedish market specific ones - which we hadn't really thought about being a usecase.

As such; right now our documentation will be fully available in all languages.

You could hereby see our matter as closed :-)

This conversation has been truly helpful and pivotal in steering our mindset towards the correct approach.
Thank you!

[slorber]

Glad it helps, thanks

I'll see if other users come with different needs in the related issue #11076