How to resolve docs sidebar items key conflicts when using autogenerated sidebar?

[s-dufour]

Hi docusaurus team,

I'm trying to migrate my docusaurus site to 3.9.1 but I have the following error:
Error: Multiple docs sidebar items produce the same translation key.

The following solution is proposed:
To avoid translation key conflicts, use the key attribute on the sidebar items above to uniquely identify them.

I see how the issue can be solved when using sidebar file. But is there a way to add this key in the page front matter when sidebar is autogenerated?

[slorber]

Thanks for reporting, agree that we should have a sidebar_key front matter for this purpose.

A temporary solution could be to enhance the existing sidebar items generator to resolve the key conflicts and automatically adding a key to the corresponding sidebar items: https://docusaurus.io/docs/next/sidebar/autogenerated#customize-the-sidebar-items-generator

Is your site using multiple locales? Do you also have conflicts on category labels?

[s-dufour]

Hi @slorber, I finally managed to reproduce the issue!
You can find a reproducer here: https://github.com/s-dufour/docusaurus-duplicated-sidebar-label
This is the default docusaurus site with few updates to introduce the issue.
It seems that the issue only occurs if the duplicated sidebar label is a category and the i18n folder exists.
The build is OK with docusaurus 3.8.1 but fails with docusaurus 3.9.1.

[s-dufour]

And I've just found a workaround by moving the sidebar_label in a category.json file and adding a unique key for each one.

[slorber]

I see thanks

So this is the case where 2 categories have the same label. Here each of your categories have a doc index.md with something like:

---
sidebar_label: Duplicated category
---

# Duplicated category

text

Maybe in this specific case, it could be more convenient to let you pass a sidebar_key front matter instead of having to create a _category_.json ?

[s-dufour]

Yes, because except for the need for this key, the _category_.yml file is not necessary in this case.

[slorber]

Agree

I'm considering this a bugfix scheduled for v3.9.2: #11490