fix(v2): sidebar_label should be used to compute next/previous button labels (#4970)

* sidebar_label should be used to compute next/previous button texts, as documented.

* improve docs frontmatter doc

* use a little bit of destructuring

packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/simple-site/docs/hello.md

@@ -1,6 +1,7 @@
 ---
 id: hello
 title: Hello, World !
+sidebar_label: Hello sidebar_label
 ---
 
 Hi, Endilie here :)

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

@@ -208,7 +208,7 @@ Object {
     \\"permalink\\": \\"/docs/foo/bar\\"
   },
   \\"next\\": {
-    \\"title\\": \\"Hello, World !\\",
+    \\"title\\": \\"Hello sidebar_label\\",
     \\"permalink\\": \\"/docs/\\"
   }
 }",
@@ -238,7 +238,8 @@ Object {
   \\"version\\": \\"current\\",
   \\"frontMatter\\": {
     \\"id\\": \\"hello\\",
-    \\"title\\": \\"Hello, World !\\"
+    \\"title\\": \\"Hello, World !\\",
+    \\"sidebar_label\\": \\"Hello sidebar_label\\"
   },
   \\"sidebar\\": \\"docs\\",
   \\"previous\\": {
@@ -435,7 +436,7 @@ Object {
           },
           {
             \\"type\\": \\"link\\",
-            \\"label\\": \\"Hello, World !\\",
+            \\"label\\": \\"Hello sidebar_label\\",
             \\"href\\": \\"/docs/\\"
           }
         ]
@@ -447,7 +448,7 @@ Object {
         \\"items\\": [
           {
             \\"type\\": \\"link\\",
-            \\"label\\": \\"Hello, World !\\",
+            \\"label\\": \\"Hello sidebar_label\\",
             \\"href\\": \\"/docs/\\"
           }
         ]

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

@@ -201,6 +201,7 @@ describe('simple site', () => {
       frontMatter: {
         id: 'hello',
         title: 'Hello, World !',
+        sidebar_label: 'Hello sidebar_label',
       },
     });
   });
@@ -230,6 +231,7 @@ describe('simple site', () => {
       frontMatter: {
         id: 'hello',
         title: 'Hello, World !',
+        sidebar_label: 'Hello sidebar_label',
       },
     });
   });

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

@@ -328,6 +328,39 @@ describe('simple website', () => {
     expect(content.loadedVersions.length).toEqual(1);
     const [currentVersion] = content.loadedVersions;
 
+    expect(findDocById(currentVersion, 'foo/baz')).toEqual({
+      ...defaultDocMetadata,
+      version: 'current',
+      id: 'foo/baz',
+      unversionedId: 'foo/baz',
+      sourceDirName: 'foo',
+      isDocsHomePage: false,
+      permalink: '/docs/foo/bazSlug.html',
+      slug: '/foo/bazSlug.html',
+      previous: {
+        title: 'Bar',
+        permalink: '/docs/foo/bar',
+      },
+      next: {
+        title: 'Hello sidebar_label',
+        permalink: '/docs/',
+      },
+      sidebar: 'docs',
+      source: path.posix.join(
+        '@site',
+        posixPath(path.relative(siteDir, currentVersion.contentPath)),
+        'foo',
+        'baz.md',
+      ),
+      title: 'baz',
+      description: 'Images',
+      frontMatter: {
+        id: 'baz',
+        title: 'baz',
+        slug: 'bazSlug.html',
+      },
+    });
+
     expect(findDocById(currentVersion, 'hello')).toEqual({
       ...defaultDocMetadata,
       version: 'current',
@@ -352,6 +385,7 @@ describe('simple website', () => {
       frontMatter: {
         id: 'hello',
         title: 'Hello, World !',
+        sidebar_label: 'Hello sidebar_label',
       },
     });
 

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

@@ -11,21 +11,7 @@ import {
   JoiFrontMatter as Joi, // Custom instance for frontmatter
   validateFrontMatter,
 } from '@docusaurus/utils-validation';
-
-export type DocFrontMatter = {
-  id?: string;
-  title?: string;
-  hide_title?: boolean;
-  hide_table_of_contents?: boolean;
-  keywords?: string[];
-  image?: string;
-  description?: string;
-  slug?: string;
-  sidebar_label?: string;
-  sidebar_position?: number;
-  custom_edit_url?: string | null;
-  parse_number_prefixes?: boolean;
-};
+import {DocFrontMatter} from './types';
 
 // NOTE: we don't add any default value on purpose here
 // We don't want default values to magically appear in doc metadatas and props

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

@@ -198,10 +198,13 @@ export default function pluginContentDocs(
             previousId,
             nextId,
           } = sidebarsUtils.getDocNavigation(doc.id);
-          const toDocNavLink = (navDocId: string): DocNavLink => ({
-            title: docsBaseById[navDocId].title,
-            permalink: docsBaseById[navDocId].permalink,
-          });
+          const toDocNavLink = (navDocId: string): DocNavLink => {
+            const {title, permalink, frontMatter} = docsBaseById[navDocId];
+            return {
+              title: frontMatter.sidebar_label ?? title,
+              permalink,
+            };
+          };
           return {
             ...doc,
             sidebar: sidebarName,

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

@@ -181,9 +181,19 @@ export type LastUpdateData = {
   lastUpdatedBy?: string;
 };
 
-export type FrontMatter = {
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  [key: string]: any;
+export type DocFrontMatter = {
+  id?: string;
+  title?: string;
+  hide_title?: boolean;
+  hide_table_of_contents?: boolean;
+  keywords?: string[];
+  image?: string;
+  description?: string;
+  slug?: string;
+  sidebar_label?: string;
+  sidebar_position?: number;
+  custom_edit_url?: string | null;
+  parse_number_prefixes?: boolean;
 };
 
 export type DocMetadataBase = LastUpdateData & {
@@ -200,7 +210,7 @@ export type DocMetadataBase = LastUpdateData & {
   // eslint-disable-next-line camelcase
   sidebarPosition?: number;
   editUrl?: string | null;
-  frontMatter: FrontMatter;
+  frontMatter: DocFrontMatter & Record<string, unknown>;
 };
 
 export type DocNavLink = {

website/docs/api/plugins/plugin-content-docs.md

@@ -193,20 +193,20 @@ module.exports = {
 
 ## Markdown Frontmatter {#markdown-frontmatter}
 
-Markdown documents can use the following markdown frontmatter metadata fields, enclosed by a line `---` on either side:
+Markdown documents can use the following Markdown FrontMatter metadata fields, enclosed by a line `---` on either side:
 
-- `id`: A unique document id. If this field is not present, the document's `id` will default to its file name (without the extension)
-- `title`: The title of your document. If this field is not present, the document's `title` will default to its `id`
-- `hide_title`: Whether to hide the title at the top of the doc. It only hides a title declared through the frontmatter, and have no effect on a title at the top of your Markdown document. By default, it is `false`
-- `hide_table_of_contents`: Whether to hide the table of contents to the right. By default it is `false`
-- `sidebar_label`: The text shown in the document sidebar and in the next/previous button for this document. If this field is not present, the document's `sidebar_label` will default to its `title`
+- `id`: A unique document id. Default value: file path (including folders, without the extension)
+- `title`: The text title of your document. Used for the page metadata and as a fallback value in multiple places (sidebar, next/previous buttons...). Automatically added at the top of your doc if it does not contain any Markdown title. Default value: Markdown title or doc `id`
+- `hide_title`: Whether to hide the title at the top of the doc. It only hides a title declared through the frontmatter, and have no effect on a Markdown title at the top of your document. Default value: `false`
+- `hide_table_of_contents`: Whether to hide the table of contents to the right. Default value: `false`
+- `sidebar_label`: The text shown in the document sidebar and in the next/previous button for this document. Default value: doc `title`
 - `sidebar_position`: Permits to control the position of a doc inside the generated sidebar slice, when using `autogenerated` sidebar items. Can be Int or Float.
-- `parse_number_prefixes`: When a document has a number prefix (`001 - My Doc.md`, `2. MyDoc.md`...), it is automatically parsed and extracted by the plugin `numberPrefixParser`, and the number prefix is used as `sidebar_position`. Use `parse_number_prefixes: false` to disable number prefix parsing on this doc
-- `custom_edit_url`: The URL for editing this document. If this field is not present, the document's edit URL will fall back to `editUrl` from options fields passed to `docusaurus-plugin-content-docs`
+- `parse_number_prefixes`: When a document has a number prefix (`001 - My Doc.md`, `2. MyDoc.md`...), it is automatically parsed and extracted by the plugin `numberPrefixParser`, and the number prefix is used as `sidebar_position`. Use `parse_number_prefixes: false` to disable number prefix parsing on this doc. Default value: `parse_number_prefixes` plugin option
+- `custom_edit_url`: The URL for editing this document. Default value: computed using the `editUrl` plugin options
 - `keywords`: Keywords meta tag for the document page, for search engines
-- `description`: The description of your document, which will become the `<meta name="description" content="..."/>` and `<meta property="og:description" content="..."/>` in `<head>`, used by search engines. If this field is not present, it will default to the first line of the contents
-- `image`: Cover or thumbnail image that will be used when displaying the link to your post
-- `slug`: Allows to customize the document url (`/<routeBasePath>/<slug>`). Support multiple patterns: `slug: my-doc`, `slug: /my/path/myDoc`, `slug: /`
+- `description`: The description of your document, which will become the `<meta name="description" content="..."/>` and `<meta property="og:description" content="..."/>` in `<head>`, used by search engines. Default value: the first line of Markdown content
+- `image`: Cover or thumbnail image that will be used when displaying the link to your post.
+- `slug`: Allows to customize the document url (`/<routeBasePath>/<slug>`). Support multiple patterns: `slug: my-doc`, `slug: /my/path/myDoc`, `slug: /`.
 
 Example: