feat(v2): provide doc sidebar_label through sidebars.js (#4500)

* feat : update SidebarItemDoc type

* feat : update assertIsDoc

* feat : allow configuring title from sidebar.js

* feat : add docs

* docs : refactor i18n docs to use label in sidebar.js

* test : add test

* Update website/docs/guides/docs/sidebar.md

Co-authored-by: Sébastien Lorber <slorber@users.noreply.github.com>

* docs : remove backported docs

Co-authored-by: Lisa Chandra <52909743+lisa761@users.noreply.github.com>
Co-authored-by: Javid <singularity.javid@gmail.com>
Co-authored-by: Sébastien Lorber <slorber@users.noreply.github.com>

packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/site-with-doc-label/docs/hello-1.md

@@ -0,0 +1,7 @@
+---
+id: hello-1
+title: Hello 1
+---
+
+Hello World 1!
+

packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/site-with-doc-label/docs/hello-2.md

@@ -0,0 +1,8 @@
+---
+id: hello-2
+title: Hello 2
+sidebar_label: Hello 2 From Doc
+---
+
+Hello World 2!
+

packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/site-with-doc-label/docusaurus.config.js

@@ -0,0 +1,14 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+module.exports = {
+  title: 'My Site',
+  tagline: 'The tagline of my site',
+  url: 'https://your-docusaurus-test-site.com',
+  baseUrl: '/',
+  favicon: 'img/favicon.ico',
+};

packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/site-with-doc-label/sidebars.json

@@ -0,0 +1,14 @@
+{
+  "docs": [
+    {
+      "id": "hello-1",
+      "type": "doc",
+      "label": "Hello One"
+    },
+    {
+      "id": "hello-2",
+      "type": "doc",
+      "label": "Hello Two"
+    }
+  ]
+}

packages/docusaurus-plugin-content-docs/src/__tests__/index.test.ts

@@ -677,3 +677,39 @@ describe('versioned website (community)', () => {
     utils.expectSnapshot();
   });
 });
+
+describe('site with doc label', () => {
+  async function loadSite() {
+    const siteDir = path.join(__dirname, '__fixtures__', 'site-with-doc-label');
+    const context = await loadContext(siteDir);
+    const sidebarPath = path.join(siteDir, 'sidebars.json');
+    const plugin = pluginContentDocs(
+      context,
+      normalizePluginOptions(OptionsSchema, {
+        path: 'docs',
+        sidebarPath,
+        homePageId: 'hello-1',
+      }),
+    );
+
+    const content = await plugin.loadContent();
+
+    return {content};
+  }
+
+  test('label in sidebar.json is used', async () => {
+    const {content} = await loadSite();
+    const loadedVersion = content.loadedVersions[0];
+    const sidebarProps = toSidebarsProp(loadedVersion);
+
+    expect(sidebarProps.docs[0].label).toBe('Hello One');
+  });
+
+  test('sidebar_label in doc has higher precedence over label in sidebar.json', async () => {
+    const {content} = await loadSite();
+    const loadedVersion = content.loadedVersions[0];
+    const sidebarProps = toSidebarsProp(loadedVersion);
+
+    expect(sidebarProps.docs[1].label).toBe('Hello 2 From Doc');
+  });
+});

packages/docusaurus-plugin-content-docs/src/props.ts

@@ -37,7 +37,7 @@ Available document ids=
 
     return {
       type: 'link',
-      label: sidebarLabel || title,
+      label: sidebarLabel || item.label || title,
       href: permalink,
       customProps: item.customProps,
     };

packages/docusaurus-plugin-content-docs/src/sidebars.ts

@@ -118,12 +118,18 @@ function assertIsCategory(
 function assertIsDoc(
   item: Record<string, unknown>,
 ): asserts item is SidebarItemDoc {
-  assertItem(item, ['id', 'customProps']);
+  assertItem(item, ['id', 'label', 'customProps']);
   if (typeof item.id !== 'string') {
     throw new Error(
       `Error loading ${JSON.stringify(item)}. "id" must be a string.`,
     );
   }
+
+  if (item.label && typeof item.label !== 'string') {
+    throw new Error(
+      `Error loading ${JSON.stringify(item)}. "label" must be a string.`,
+    );
+  }
 }
 
 function assertIsLink(

packages/docusaurus-plugin-content-docs/src/types.ts

@@ -91,6 +91,7 @@ export type SidebarItemBase = {
 
 export type SidebarItemDoc = SidebarItemBase & {
   type: 'doc' | 'ref';
+  label?: string;
   id: string;
 };
 

website/docs/guides/docs/sidebar.md

@@ -128,6 +128,7 @@ type SidebarItemDoc =
   | {
       type: 'doc';
       id: string;
+      label: string; // Sidebar label text
     };
 ```
 
@@ -137,10 +138,11 @@ Example:
 {
   type: 'doc',
   id: 'doc1', // string - document id
+  label: 'Getting started' // Sidebar label text
 }
 ```
 
-Using just the [Document ID](#document-id) is also valid, the following is equivalent to the above:
+The `sidebar_label` in the markdown frontmatter has a higher precedence over the `label` key in `SidebarItemDoc`. Using just the [Document ID](#document-id) is also valid, the following is equivalent to the above:
 
 ```js
 'doc1'; // string - document id

website/docs/i18n/i18n-crowdin.mdx

@@ -1,7 +1,6 @@
 ---
 id: crowdin
 title: i18n - Using Crowdin
-sidebar_label: Using Crowdin
 slug: /i18n/crowdin
 ---
 

website/docs/i18n/i18n-git.md

@@ -1,7 +1,6 @@
 ---
 id: git
 title: i18n - Using git
-sidebar_label: Using Git
 slug: /i18n/git
 ---
 

website/docs/i18n/i18n-introduction.md

@@ -1,7 +1,6 @@
 ---
 id: introduction
 title: i18n - Introduction
-sidebar_label: Introduction
 slug: /i18n/introduction
 ---
 

website/docs/i18n/i18n-tutorial.md

@@ -1,7 +1,6 @@
 ---
 id: tutorial
 title: i18n - Tutorial
-sidebar_label: Tutorial
 slug: /i18n/tutorial
 ---
 

website/sidebars.js

@@ -57,10 +57,26 @@ module.exports = {
           type: 'category',
           label: 'Internationalization',
           items: [
-            'i18n/introduction',
-            'i18n/tutorial',
-            'i18n/git',
-            'i18n/crowdin',
+            {
+              type: 'doc',
+              id: 'i18n/introduction',
+              label: 'Introduction',
+            },
+            {
+              type: 'doc',
+              id: 'i18n/tutorial',
+              label: 'Tutorial',
+            },
+            {
+              type: 'doc',
+              id: 'i18n/git',
+              label: 'Using Git',
+            },
+            {
+              type: 'doc',
+              id: 'i18n/crowdin',
+              label: 'Using Crowdin',
+            },
           ],
         },
       ],