feat(docs): sidebar item key attribute - fix docs translations key conflicts
#11228
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
✅ [V2]
To edit notification comments on pull requests, go to your Netlify project configuration. |
|
Size Change: +24.1 kB (+0.21%) Total Size: 11.5 MB
ℹ️ View Unchanged
|
⚡️ Lighthouse report for the deploy preview of this PR
|
|
Size Change: +24.4 kB (+0.2%) Total Size: 11.9 MB
ℹ️ View Unchanged
|
This was referenced Jun 4, 2025
…orwarded to frontend as props for all sidebar items
7 tasks
key attribute - fix docs translations key conflicts
3 tasks
josh-wong
added a commit
to scalar-labs/docs-scalardb
that referenced
this pull request
Oct 6, 2025
When labels have duplicate names, the sidebar must contain a `key` attribute. Without these `key` attributes, Docusaurus 3.9 (and likely later unless this specification changes) will encounter errors during the build process. As described in the Docusaurus blog post for 3.9: "In #11228, we added a new `key` attribute to the docs sidebar items, allowing to assign explicit translation keys to each sidebar item that use the same label and would otherwise lead to translation key conflicts." Related Docusaurus PR: facebook/docusaurus#11228
This was referenced Oct 6, 2025
josh-wong
added a commit
to scalar-labs/docs-scalardl
that referenced
this pull request
Oct 6, 2025
When labels have duplicate names, the sidebar must contain a `key` attribute. Without these `key` attributes, Docusaurus 3.9 (and likely later unless this specification changes) will encounter errors during the build process. As described in the Docusaurus blog post for 3.9: "In #11228, we added a new `key` attribute to the docs sidebar items, allowing to assign explicit translation keys to each sidebar item that use the same label and would otherwise lead to translation key conflicts." Related Docusaurus PR: facebook/docusaurus#11228
josh-wong
added a commit
to scalar-labs/docs-scalardl
that referenced
this pull request
Nov 4, 2025
* Upgrade Docusaurus from 3.7.0 to 3.9.1 * Move `onBrokenMarkdownLinks` to markdown hooks The onBrokenMarkdownLinks option was removed from the root config and added under markdown.hooks to align with updated Docusaurus configuration structure. This change complies with a change made in Docusaurus 3.9: facebook/docusaurus#11283 * Add `onDuplicateRoutes` configuration * Change version number in description * Update Node.js version to `20` Bump Node.js version from `18` to `20` in deploy and test-deploy GitHub Actions workflows to ensure compatibility with the latest Node.js features and security updates. This is necessary because Docusaurus 3.9 drops support for Node.js 18: https://docusaurus.io/blog/releases/3.9#dropping-nodejs-18 * Ensure output directory exists before writing JSON Added logic to create the output directory if it does not exist before writing the glossary JSON file. This prevents errors when the specified output path's directory is missing. * Add `key` attributes for labels with duplicate names When labels have duplicate names, the sidebar must contain a `key` attribute. Without these `key` attributes, Docusaurus 3.9 (and likely later unless this specification changes) will encounter errors during the build process. As described in the Docusaurus blog post for 3.9: "In #11228, we added a new `key` attribute to the docs sidebar items, allowing to assign explicit translation keys to each sidebar item that use the same label and would otherwise lead to translation key conflicts." Related Docusaurus PR: facebook/docusaurus#11228 * Add `colorMode` to respect user's light/dark theme preference Introduced a colorMode section in the Docusaurus config to set the default mode to light, enable the color mode switch, and respect the user's preferred color scheme. * Change `current` to version number (`3.12`) * Change format of `key` values Addresses: #1011 (comment) Co-Authored-By: Jun Nemoto <35618893+jnmt@users.noreply.github.com> * Upgrade Docusaurus form 3.9.1 to 3.9.2 --------- Co-authored-by: Jun Nemoto <35618893+jnmt@users.noreply.github.com>
josh-wong
added a commit
to scalar-labs/docs-scalardb
that referenced
this pull request
Nov 4, 2025
* Move `onBrokenMarkdownLinks` to markdown hooks The onBrokenMarkdownLinks option was removed from the root config and added under markdown.hooks to align with updated Docusaurus configuration structure. This change complies with a change made in Docusaurus 3.9: facebook/docusaurus#11283 * Fix link to ABAC doc in Japanese * Upgrade Docusaurus from 3.7.0 to 3.9.1 * Change `current` to `3.15` in description * Add `onDuplicateRoutes` configuration * Fix incorrect label * Add `key` attributes for labels with duplicate names When labels have duplicate names, the sidebar must contain a `key` attribute. Without these `key` attributes, Docusaurus 3.9 (and likely later unless this specification changes) will encounter errors during the build process. As described in the Docusaurus blog post for 3.9: "In #11228, we added a new `key` attribute to the docs sidebar items, allowing to assign explicit translation keys to each sidebar item that use the same label and would otherwise lead to translation key conflicts." Related Docusaurus PR: facebook/docusaurus#11228 * Change URL identifiers Change as suggested by Gemini code review: #1564 (comment) * Ensure output directory exists before writing JSON Added logic to create the output directory if it does not exist before writing the glossary JSON file. This prevents errors when the specified output path's directory is missing. * Update Node.js version to `20` Bump Node.js version from `18` to `20` in deploy and test-deploy GitHub Actions workflows to ensure compatibility with the latest Node.js features and security updates. This is necessary because Docusaurus 3.9 drops support for Node.js 18: https://docusaurus.io/blog/releases/3.9#dropping-nodejs-18 * Add `colorMode` to respect user's light/dark theme preference Introduced a colorMode section in the Docusaurus config to set the default mode to light, enable the color mode switch, and respect the user's preferred color scheme. * Change format of `key` values Addresses the following comment made in the ScalarDL docs site repository: scalar-labs/docs-scalardl#1011 (comment) * Upgrade Docusaurus from 3.9.1 to 3.9.2
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
EDIT: for Docusaurus v3.9.2 we are also "fixing/completing" this feature with an additional
sidebar_keyfront matter that you can add to docs: #11490Motivation
This is now possible to pass a
keyattribute to sidebar items to uniquely identify them.Why?
Usage for Docusaurus i18n
The only place Docusaurus uses it is for generating unique i18n translation keys and avoid translation key conflicts (fix #10913).
If the 2 categories have the same label, we can now use the key to generate unique translation keys
docs.<sidebarName>.category.api-for-feature-{1,2}instead of having a translation key conflictdocs.<sidebarName>.category.API.Docusaurus will tell you when there's an i18n key conflict, so it's not really useful to add
keyattributes ahead of time.Usage for your own reasons
Alternatively, you may have your own reasons to do so.
For example, you can add
keyattributes and then swizzle the React sidebar item components and doing something fancy with thekeyyou receive on the client-side.Test Plan
Unit tests + dogfood
Test links
Dogfood: https://deploy-preview-11228--docusaurus-2.netlify.app/tests/docs/category/category-index-name-conflict
Docs: https://deploy-preview-11228--docusaurus-2.netlify.app/docs/sidebar/#passing-custom-props