refactor(content-docs): deduplicate types, JSDoc for some APIs

packages/docusaurus-mdx-loader/src/index.ts

@@ -21,21 +21,21 @@ import toc from './remark/toc';
 import unwrapMdxCodeBlocks from './remark/unwrapMdxCodeBlocks';
 import transformImage from './remark/transformImage';
 import transformLinks from './remark/transformLinks';
-import type {RemarkAndRehypePluginOptions} from '@docusaurus/mdx-loader';
+import type {MDXOptions} from '@docusaurus/mdx-loader';
 import type {LoaderContext} from 'webpack';
 
 const {
   loaders: {inlineMarkdownImageFileLoader},
 } = getFileLoaderUtils();
 
-const DEFAULT_OPTIONS: RemarkAndRehypePluginOptions = {
+const DEFAULT_OPTIONS: MDXOptions = {
   rehypePlugins: [],
   remarkPlugins: [unwrapMdxCodeBlocks, emoji, headings, toc],
   beforeDefaultRemarkPlugins: [],
   beforeDefaultRehypePlugins: [],
 };
 
-type Options = RemarkAndRehypePluginOptions & {
+type Options = MDXOptions & {
   staticDirs: string[];
   siteDir: string;
   isMDXPartial?: (filePath: string) => boolean;

packages/docusaurus-mdx-loader/src/mdx-loader.d.ts

@@ -7,12 +7,12 @@
 
 import type {Plugin} from 'unified';
 
-export type RemarkOrRehypePlugin =
+export type MDXPlugin =
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   [Plugin<any[]>, any] | Plugin<any[]>;
-export type RemarkAndRehypePluginOptions = {
-  remarkPlugins: RemarkOrRehypePlugin[];
-  rehypePlugins: RemarkOrRehypePlugin[];
-  beforeDefaultRemarkPlugins: RemarkOrRehypePlugin[];
-  beforeDefaultRehypePlugins: RemarkOrRehypePlugin[];
+export type MDXOptions = {
+  remarkPlugins: MDXPlugin[];
+  rehypePlugins: MDXPlugin[];
+  beforeDefaultRemarkPlugins: MDXPlugin[];
+  beforeDefaultRehypePlugins: MDXPlugin[];
 };

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

@@ -6,8 +6,8 @@
  */
 
 declare module '@docusaurus/plugin-content-blog' {
-  import type {RemarkAndRehypePluginOptions} from '@docusaurus/mdx-loader';
-  import type {FrontMatterTag} from '@docusaurus/utils';
+  import type {MDXOptions} from '@docusaurus/mdx-loader';
+  import type {FrontMatterTag, Tag} from '@docusaurus/utils';
   import type {Overwrite} from 'utility-types';
 
   export interface Assets {
@@ -81,10 +81,7 @@ declare module '@docusaurus/plugin-content-blog' {
      * @see {@link BlogPostMetadata.tags}
      */
     tags?: FrontMatterTag[];
-    /**
-     * Custom slug appended after /<baseUrl>/<routeBasePath>/
-     * @see {@link BlogPostMetadata.slug}
-     */
+    /** Custom slug appended after `/<baseUrl>/<routeBasePath>/` */
     slug?: string;
     /**
      * Marks the post as draft and excludes it from the production build.
@@ -130,25 +127,18 @@ declare module '@docusaurus/plugin-content-blog' {
     /** @deprecated v1 legacy */
     authorImageURL?: string;
 
-    /**
-     * @see {@link BlogPostMetadata.image}
-     */
+    /** Used in the head meta. Should use `assets.image` in priority. */
     image?: string;
-    /**
-     * Used in the head meta
-     */
+    /** Used in the head meta. */
     keywords?: string[];
-    /**
-     * Hide the right TOC
-     */
+    /** Hide the right TOC. */
     hide_table_of_contents?: boolean;
     /**
-     * Minimum TOC heading level
+     * Minimum TOC heading level. Must be between 2 and 6 and lower or equal to
+     * the max value.
      */
     toc_min_heading_level?: number;
-    /**
-     * Maximum TOC heading level
-     */
+    /** Maximum TOC heading level. Must be between 2 and 6. */
     toc_max_heading_level?: number;
   };
 
@@ -175,9 +165,7 @@ declare module '@docusaurus/plugin-content-blog' {
     | (string | BlogPostFrontMatterAuthor)[];
 
   export type BlogPostMetadata = {
-    /**
-     * Path to the Markdown source, with `@site` alias.
-     */
+    /** Path to the Markdown source, with `@site` alias. */
     readonly source: string;
     /**
      * Used to generate the page h1 heading, tab title, and pagination title.
@@ -193,9 +181,7 @@ declare module '@docusaurus/plugin-content-blog' {
      * render the date regardless of the existence of `Intl.DateTimeFormat`.
      */
     readonly formattedDate: string;
-    /**
-     * Full link including base URL.
-     */
+    /** Full link including base URL. */
     readonly permalink: string;
     /**
      * Description used in the meta. Could be an empty string (empty content)
@@ -229,17 +215,10 @@ declare module '@docusaurus/plugin-content-blog' {
      * `assets.authorsImageUrls` on client side.
      */
     readonly authors: Author[];
-    /**
-     * Front matter, as-is.
-     */
+    /** Front matter, as-is. */
     readonly frontMatter: BlogPostFrontMatter & {[key: string]: unknown};
-    /**
-     * Tags, normalized.
-     */
-    readonly tags: readonly {
-      readonly label: string;
-      readonly permalink: string;
-    }[];
+    /** Tags, normalized. */
+    readonly tags: Tag[];
   };
   /**
    * @returns The edit URL that's directly plugged into metadata.
@@ -250,17 +229,11 @@ declare module '@docusaurus/plugin-content-blog' {
      * site path. Usually the same as `options.path` but can be localized
      */
     blogDirPath: string;
-    /**
-     * Path to this post file, relative to `blogDirPath`
-     */
+    /** Path to this post file, relative to `blogDirPath`. */
     blogPath: string;
-    /**
-     * @see {@link BlogPostMetadata.permalink}
-     */
+    /** @see {@link BlogPostMetadata.permalink} */
     permalink: string;
-    /**
-     * Locale name.
-     */
+    /** Locale name. */
     locale: string;
   }) => string | undefined;
 
@@ -325,7 +298,7 @@ declare module '@docusaurus/plugin-content-blog' {
   /**
    * Plugin options after normalization.
    */
-  export type PluginOptions = RemarkAndRehypePluginOptions & {
+  export type PluginOptions = MDXOptions & {
     /** Plugin ID. */
     id?: string;
     /**

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

@@ -169,7 +169,9 @@ exports[`translateLoadedContent returns translated loaded content 1`] = `
         },
       ],
       "isLast": true,
+      "label": "current label (translated)",
       "mainDocId": "",
+      "path": "/docs/",
       "routePriority": undefined,
       "sidebarFilePath": "any",
       "sidebars": {
@@ -221,9 +223,7 @@ exports[`translateLoadedContent returns translated loaded content 1`] = `
           },
         ],
       },
-      "versionLabel": "current label (translated)",
       "versionName": "current",
-      "versionPath": "/docs/",
     },
     {
       "contentPath": "any",
@@ -311,7 +311,9 @@ exports[`translateLoadedContent returns translated loaded content 1`] = `
         },
       ],
       "isLast": true,
+      "label": "2.0.0 label (translated)",
       "mainDocId": "",
+      "path": "/docs/",
       "routePriority": undefined,
       "sidebarFilePath": "any",
       "sidebars": {
@@ -363,9 +365,7 @@ exports[`translateLoadedContent returns translated loaded content 1`] = `
           },
         ],
       },
-      "versionLabel": "2.0.0 label (translated)",
       "versionName": "2.0.0",
-      "versionPath": "/docs/",
     },
     {
       "contentPath": "any",
@@ -453,7 +453,9 @@ exports[`translateLoadedContent returns translated loaded content 1`] = `
         },
       ],
       "isLast": true,
+      "label": "1.0.0 label (translated)",
       "mainDocId": "",
+      "path": "/docs/",
       "routePriority": undefined,
       "sidebarFilePath": "any",
       "sidebars": {
@@ -505,9 +507,7 @@ exports[`translateLoadedContent returns translated loaded content 1`] = `
           },
         ],
       },
-      "versionLabel": "1.0.0 label (translated)",
       "versionName": "1.0.0",
-      "versionPath": "/docs/",
     },
   ],
 }

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

@@ -18,16 +18,14 @@ import {
 import {loadSidebars} from '../sidebars';
 import type {Sidebars} from '../sidebars/types';
 import {readVersionsMetadata} from '../versions';
-import type {
-  DocFile,
-  DocMetadataBase,
-  VersionMetadata,
-  DocNavLink,
-} from '../types';
+import type {DocFile} from '../types';
 import type {
   MetadataOptions,
   PluginOptions,
   EditUrlFunction,
+  DocMetadataBase,
+  VersionMetadata,
+  PropNavigationLink,
 } from '@docusaurus/plugin-content-docs';
 import type {LoadContext} from '@docusaurus/types';
 import {DEFAULT_OPTIONS} from '../options';
@@ -123,7 +121,11 @@ function createTestUtils({
   }
 
   async function generateNavigation(docFiles: DocFile[]): Promise<{
-    pagination: {prev?: DocNavLink; next?: DocNavLink; id: string}[];
+    pagination: {
+      prev?: PropNavigationLink;
+      next?: PropNavigationLink;
+      id: string;
+    }[];
     sidebars: Sidebars;
   }> {
     const rawDocs = docFiles.map((docFile) =>

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

@@ -6,7 +6,7 @@
  */
 
 import {validateDocFrontMatter} from '../frontMatter';
-import type {DocFrontMatter} from '../types';
+import type {DocFrontMatter} from '@docusaurus/plugin-content-docs';
 import escapeStringRegexp from 'escape-string-regexp';
 
 function testField(params: {

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

@@ -12,9 +12,9 @@ describe('toGlobalDataVersion', () => {
     expect(
       toGlobalDataVersion({
         versionName: 'current',
-        versionLabel: 'Label',
+        label: 'Label',
         isLast: true,
-        versionPath: '/current',
+        path: '/current',
         mainDocId: 'main',
         docs: [
           {
@@ -86,9 +86,9 @@ describe('toGlobalDataVersion', () => {
             sidebar: 'tutorial',
           },
         ],
-        versionBanner: 'unreleased',
-        versionBadge: true,
-        versionClassName: 'current-cls',
+        banner: 'unreleased',
+        badge: true,
+        className: 'current-cls',
         tagsPath: '/current/tags',
         contentPath: '',
         contentPathLocalized: '',

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

@@ -16,7 +16,7 @@ describe('toTagDocListProp', () => {
 
   it('works', () => {
     const tag: Tag = {
-      name: 'tag1',
+      label: 'tag1',
       permalink: '/tag1',
       docIds: ['id1', 'id3'],
     };
@@ -54,7 +54,7 @@ describe('toTagDocListProp', () => {
 
     expect(result).toEqual({
       allTagsPath,
-      name: tag.name,
+      name: tag.label,
       permalink: tag.permalink,
       docs: [doc3, doc1], // docs sorted by title, ignore "id5" absence
     });

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

@@ -5,12 +5,13 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import type {LoadedContent, DocMetadata, LoadedVersion} from '../types';
+import type {LoadedContent, LoadedVersion} from '../types';
 import {CURRENT_VERSION_NAME} from '../constants';
 import {
   getLoadedContentTranslationFiles,
   translateLoadedContent,
 } from '../translations';
+import type {DocMetadata} from '@docusaurus/plugin-content-docs';
 import {updateTranslationFileMessages} from '@docusaurus/utils';
 
 function createSampleDoc(doc: Pick<DocMetadata, 'id'>): DocMetadata {
@@ -36,30 +37,20 @@ function createSampleVersion(
   version: Pick<LoadedVersion, 'versionName'>,
 ): LoadedVersion {
   return {
-    versionLabel: `${version.versionName} label`,
-    versionPath: '/docs/',
+    label: `${version.versionName} label`,
+    path: '/docs/',
     mainDocId: '',
     routePriority: undefined,
     sidebarFilePath: 'any',
     isLast: true,
     contentPath: 'any',
     contentPathLocalized: 'any',
     docs: [
-      createSampleDoc({
-        id: 'doc1',
-      }),
-      createSampleDoc({
-        id: 'doc2',
-      }),
-      createSampleDoc({
-        id: 'doc3',
-      }),
-      createSampleDoc({
-        id: 'doc4',
-      }),
-      createSampleDoc({
-        id: 'doc5',
-      }),
+      createSampleDoc({id: 'doc1'}),
+      createSampleDoc({id: 'doc2'}),
+      createSampleDoc({id: 'doc3'}),
+      createSampleDoc({id: 'doc4'}),
+      createSampleDoc({id: 'doc5'}),
     ],
     sidebars: {
       docs: [