From 53c6c8ed6ad9535fe90e754ee8f106a2983aafa9 Mon Sep 17 00:00:00 2001 From: bharateshwq Date: Sun, 21 Jul 2024 14:26:19 +0530 Subject: [PATCH 1/9] changed validation parameters and accepted description parameters from generators according to the requirement --- .../docusaurus-plugin-content-docs/src/sidebars/generator.ts | 1 + .../src/sidebars/postProcessor.ts | 5 +++++ .../docusaurus-plugin-content-docs/src/sidebars/types.ts | 1 + .../src/sidebars/validation.ts | 1 + .../docusaurus-theme-classic/src/theme/DocCard/index.tsx | 2 +- 5 files changed, 9 insertions(+), 1 deletion(-) diff --git a/packages/docusaurus-plugin-content-docs/src/sidebars/generator.ts b/packages/docusaurus-plugin-content-docs/src/sidebars/generator.ts index 0edf909bb9c8..d04fa770cdc1 100644 --- a/packages/docusaurus-plugin-content-docs/src/sidebars/generator.ts +++ b/packages/docusaurus-plugin-content-docs/src/sidebars/generator.ts @@ -239,6 +239,7 @@ Available doc IDs: return { type: 'category', label: categoryMetadata?.label ?? categoryLinkedDoc?.label ?? filename, + description: categoryMetadata?.description, collapsible: categoryMetadata?.collapsible, collapsed: categoryMetadata?.collapsed, position: diff --git a/packages/docusaurus-plugin-content-docs/src/sidebars/postProcessor.ts b/packages/docusaurus-plugin-content-docs/src/sidebars/postProcessor.ts index 3ec8a6f48124..61c3abec18ae 100644 --- a/packages/docusaurus-plugin-content-docs/src/sidebars/postProcessor.ts +++ b/packages/docusaurus-plugin-content-docs/src/sidebars/postProcessor.ts @@ -64,6 +64,11 @@ function postProcessSidebarItem( .map((subItem) => postProcessSidebarItem(subItem, params)) .filter((v): v is SidebarItem => Boolean(v)), }; + + if (item.description !== undefined) { + category.description = item.description; + } + // If the current category doesn't have subitems, we render a normal link // instead. if (category.items.length === 0) { diff --git a/packages/docusaurus-plugin-content-docs/src/sidebars/types.ts b/packages/docusaurus-plugin-content-docs/src/sidebars/types.ts index 555a2b471843..9dbd23415d3f 100644 --- a/packages/docusaurus-plugin-content-docs/src/sidebars/types.ts +++ b/packages/docusaurus-plugin-content-docs/src/sidebars/types.ts @@ -217,6 +217,7 @@ export type PropSidebarBreadcrumbsItem = export type CategoryMetadataFile = { label?: string; position?: number; + description?: string; collapsed?: boolean; collapsible?: boolean; className?: string; diff --git a/packages/docusaurus-plugin-content-docs/src/sidebars/validation.ts b/packages/docusaurus-plugin-content-docs/src/sidebars/validation.ts index e65eb41960f3..33492dc309c7 100644 --- a/packages/docusaurus-plugin-content-docs/src/sidebars/validation.ts +++ b/packages/docusaurus-plugin-content-docs/src/sidebars/validation.ts @@ -167,6 +167,7 @@ export function validateSidebars(sidebars: { const categoryMetadataFileSchema = Joi.object({ label: Joi.string(), + description: Joi.string(), position: Joi.number(), collapsed: Joi.boolean(), collapsible: Joi.boolean(), diff --git a/packages/docusaurus-theme-classic/src/theme/DocCard/index.tsx b/packages/docusaurus-theme-classic/src/theme/DocCard/index.tsx index 8348cf801459..4174ded6651b 100644 --- a/packages/docusaurus-theme-classic/src/theme/DocCard/index.tsx +++ b/packages/docusaurus-theme-classic/src/theme/DocCard/index.tsx @@ -67,7 +67,7 @@ function CardLayout({ href: string; icon: ReactNode; title: string; - description?: string; + description: string | undefined; }): JSX.Element { return ( From 5a8ebd3eba6fe1ecd71c8e8a1180f3241e8cfc21 Mon Sep 17 00:00:00 2001 From: bharateshwq Date: Sun, 21 Jul 2024 14:52:56 +0530 Subject: [PATCH 2/9] demonstration of the bugfix --- .../advanced/new-subcategory/_category_.json | 4 + website/docs/advanced/new-subcategory/doc1.md | 1 + website/docs/advanced/new-subcategory/doc2.md | 0 website/sidebars.ts | 148 +----------------- 4 files changed, 6 insertions(+), 147 deletions(-) create mode 100644 website/docs/advanced/new-subcategory/_category_.json create mode 100644 website/docs/advanced/new-subcategory/doc1.md create mode 100644 website/docs/advanced/new-subcategory/doc2.md diff --git a/website/docs/advanced/new-subcategory/_category_.json b/website/docs/advanced/new-subcategory/_category_.json new file mode 100644 index 000000000000..caca7bbaeebd --- /dev/null +++ b/website/docs/advanced/new-subcategory/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "this is a test title", + "description": "this is a test description" +} diff --git a/website/docs/advanced/new-subcategory/doc1.md b/website/docs/advanced/new-subcategory/doc1.md new file mode 100644 index 000000000000..33c96115baba --- /dev/null +++ b/website/docs/advanced/new-subcategory/doc1.md @@ -0,0 +1 @@ +#doc 1 diff --git a/website/docs/advanced/new-subcategory/doc2.md b/website/docs/advanced/new-subcategory/doc2.md new file mode 100644 index 000000000000..e69de29bb2d1 diff --git a/website/sidebars.ts b/website/sidebars.ts index 09ddffdb7784..089cd4917068 100644 --- a/website/sidebars.ts +++ b/website/sidebars.ts @@ -8,153 +8,7 @@ import type {SidebarsConfig} from '@docusaurus/plugin-content-docs'; const sidebars: SidebarsConfig = { - docs: [ - 'introduction', - { - type: 'category', - label: 'Getting Started', - link: { - type: 'generated-index', - }, - collapsed: false, - items: [ - 'installation', - 'configuration', - 'playground', - 'typescript-support', - ], - }, - { - type: 'category', - label: 'Guides', - link: { - type: 'generated-index', - title: 'Docusaurus Guides', - description: - "Let's learn about the most important Docusaurus concepts!", - keywords: ['guides'], - image: '/img/docusaurus.png', - }, - items: [ - 'guides/creating-pages', - { - type: 'category', - label: 'Docs', - link: { - type: 'doc', - id: 'guides/docs/introduction', - }, - items: [ - 'guides/docs/create-doc', - { - type: 'category', - label: 'Sidebar', - link: { - type: 'doc', - id: 'guides/docs/sidebar/index', - }, - items: [ - 'guides/docs/sidebar/items', - 'guides/docs/sidebar/autogenerated', - 'guides/docs/sidebar/multiple-sidebars', - ], - }, - 'guides/docs/versioning', - 'guides/docs/multi-instance', - ], - }, - 'blog', - { - type: 'category', - label: 'Markdown Features', - link: { - type: 'doc', - id: 'guides/markdown-features/introduction', - }, - items: [ - 'guides/markdown-features/react', - 'guides/markdown-features/tabs', - 'guides/markdown-features/code-blocks', - 'guides/markdown-features/admonitions', - 'guides/markdown-features/toc', - 'guides/markdown-features/assets', - 'guides/markdown-features/links', - 'guides/markdown-features/plugins', - 'guides/markdown-features/math-equations', - 'guides/markdown-features/diagrams', - 'guides/markdown-features/head-metadata', - ], - }, - 'styling-layout', - 'swizzling', - 'static-assets', - 'search', - 'browser-support', - 'seo', - 'using-plugins', - 'deployment', - { - type: 'category', - label: 'Internationalization', - link: {type: 'doc', id: 'i18n/introduction'}, - items: [ - { - type: 'doc', - id: 'i18n/tutorial', - label: 'Tutorial', - }, - { - type: 'doc', - id: 'i18n/git', - label: 'Using Git', - }, - { - type: 'doc', - id: 'i18n/crowdin', - label: 'Using Crowdin', - }, - ], - }, - 'guides/whats-next', - ], - }, - { - type: 'category', - label: 'Advanced Guides', - link: {type: 'doc', id: 'advanced/index'}, - items: [ - 'advanced/architecture', - 'advanced/plugins', - 'advanced/routing', - 'advanced/ssg', - 'advanced/client', - ], - }, - { - type: 'category', - label: 'Upgrading', - link: { - type: 'doc', - id: 'migration/index', - }, - items: [ - 'migration/v3', - // TODO do we want to keep upgrade docs for older Docusaurus versions? - // It contains links to docs of current version :/ - { - type: 'category', - label: 'To Docusaurus v2', - items: [ - 'migration/v2/migration-overview', - 'migration/v2/migration-automated', - 'migration/v2/migration-manual', - 'migration/v2/migration-versioned-sites', - 'migration/v2/migration-translated-sites', - ], - }, - ], - }, - ], + tutorialSidebar: [{type: 'autogenerated', dirName: '.'}], api: [ 'cli', 'docusaurus-core', From 03feca7e19c0b4326e172742910f879fc7eb7959 Mon Sep 17 00:00:00 2001 From: bharateshwq Date: Sun, 21 Jul 2024 15:05:19 +0530 Subject: [PATCH 3/9] final commit since the builds were failing --- .../advanced/new-subcategory/_category_.json | 4 - website/docs/advanced/new-subcategory/doc1.md | 1 - website/docs/advanced/new-subcategory/doc2.md | 0 website/sidebars.ts | 148 +++++++++++++++++- 4 files changed, 147 insertions(+), 6 deletions(-) delete mode 100644 website/docs/advanced/new-subcategory/_category_.json delete mode 100644 website/docs/advanced/new-subcategory/doc1.md delete mode 100644 website/docs/advanced/new-subcategory/doc2.md diff --git a/website/docs/advanced/new-subcategory/_category_.json b/website/docs/advanced/new-subcategory/_category_.json deleted file mode 100644 index caca7bbaeebd..000000000000 --- a/website/docs/advanced/new-subcategory/_category_.json +++ /dev/null @@ -1,4 +0,0 @@ -{ - "label": "this is a test title", - "description": "this is a test description" -} diff --git a/website/docs/advanced/new-subcategory/doc1.md b/website/docs/advanced/new-subcategory/doc1.md deleted file mode 100644 index 33c96115baba..000000000000 --- a/website/docs/advanced/new-subcategory/doc1.md +++ /dev/null @@ -1 +0,0 @@ -#doc 1 diff --git a/website/docs/advanced/new-subcategory/doc2.md b/website/docs/advanced/new-subcategory/doc2.md deleted file mode 100644 index e69de29bb2d1..000000000000 diff --git a/website/sidebars.ts b/website/sidebars.ts index 089cd4917068..09ddffdb7784 100644 --- a/website/sidebars.ts +++ b/website/sidebars.ts @@ -8,7 +8,153 @@ import type {SidebarsConfig} from '@docusaurus/plugin-content-docs'; const sidebars: SidebarsConfig = { - tutorialSidebar: [{type: 'autogenerated', dirName: '.'}], + docs: [ + 'introduction', + { + type: 'category', + label: 'Getting Started', + link: { + type: 'generated-index', + }, + collapsed: false, + items: [ + 'installation', + 'configuration', + 'playground', + 'typescript-support', + ], + }, + { + type: 'category', + label: 'Guides', + link: { + type: 'generated-index', + title: 'Docusaurus Guides', + description: + "Let's learn about the most important Docusaurus concepts!", + keywords: ['guides'], + image: '/img/docusaurus.png', + }, + items: [ + 'guides/creating-pages', + { + type: 'category', + label: 'Docs', + link: { + type: 'doc', + id: 'guides/docs/introduction', + }, + items: [ + 'guides/docs/create-doc', + { + type: 'category', + label: 'Sidebar', + link: { + type: 'doc', + id: 'guides/docs/sidebar/index', + }, + items: [ + 'guides/docs/sidebar/items', + 'guides/docs/sidebar/autogenerated', + 'guides/docs/sidebar/multiple-sidebars', + ], + }, + 'guides/docs/versioning', + 'guides/docs/multi-instance', + ], + }, + 'blog', + { + type: 'category', + label: 'Markdown Features', + link: { + type: 'doc', + id: 'guides/markdown-features/introduction', + }, + items: [ + 'guides/markdown-features/react', + 'guides/markdown-features/tabs', + 'guides/markdown-features/code-blocks', + 'guides/markdown-features/admonitions', + 'guides/markdown-features/toc', + 'guides/markdown-features/assets', + 'guides/markdown-features/links', + 'guides/markdown-features/plugins', + 'guides/markdown-features/math-equations', + 'guides/markdown-features/diagrams', + 'guides/markdown-features/head-metadata', + ], + }, + 'styling-layout', + 'swizzling', + 'static-assets', + 'search', + 'browser-support', + 'seo', + 'using-plugins', + 'deployment', + { + type: 'category', + label: 'Internationalization', + link: {type: 'doc', id: 'i18n/introduction'}, + items: [ + { + type: 'doc', + id: 'i18n/tutorial', + label: 'Tutorial', + }, + { + type: 'doc', + id: 'i18n/git', + label: 'Using Git', + }, + { + type: 'doc', + id: 'i18n/crowdin', + label: 'Using Crowdin', + }, + ], + }, + 'guides/whats-next', + ], + }, + { + type: 'category', + label: 'Advanced Guides', + link: {type: 'doc', id: 'advanced/index'}, + items: [ + 'advanced/architecture', + 'advanced/plugins', + 'advanced/routing', + 'advanced/ssg', + 'advanced/client', + ], + }, + { + type: 'category', + label: 'Upgrading', + link: { + type: 'doc', + id: 'migration/index', + }, + items: [ + 'migration/v3', + // TODO do we want to keep upgrade docs for older Docusaurus versions? + // It contains links to docs of current version :/ + { + type: 'category', + label: 'To Docusaurus v2', + items: [ + 'migration/v2/migration-overview', + 'migration/v2/migration-automated', + 'migration/v2/migration-manual', + 'migration/v2/migration-versioned-sites', + 'migration/v2/migration-translated-sites', + ], + }, + ], + }, + ], api: [ 'cli', 'docusaurus-core', From 7cdbfd2c7d826826e2ad71188922964e05b179d8 Mon Sep 17 00:00:00 2001 From: sebastien Date: Fri, 9 Aug 2024 10:59:46 +0200 Subject: [PATCH 4/9] add dogfood test case --- .../_dogfooding/_docs tests/tests/category-links/_category_.json | 1 + 1 file changed, 1 insertion(+) diff --git a/website/_dogfooding/_docs tests/tests/category-links/_category_.json b/website/_dogfooding/_docs tests/tests/category-links/_category_.json index 8d0c8da76ae0..7166d0a75525 100644 --- a/website/_dogfooding/_docs tests/tests/category-links/_category_.json +++ b/website/_dogfooding/_docs tests/tests/category-links/_category_.json @@ -1,5 +1,6 @@ { "label": "Category Links", + "description": "Category Links - Custom Description", "link": { "type": "generated-index", "slug": "/category-links-generated-index-slug" From 2e0b1f3c6ced3644fbe981dd0e271aa074bc7234 Mon Sep 17 00:00:00 2001 From: sebastien Date: Fri, 9 Aug 2024 11:09:48 +0200 Subject: [PATCH 5/9] add dogfood test case --- website/_dogfooding/docs-tests-sidebars.js | 1 + 1 file changed, 1 insertion(+) diff --git a/website/_dogfooding/docs-tests-sidebars.js b/website/_dogfooding/docs-tests-sidebars.js index c6f7ca8d5ba9..1e37a44d7c90 100644 --- a/website/_dogfooding/docs-tests-sidebars.js +++ b/website/_dogfooding/docs-tests-sidebars.js @@ -41,6 +41,7 @@ const sidebars = { { type: 'category', label: 'Sidebar item description tests', + description: 'Some custom category description', link: { type: 'generated-index', }, From 37a7742a538d2f5b5be130ecb4db89bf65cbbe6e Mon Sep 17 00:00:00 2001 From: sebastien Date: Fri, 9 Aug 2024 11:09:55 +0200 Subject: [PATCH 6/9] add validation test --- .../src/sidebars/__tests__/validation.test.ts | 1 + 1 file changed, 1 insertion(+) diff --git a/packages/docusaurus-plugin-content-docs/src/sidebars/__tests__/validation.test.ts b/packages/docusaurus-plugin-content-docs/src/sidebars/__tests__/validation.test.ts index 8186601285a0..6620705ff712 100644 --- a/packages/docusaurus-plugin-content-docs/src/sidebars/__tests__/validation.test.ts +++ b/packages/docusaurus-plugin-content-docs/src/sidebars/__tests__/validation.test.ts @@ -282,6 +282,7 @@ describe('validateCategoryMetadataFile', () => { const content: CategoryMetadataFile = { className: 'className', label: 'Category Label', + description: 'Category Description', link: { type: 'generated-index', slug: 'slug', From 326b30cb340e42366893ce5ec8952bbb4394f4b1 Mon Sep 17 00:00:00 2001 From: sebastien Date: Fri, 9 Aug 2024 11:10:01 +0200 Subject: [PATCH 7/9] remove useless code --- .../src/sidebars/postProcessor.ts | 4 ---- 1 file changed, 4 deletions(-) diff --git a/packages/docusaurus-plugin-content-docs/src/sidebars/postProcessor.ts b/packages/docusaurus-plugin-content-docs/src/sidebars/postProcessor.ts index 61c3abec18ae..b5cdc34aa913 100644 --- a/packages/docusaurus-plugin-content-docs/src/sidebars/postProcessor.ts +++ b/packages/docusaurus-plugin-content-docs/src/sidebars/postProcessor.ts @@ -65,10 +65,6 @@ function postProcessSidebarItem( .filter((v): v is SidebarItem => Boolean(v)), }; - if (item.description !== undefined) { - category.description = item.description; - } - // If the current category doesn't have subitems, we render a normal link // instead. if (category.items.length === 0) { From 6c31f42a30314f21b807cf9f0b69c1589006f392 Mon Sep 17 00:00:00 2001 From: sebastien Date: Fri, 9 Aug 2024 11:14:41 +0200 Subject: [PATCH 8/9] polish --- .../docusaurus-plugin-content-docs/src/sidebars/generator.ts | 4 +++- packages/docusaurus-theme-classic/src/theme/DocCard/index.tsx | 2 +- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/packages/docusaurus-plugin-content-docs/src/sidebars/generator.ts b/packages/docusaurus-plugin-content-docs/src/sidebars/generator.ts index d04fa770cdc1..20383b003ac8 100644 --- a/packages/docusaurus-plugin-content-docs/src/sidebars/generator.ts +++ b/packages/docusaurus-plugin-content-docs/src/sidebars/generator.ts @@ -239,7 +239,6 @@ Available doc IDs: return { type: 'category', label: categoryMetadata?.label ?? categoryLinkedDoc?.label ?? filename, - description: categoryMetadata?.description, collapsible: categoryMetadata?.collapsible, collapsed: categoryMetadata?.collapsed, position: @@ -250,6 +249,9 @@ Available doc IDs: ...(customProps !== undefined && {customProps}), ...(className !== undefined && {className}), items, + ...(categoryMetadata?.description && { + description: categoryMetadata?.description, + }), ...(link && {link}), }; } diff --git a/packages/docusaurus-theme-classic/src/theme/DocCard/index.tsx b/packages/docusaurus-theme-classic/src/theme/DocCard/index.tsx index 4174ded6651b..8348cf801459 100644 --- a/packages/docusaurus-theme-classic/src/theme/DocCard/index.tsx +++ b/packages/docusaurus-theme-classic/src/theme/DocCard/index.tsx @@ -67,7 +67,7 @@ function CardLayout({ href: string; icon: ReactNode; title: string; - description: string | undefined; + description?: string; }): JSX.Element { return ( From 95d31e0f2d87e8ef25b21a12040c294a7669ca76 Mon Sep 17 00:00:00 2001 From: sebastien Date: Fri, 9 Aug 2024 11:22:41 +0200 Subject: [PATCH 9/9] add _category_ description to unit test snapshot --- .../src/sidebars/__tests__/__snapshots__/generator.test.ts.snap | 1 + .../src/sidebars/__tests__/generator.test.ts | 1 + 2 files changed, 2 insertions(+) diff --git a/packages/docusaurus-plugin-content-docs/src/sidebars/__tests__/__snapshots__/generator.test.ts.snap b/packages/docusaurus-plugin-content-docs/src/sidebars/__tests__/__snapshots__/generator.test.ts.snap index 29dd570e2366..63430fd3632c 100644 --- a/packages/docusaurus-plugin-content-docs/src/sidebars/__tests__/__snapshots__/generator.test.ts.snap +++ b/packages/docusaurus-plugin-content-docs/src/sidebars/__tests__/__snapshots__/generator.test.ts.snap @@ -217,6 +217,7 @@ exports[`DefaultSidebarItemsGenerator uses explicit link over the index/readme.{ { "collapsed": undefined, "collapsible": undefined, + "description": "Category description", "items": [ { "id": "parent/doc2", diff --git a/packages/docusaurus-plugin-content-docs/src/sidebars/__tests__/generator.test.ts b/packages/docusaurus-plugin-content-docs/src/sidebars/__tests__/generator.test.ts index 2bb401457537..de104a1a254a 100644 --- a/packages/docusaurus-plugin-content-docs/src/sidebars/__tests__/generator.test.ts +++ b/packages/docusaurus-plugin-content-docs/src/sidebars/__tests__/generator.test.ts @@ -331,6 +331,7 @@ describe('DefaultSidebarItemsGenerator', () => { categoriesMetadata: { Category: { label: 'Category label', + description: 'Category description', link: { type: 'doc', id: 'doc3', // Using a "local doc id" ("doc1" instead of "parent/doc1") on purpose