From 9715048f795c0b9b3432b8721f7572fc690aa798 Mon Sep 17 00:00:00 2001 From: besemuna <51783214+besemuna@users.noreply.github.com> Date: Fri, 26 Mar 2021 14:11:21 +0000 Subject: [PATCH] feat(v2): provide doc sidebar_label through sidebars.js (#4500) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * 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 * docs : remove backported docs Co-authored-by: Lisa Chandra <52909743+lisa761@users.noreply.github.com> Co-authored-by: Javid Co-authored-by: Sébastien Lorber --- .../site-with-doc-label/docs/hello-1.md | 7 ++++ .../site-with-doc-label/docs/hello-2.md | 8 +++++ .../site-with-doc-label/docusaurus.config.js | 14 ++++++++ .../site-with-doc-label/sidebars.json | 14 ++++++++ .../src/__tests__/index.test.ts | 36 +++++++++++++++++++ .../src/props.ts | 2 +- .../src/sidebars.ts | 8 ++++- .../src/types.ts | 1 + website/docs/guides/docs/sidebar.md | 4 ++- website/docs/i18n/i18n-crowdin.mdx | 1 - website/docs/i18n/i18n-git.md | 1 - website/docs/i18n/i18n-introduction.md | 1 - website/docs/i18n/i18n-tutorial.md | 1 - website/sidebars.js | 24 ++++++++++--- 14 files changed, 111 insertions(+), 11 deletions(-) create mode 100644 packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/site-with-doc-label/docs/hello-1.md create mode 100644 packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/site-with-doc-label/docs/hello-2.md create mode 100644 packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/site-with-doc-label/docusaurus.config.js create mode 100644 packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/site-with-doc-label/sidebars.json diff --git a/packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/site-with-doc-label/docs/hello-1.md b/packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/site-with-doc-label/docs/hello-1.md new file mode 100644 index 0000000000..88f42926c1 --- /dev/null +++ b/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! + diff --git a/packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/site-with-doc-label/docs/hello-2.md b/packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/site-with-doc-label/docs/hello-2.md new file mode 100644 index 0000000000..f137c9d8d0 --- /dev/null +++ b/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! + diff --git a/packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/site-with-doc-label/docusaurus.config.js b/packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/site-with-doc-label/docusaurus.config.js new file mode 100644 index 0000000000..6fa02ca102 --- /dev/null +++ b/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', +}; diff --git a/packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/site-with-doc-label/sidebars.json b/packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/site-with-doc-label/sidebars.json new file mode 100644 index 0000000000..081ece926c --- /dev/null +++ b/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" + } + ] +} diff --git a/packages/docusaurus-plugin-content-docs/src/__tests__/index.test.ts b/packages/docusaurus-plugin-content-docs/src/__tests__/index.test.ts index 87dba280cb..18e34dd4b8 100644 --- a/packages/docusaurus-plugin-content-docs/src/__tests__/index.test.ts +++ b/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'); + }); +}); diff --git a/packages/docusaurus-plugin-content-docs/src/props.ts b/packages/docusaurus-plugin-content-docs/src/props.ts index 994fe17013..2e7781daa8 100644 --- a/packages/docusaurus-plugin-content-docs/src/props.ts +++ b/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, }; diff --git a/packages/docusaurus-plugin-content-docs/src/sidebars.ts b/packages/docusaurus-plugin-content-docs/src/sidebars.ts index 1d98ddc92f..0f4758d78c 100644 --- a/packages/docusaurus-plugin-content-docs/src/sidebars.ts +++ b/packages/docusaurus-plugin-content-docs/src/sidebars.ts @@ -118,12 +118,18 @@ function assertIsCategory( function assertIsDoc( item: Record, ): 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( diff --git a/packages/docusaurus-plugin-content-docs/src/types.ts b/packages/docusaurus-plugin-content-docs/src/types.ts index 7fb0f50c22..022efda0d2 100644 --- a/packages/docusaurus-plugin-content-docs/src/types.ts +++ b/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; }; diff --git a/website/docs/guides/docs/sidebar.md b/website/docs/guides/docs/sidebar.md index 832e4699c1..ec68bd3ca8 100644 --- a/website/docs/guides/docs/sidebar.md +++ b/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 diff --git a/website/docs/i18n/i18n-crowdin.mdx b/website/docs/i18n/i18n-crowdin.mdx index 1543713e82..9cd55af1d4 100644 --- a/website/docs/i18n/i18n-crowdin.mdx +++ b/website/docs/i18n/i18n-crowdin.mdx @@ -1,7 +1,6 @@ --- id: crowdin title: i18n - Using Crowdin -sidebar_label: Using Crowdin slug: /i18n/crowdin --- diff --git a/website/docs/i18n/i18n-git.md b/website/docs/i18n/i18n-git.md index 463bd41a47..9635734f49 100644 --- a/website/docs/i18n/i18n-git.md +++ b/website/docs/i18n/i18n-git.md @@ -1,7 +1,6 @@ --- id: git title: i18n - Using git -sidebar_label: Using Git slug: /i18n/git --- diff --git a/website/docs/i18n/i18n-introduction.md b/website/docs/i18n/i18n-introduction.md index 7cca601753..cb45e8f325 100644 --- a/website/docs/i18n/i18n-introduction.md +++ b/website/docs/i18n/i18n-introduction.md @@ -1,7 +1,6 @@ --- id: introduction title: i18n - Introduction -sidebar_label: Introduction slug: /i18n/introduction --- diff --git a/website/docs/i18n/i18n-tutorial.md b/website/docs/i18n/i18n-tutorial.md index 526acdf338..fba9409e30 100644 --- a/website/docs/i18n/i18n-tutorial.md +++ b/website/docs/i18n/i18n-tutorial.md @@ -1,7 +1,6 @@ --- id: tutorial title: i18n - Tutorial -sidebar_label: Tutorial slug: /i18n/tutorial --- diff --git a/website/sidebars.js b/website/sidebars.js index 24461ff0cd..267fcb7abc 100644 --- a/website/sidebars.js +++ b/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', + }, ], }, ],