From 4348c6a990864204c44c81de83b898727595a2a1 Mon Sep 17 00:00:00 2001 From: Davide Donadio Date: Sat, 22 Oct 2022 14:26:52 +0000 Subject: [PATCH 01/10] feat: Introduced description to SidebarItemLink --- packages/docusaurus-plugin-content-docs/src/sidebars/types.ts | 2 ++ .../docusaurus-plugin-content-docs/src/sidebars/validation.ts | 3 +++ 2 files changed, 5 insertions(+) diff --git a/packages/docusaurus-plugin-content-docs/src/sidebars/types.ts b/packages/docusaurus-plugin-content-docs/src/sidebars/types.ts index 555004846ea4..a4b5c7a2aa7c 100644 --- a/packages/docusaurus-plugin-content-docs/src/sidebars/types.ts +++ b/packages/docusaurus-plugin-content-docs/src/sidebars/types.ts @@ -45,6 +45,7 @@ export type SidebarItemLink = SidebarItemBase & { href: string; label: string; autoAddBaseUrl?: boolean; + description?: string; }; export type SidebarItemAutogenerated = SidebarItemBase & { @@ -69,6 +70,7 @@ export type SidebarItemCategoryLinkGeneratedIndexConfig = { image?: string; keywords?: string | readonly string[]; }; + export type SidebarItemCategoryLinkGeneratedIndex = { type: 'generated-index'; slug: string; diff --git a/packages/docusaurus-plugin-content-docs/src/sidebars/validation.ts b/packages/docusaurus-plugin-content-docs/src/sidebars/validation.ts index 0273132360d1..990fba485e27 100644 --- a/packages/docusaurus-plugin-content-docs/src/sidebars/validation.ts +++ b/packages/docusaurus-plugin-content-docs/src/sidebars/validation.ts @@ -63,6 +63,9 @@ const sidebarItemLinkSchema = sidebarItemBaseSchema.append({ label: Joi.string() .required() .messages({'any.unknown': '"label" must be a string'}), + description: Joi.string().optional().messages({ + 'any.unknown': '"description" must be a string', + }), }); const sidebarItemCategoryLinkSchema = Joi.object() From fdd8c7350a2c2033f0a2562edc94b1b2d6ebdeb3 Mon Sep 17 00:00:00 2001 From: Davide Donadio Date: Sat, 22 Oct 2022 16:56:18 +0200 Subject: [PATCH 02/10] feat: managed to display description of External link in DocCard --- packages/docusaurus-theme-classic/src/theme/DocCard/index.tsx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/docusaurus-theme-classic/src/theme/DocCard/index.tsx b/packages/docusaurus-theme-classic/src/theme/DocCard/index.tsx index db0bda743570..56a9fd60339b 100644 --- a/packages/docusaurus-theme-classic/src/theme/DocCard/index.tsx +++ b/packages/docusaurus-theme-classic/src/theme/DocCard/index.tsx @@ -98,7 +98,7 @@ function CardCategory({ function CardLink({item}: {item: PropSidebarItemLink}): JSX.Element { const icon = isInternalUrl(item.href) ? '📄️' : '🔗'; - const doc = useDocById(item.docId ?? undefined); + const doc = isInternalUrl(item.href) ? useDocById(item.docId ?? undefined) : item; return ( Date: Sat, 22 Oct 2022 15:35:09 +0000 Subject: [PATCH 03/10] feat: added external link with description for dogfooding --- website/_dogfooding/docs-tests-sidebars.js | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/website/_dogfooding/docs-tests-sidebars.js b/website/_dogfooding/docs-tests-sidebars.js index d458e7eb517d..3adbd44f9a15 100644 --- a/website/_dogfooding/docs-tests-sidebars.js +++ b/website/_dogfooding/docs-tests-sidebars.js @@ -39,6 +39,12 @@ const sidebars = { label: 'External Link test', href: 'https://docusaurus.io', }, + { + type: 'link', + label: 'External Link with description', + href: 'https://docusaurus.io', + description: 'Some description', + }, ], }, { From 143999beab97eff4dc5e414095455963fe31be73 Mon Sep 17 00:00:00 2001 From: Davide Donadio Date: Sat, 22 Oct 2022 16:16:14 +0000 Subject: [PATCH 04/10] fix: solved problem related with react hooks executed conditionally --- .../docusaurus-theme-classic/src/theme/DocCard/index.tsx | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/packages/docusaurus-theme-classic/src/theme/DocCard/index.tsx b/packages/docusaurus-theme-classic/src/theme/DocCard/index.tsx index 56a9fd60339b..c9e912ed76ef 100644 --- a/packages/docusaurus-theme-classic/src/theme/DocCard/index.tsx +++ b/packages/docusaurus-theme-classic/src/theme/DocCard/index.tsx @@ -98,13 +98,15 @@ function CardCategory({ function CardLink({item}: {item: PropSidebarItemLink}): JSX.Element { const icon = isInternalUrl(item.href) ? '📄️' : '🔗'; - const doc = isInternalUrl(item.href) ? useDocById(item.docId ?? undefined) : item; + const doc = useDocById(item.docId ?? undefined); return ( ); } From dddb70f6f152e11bdf830812d971cdc727a6177d Mon Sep 17 00:00:00 2001 From: Davide Donadio Date: Mon, 24 Oct 2022 18:05:46 +0000 Subject: [PATCH 05/10] feat: Added chenges to categories --- .../docusaurus-plugin-content-docs/src/sidebars/types.ts | 7 ++++++- .../src/sidebars/validation.ts | 3 +++ .../docusaurus-theme-classic/src/theme/DocCard/index.tsx | 6 ++++-- 3 files changed, 13 insertions(+), 3 deletions(-) diff --git a/packages/docusaurus-plugin-content-docs/src/sidebars/types.ts b/packages/docusaurus-plugin-content-docs/src/sidebars/types.ts index a4b5c7a2aa7c..597f53439d64 100644 --- a/packages/docusaurus-plugin-content-docs/src/sidebars/types.ts +++ b/packages/docusaurus-plugin-content-docs/src/sidebars/types.ts @@ -60,7 +60,10 @@ type SidebarItemCategoryBase = SidebarItemBase & { collapsible: boolean; }; -export type SidebarItemCategoryLinkDoc = {type: 'doc'; id: string}; +export type SidebarItemCategoryLinkDoc = { + type: 'doc'; + id: string; +}; export type SidebarItemCategoryLinkGeneratedIndexConfig = { type: 'generated-index'; @@ -94,6 +97,7 @@ export type SidebarItemCategoryConfig = Expand< Optional & { items: SidebarCategoriesShorthand | SidebarItemConfig[]; link?: SidebarItemCategoryLinkConfig; + description?: string; } >; @@ -185,6 +189,7 @@ export type PropSidebarItemCategory = Expand< SidebarItemCategoryBase & { items: PropSidebarItem[]; href?: string; + description?: string; } >; diff --git a/packages/docusaurus-plugin-content-docs/src/sidebars/validation.ts b/packages/docusaurus-plugin-content-docs/src/sidebars/validation.ts index 990fba485e27..e65eb41960f3 100644 --- a/packages/docusaurus-plugin-content-docs/src/sidebars/validation.ts +++ b/packages/docusaurus-plugin-content-docs/src/sidebars/validation.ts @@ -119,6 +119,9 @@ const sidebarItemCategorySchema = collapsible: Joi.boolean().messages({ 'any.unknown': '"collapsible" must be a boolean', }), + description: Joi.string().optional().messages({ + 'any.unknown': '"description" must be a string', + }), }); const sidebarItemSchema = Joi.object().when('.type', { diff --git a/packages/docusaurus-theme-classic/src/theme/DocCard/index.tsx b/packages/docusaurus-theme-classic/src/theme/DocCard/index.tsx index c9e912ed76ef..ca3771b51940 100644 --- a/packages/docusaurus-theme-classic/src/theme/DocCard/index.tsx +++ b/packages/docusaurus-theme-classic/src/theme/DocCard/index.tsx @@ -78,6 +78,8 @@ function CardCategory({ return null; } + console.log(item); + return ( ); From 8000537d4678bdb2b8a12f04dee20cad2d31e36c Mon Sep 17 00:00:00 2001 From: Davide Donadio Date: Wed, 26 Oct 2022 07:36:30 +0000 Subject: [PATCH 06/10] fix: removed console log from DocCard --- packages/docusaurus-theme-classic/src/theme/DocCard/index.tsx | 2 -- 1 file changed, 2 deletions(-) diff --git a/packages/docusaurus-theme-classic/src/theme/DocCard/index.tsx b/packages/docusaurus-theme-classic/src/theme/DocCard/index.tsx index ca3771b51940..880b0c869334 100644 --- a/packages/docusaurus-theme-classic/src/theme/DocCard/index.tsx +++ b/packages/docusaurus-theme-classic/src/theme/DocCard/index.tsx @@ -78,8 +78,6 @@ function CardCategory({ return null; } - console.log(item); - return ( Date: Fri, 28 Oct 2022 09:37:44 +0000 Subject: [PATCH 07/10] fix: edit types and Card Doc based on suggestion on PR --- .../src/sidebars/types.ts | 3 +-- .../src/theme/DocCard/index.tsx | 25 ++++++++++--------- 2 files changed, 14 insertions(+), 14 deletions(-) diff --git a/packages/docusaurus-plugin-content-docs/src/sidebars/types.ts b/packages/docusaurus-plugin-content-docs/src/sidebars/types.ts index 597f53439d64..ffd0d5533a48 100644 --- a/packages/docusaurus-plugin-content-docs/src/sidebars/types.ts +++ b/packages/docusaurus-plugin-content-docs/src/sidebars/types.ts @@ -58,6 +58,7 @@ type SidebarItemCategoryBase = SidebarItemBase & { label: string; collapsed: boolean; collapsible: boolean; + description?: string; }; export type SidebarItemCategoryLinkDoc = { @@ -97,7 +98,6 @@ export type SidebarItemCategoryConfig = Expand< Optional & { items: SidebarCategoriesShorthand | SidebarItemConfig[]; link?: SidebarItemCategoryLinkConfig; - description?: string; } >; @@ -189,7 +189,6 @@ export type PropSidebarItemCategory = Expand< SidebarItemCategoryBase & { items: PropSidebarItem[]; href?: string; - description?: string; } >; diff --git a/packages/docusaurus-theme-classic/src/theme/DocCard/index.tsx b/packages/docusaurus-theme-classic/src/theme/DocCard/index.tsx index 880b0c869334..affb30a8a461 100644 --- a/packages/docusaurus-theme-classic/src/theme/DocCard/index.tsx +++ b/packages/docusaurus-theme-classic/src/theme/DocCard/index.tsx @@ -83,15 +83,18 @@ function CardCategory({ href={href} icon="🗃️" title={item.label} - description={translate( - { - message: '({count} items) {description}', - id: 'theme.docs.DocCard.categoryDescription', - description: - 'The default description for a category card in the generated index about how many items this category includes', - }, - {description: item.description ?? '', count: item.items.length}, - )} + description={ + item.description ?? + translate( + { + message: '{count} items', + id: 'theme.docs.DocCard.categoryDescription', + description: + 'The default description for a category card in the generated index about how many items this category includes', + }, + {count: item.items.length}, + ) + } /> ); } @@ -104,9 +107,7 @@ function CardLink({item}: {item: PropSidebarItemLink}): JSX.Element { href={item.href} icon={icon} title={item.label} - description={ - isInternalUrl(item.href) ? doc?.description : item.description - } + description={item.description ?? doc?.description} /> ); } From c8605c3d4617d6834c6df8506c2360936c7bdb6d Mon Sep 17 00:00:00 2001 From: sebastienlorber Date: Wed, 15 Mar 2023 19:34:48 +0100 Subject: [PATCH 08/10] add dogfood for link/category item description --- website/_dogfooding/docs-tests-sidebars.js | 45 ++++++++++++++++++++-- 1 file changed, 41 insertions(+), 4 deletions(-) diff --git a/website/_dogfooding/docs-tests-sidebars.js b/website/_dogfooding/docs-tests-sidebars.js index d9be38cc466b..c6f7ca8d5ba9 100644 --- a/website/_dogfooding/docs-tests-sidebars.js +++ b/website/_dogfooding/docs-tests-sidebars.js @@ -39,10 +39,47 @@ const sidebars = { href: 'https://docusaurus.io', }, { - type: 'link', - label: 'External Link with description', - href: 'https://docusaurus.io', - description: 'Some description', + type: 'category', + label: 'Sidebar item description tests', + link: { + type: 'generated-index', + }, + items: [ + { + type: 'link', + label: 'Link without description', + href: 'https://docusaurus.io', + }, + { + type: 'link', + label: 'Link with description', + href: 'https://docusaurus.io', + description: 'Some link description', + }, + { + type: 'category', + label: 'Category without description', + items: [ + { + type: 'link', + label: 'Link ', + href: 'https://docusaurus.io', + }, + ], + }, + { + type: 'category', + label: 'Category with description', + description: 'Some category description', + items: [ + { + type: 'link', + label: 'Link ', + href: 'https://docusaurus.io', + }, + ], + }, + ], }, ], }, From 6d6dee5f56b86ee97124351aeeb59470fdfb8ec6 Mon Sep 17 00:00:00 2001 From: sebastienlorber Date: Wed, 15 Mar 2023 19:40:42 +0100 Subject: [PATCH 09/10] reduce unneeded diff --- .../docusaurus-plugin-content-docs/src/sidebars/types.ts | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/packages/docusaurus-plugin-content-docs/src/sidebars/types.ts b/packages/docusaurus-plugin-content-docs/src/sidebars/types.ts index 6b23f9898d34..0aa9a4d5ff1b 100644 --- a/packages/docusaurus-plugin-content-docs/src/sidebars/types.ts +++ b/packages/docusaurus-plugin-content-docs/src/sidebars/types.ts @@ -61,10 +61,7 @@ type SidebarItemCategoryBase = SidebarItemBase & { description?: string; }; -export type SidebarItemCategoryLinkDoc = { - type: 'doc'; - id: string; -}; +export type SidebarItemCategoryLinkDoc = {type: 'doc'; id: string}; export type SidebarItemCategoryLinkGeneratedIndexConfig = { type: 'generated-index'; @@ -74,7 +71,6 @@ export type SidebarItemCategoryLinkGeneratedIndexConfig = { image?: string; keywords?: string | readonly string[]; }; - export type SidebarItemCategoryLinkGeneratedIndex = { type: 'generated-index'; slug: string; From d4b1431846055bd0bef7e084100d80122331ac54 Mon Sep 17 00:00:00 2001 From: sebastienlorber Date: Wed, 15 Mar 2023 19:53:15 +0100 Subject: [PATCH 10/10] add basic API docs --- website/docs/guides/docs/sidebar/items.mdx | 2 ++ website/docs/guides/docs/sidebar/multiple-sidebars.mdx | 2 +- 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/website/docs/guides/docs/sidebar/items.mdx b/website/docs/guides/docs/sidebar/items.mdx index b2793826f98b..1e358a12fee6 100644 --- a/website/docs/guides/docs/sidebar/items.mdx +++ b/website/docs/guides/docs/sidebar/items.mdx @@ -85,6 +85,7 @@ type SidebarItemLink = { label: string; href: string; className?: string; + description?: string; }; ``` @@ -173,6 +174,7 @@ type SidebarItemCategory = { label: string; // Sidebar label text. items: SidebarItem[]; // Array of sidebar items. className?: string; + description?: string; // Category options: collapsible: boolean; // Set the category to be collapsible diff --git a/website/docs/guides/docs/sidebar/multiple-sidebars.mdx b/website/docs/guides/docs/sidebar/multiple-sidebars.mdx index e90ba26a98ac..419a8fc57258 100644 --- a/website/docs/guides/docs/sidebar/multiple-sidebars.mdx +++ b/website/docs/guides/docs/sidebar/multiple-sidebars.mdx @@ -116,7 +116,7 @@ The pagination label by default is the sidebar label. You can use the front matt ## The `ref` item {#sidebar-item-ref} -The `ref` type is identical to the [`doc` type](#sidebar-item-doc) in every way, except that it doesn't participate in generating navigation metadata. It only registers itself as a link. When [generating pagination](#generating-pagination) and [displaying sidebar](#sidebar-association), `ref` items are completely ignored. +The `ref` type is identical to the [`doc` type](./items.mdx#sidebar-item-doc) in every way, except that it doesn't participate in generating navigation metadata. It only registers itself as a link. When [generating pagination](#generating-pagination) and [displaying sidebar](#sidebar-association), `ref` items are completely ignored. It is particularly useful where you wish to link to the same document from multiple sidebars. The document only belongs to one sidebar (the one where it's registered as `type: 'doc'` or from an autogenerated directory), but its link will appear in all sidebars that it's registered in.