refactor(content-{blog,docs}): unify handling of tags (#7117)

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

@@ -714,9 +714,11 @@ exports[`simple website content: data 1`] = `
   }
 }",
   "tag-docs-tags-tag-1-b3f.json": "{
-  \\"name\\": \\"tag 1\\",
+  \\"label\\": \\"tag 1\\",
   \\"permalink\\": \\"/docs/tags/tag-1\\",
-  \\"docs\\": [
+  \\"allTagsPath\\": \\"/docs/tags\\",
+  \\"count\\": 2,
+  \\"items\\": [
     {
       \\"id\\": \\"foo/baz\\",
       \\"title\\": \\"baz\\",
@@ -729,48 +731,49 @@ exports[`simple website content: data 1`] = `
       \\"description\\": \\"Hi, Endilie here :)\\",
       \\"permalink\\": \\"/docs/\\"
     }
-  ],
-  \\"allTagsPath\\": \\"/docs/tags\\"
+  ]
 }",
   "tag-docs-tags-tag-2-custom-permalink-825.json": "{
-  \\"name\\": \\"tag 2\\",
+  \\"label\\": \\"tag 2\\",
   \\"permalink\\": \\"/docs/tags/tag2-custom-permalink\\",
-  \\"docs\\": [
+  \\"allTagsPath\\": \\"/docs/tags\\",
+  \\"count\\": 1,
+  \\"items\\": [
     {
       \\"id\\": \\"foo/baz\\",
       \\"title\\": \\"baz\\",
       \\"description\\": \\"Images\\",
       \\"permalink\\": \\"/docs/foo/bazSlug.html\\"
     }
-  ],
-  \\"allTagsPath\\": \\"/docs/tags\\"
+  ]
 }",
   "tag-docs-tags-tag-3-ab5.json": "{
-  \\"name\\": \\"tag 3\\",
+  \\"label\\": \\"tag 3\\",
   \\"permalink\\": \\"/docs/tags/tag-3\\",
-  \\"docs\\": [
+  \\"allTagsPath\\": \\"/docs/tags\\",
+  \\"count\\": 1,
+  \\"items\\": [
     {
       \\"id\\": \\"hello\\",
       \\"title\\": \\"Hello, World !\\",
       \\"description\\": \\"Hi, Endilie here :)\\",
       \\"permalink\\": \\"/docs/\\"
     }
-  ],
-  \\"allTagsPath\\": \\"/docs/tags\\"
+  ]
 }",
   "tags-list-current-prop-15a.json": "[
   {
-    \\"name\\": \\"tag 1\\",
+    \\"label\\": \\"tag 1\\",
     \\"permalink\\": \\"/docs/tags/tag-1\\",
     \\"count\\": 2
   },
   {
-    \\"name\\": \\"tag 2\\",
+    \\"label\\": \\"tag 2\\",
     \\"permalink\\": \\"/docs/tags/tag2-custom-permalink\\",
     \\"count\\": 1
   },
   {
-    \\"name\\": \\"tag 3\\",
+    \\"label\\": \\"tag 3\\",
     \\"permalink\\": \\"/docs/tags/tag-3\\",
     \\"count\\": 1
   }
@@ -3172,57 +3175,60 @@ exports[`versioned website content: data 1`] = `
   }
 }",
   "tag-docs-next-tags-bar-tag-1-a8f.json": "{
-  \\"name\\": \\"barTag 1\\",
+  \\"label\\": \\"barTag 1\\",
   \\"permalink\\": \\"/docs/next/tags/bar-tag-1\\",
-  \\"docs\\": [
+  \\"allTagsPath\\": \\"/docs/next/tags\\",
+  \\"count\\": 1,
+  \\"items\\": [
     {
       \\"id\\": \\"foo/bar\\",
       \\"title\\": \\"bar\\",
       \\"description\\": \\"This is next version of bar.\\",
       \\"permalink\\": \\"/docs/next/foo/barSlug\\"
     }
-  ],
-  \\"allTagsPath\\": \\"/docs/next/tags\\"
+  ]
 }",
   "tag-docs-next-tags-bar-tag-2-216.json": "{
-  \\"name\\": \\"barTag-2\\",
+  \\"label\\": \\"barTag-2\\",
   \\"permalink\\": \\"/docs/next/tags/bar-tag-2\\",
-  \\"docs\\": [
+  \\"allTagsPath\\": \\"/docs/next/tags\\",
+  \\"count\\": 1,
+  \\"items\\": [
     {
       \\"id\\": \\"foo/bar\\",
       \\"title\\": \\"bar\\",
       \\"description\\": \\"This is next version of bar.\\",
       \\"permalink\\": \\"/docs/next/foo/barSlug\\"
     }
-  ],
-  \\"allTagsPath\\": \\"/docs/next/tags\\"
+  ]
 }",
   "tag-docs-next-tags-bar-tag-3-permalink-94a.json": "{
-  \\"name\\": \\"barTag 3\\",
+  \\"label\\": \\"barTag 3\\",
   \\"permalink\\": \\"/docs/next/tags/barTag-3-permalink\\",
-  \\"docs\\": [
+  \\"allTagsPath\\": \\"/docs/next/tags\\",
+  \\"count\\": 1,
+  \\"items\\": [
     {
       \\"id\\": \\"foo/bar\\",
       \\"title\\": \\"bar\\",
       \\"description\\": \\"This is next version of bar.\\",
       \\"permalink\\": \\"/docs/next/foo/barSlug\\"
     }
-  ],
-  \\"allTagsPath\\": \\"/docs/next/tags\\"
+  ]
 }",
   "tags-list-current-prop-15a.json": "[
   {
-    \\"name\\": \\"barTag 1\\",
+    \\"label\\": \\"barTag 1\\",
     \\"permalink\\": \\"/docs/next/tags/bar-tag-1\\",
     \\"count\\": 1
   },
   {
-    \\"name\\": \\"barTag-2\\",
+    \\"label\\": \\"barTag-2\\",
     \\"permalink\\": \\"/docs/next/tags/bar-tag-2\\",
     \\"count\\": 1
   },
   {
-    \\"name\\": \\"barTag 3\\",
+    \\"label\\": \\"barTag 3\\",
     \\"permalink\\": \\"/docs/next/tags/barTag-3-permalink\\",
     \\"count\\": 1
   }

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

@@ -54,9 +54,10 @@ describe('toTagDocListProp', () => {
 
     expect(result).toEqual({
       allTagsPath,
-      name: tag.label,
+      count: 2,
+      label: tag.label,
       permalink: tag.permalink,
-      docs: [doc3, doc1], // docs sorted by title, ignore "id5" absence
+      items: [doc3, doc1], // docs sorted by title, ignore "id5" absence
     });
   });
 });

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

@@ -228,13 +228,13 @@ export default async function pluginContentDocs(
           const tagsProp: PropTagsListPage['tags'] = Object.values(
             versionTags,
           ).map((tagValue) => ({
-            name: tagValue.label,
+            label: tagValue.label,
             permalink: tagValue.permalink,
             count: tagValue.docIds.length,
           }));
 
           // Only create /tags page if there are tags.
-          if (Object.keys(tagsProp).length > 0) {
+          if (tagsProp.length > 0) {
             const tagsPropPath = await createData(
               `${docuHash(`tags-list-${version.versionName}-prop`)}.json`,
               JSON.stringify(tagsProp, null, 2),

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

@@ -7,7 +7,8 @@
 
 declare module '@docusaurus/plugin-content-docs' {
   import type {MDXOptions} from '@docusaurus/mdx-loader';
-  import type {ContentPaths, Tag, FrontMatterTag} from '@docusaurus/utils';
+  import type {ContentPaths, FrontMatterTag} from '@docusaurus/utils';
+  import type {TagsListItem, TagModule, Tag} from '@docusaurus/types';
   import type {Required} from 'utility-types';
 
   export type Assets = {
@@ -483,25 +484,14 @@ declare module '@docusaurus/plugin-content-docs' {
   export type PropSidebar = import('./sidebars/types').PropSidebar;
   export type PropSidebars = import('./sidebars/types').PropSidebars;
 
-  export type PropTagDocListDoc = {
-    id: string;
-    title: string;
-    description: string;
-    permalink: string;
-  };
-  export type PropTagDocList = {
-    allTagsPath: string;
-    name: string; // normalized name/label of the tag
-    permalink: string; // pathname of the tag
-    docs: PropTagDocListDoc[];
-  };
+  export type PropTagDocListDoc = Pick<
+    DocMetadata,
+    'id' | 'title' | 'description' | 'permalink'
+  >;
+  export type PropTagDocList = TagModule & {items: PropTagDocListDoc[]};
 
   export type PropTagsListPage = {
-    tags: {
-      name: string;
-      permalink: string;
-      count: number;
-    }[];
+    tags: TagsListItem[];
   };
 }
 

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

@@ -137,7 +137,7 @@ export function toTagDocListProp({
 }: {
   allTagsPath: string;
   tag: VersionTag;
-  docs: Pick<DocMetadata, 'id' | 'title' | 'description' | 'permalink'>[];
+  docs: DocMetadata[];
 }): PropTagDocList {
   function toDocListProp(): PropTagDocListDoc[] {
     const list = _.compact(
@@ -154,9 +154,10 @@ export function toTagDocListProp({
   }
 
   return {
-    name: tag.label,
+    label: tag.label,
     permalink: tag.permalink,
-    docs: toDocListProp(),
     allTagsPath,
+    count: tag.docIds.length,
+    items: toDocListProp(),
   };
 }

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

@@ -8,13 +8,14 @@
 /// <reference types="@docusaurus/module-type-aliases" />
 
 import type {Sidebars} from './sidebars/types';
-import type {BrokenMarkdownLink, Tag} from '@docusaurus/utils';
+import type {BrokenMarkdownLink} from '@docusaurus/utils';
 import type {
   VersionMetadata,
   LastUpdateData,
   DocMetadata,
   CategoryGeneratedIndexMetadata,
 } from '@docusaurus/plugin-content-docs';
+import type {Tag} from '@docusaurus/types';
 
 export type DocFile = {
   contentPath: string; // /!\ may be localized
@@ -33,7 +34,7 @@ export type VersionTag = Tag & {
   docIds: string[];
 };
 export type VersionTags = {
-  [key: string]: VersionTag;
+  [permalink: string]: VersionTag;
 };
 
 export type LoadedVersion = VersionMetadata & {