Merge branch 'main' of github.com:facebook/docusaurus into lex111/min…

…or-fixes

packages/create-docusaurus/src/index.ts

@@ -271,7 +271,7 @@ export default async function init(
         return logger.red('Invalid repository URL');
       },
       message: logger.interpolate`Enter a repository URL from GitHub, Bitbucket, GitLab, or any other public repo.
-(e.g: path=${'https://github.com/ownerName/repoName.git'})`,
+(e.g: url=${'https://github.com/ownerName/repoName.git'})`,
     });
     ({gitStrategy} = await prompts({
       type: 'select',
@@ -318,7 +318,7 @@ export default async function init(
   logger.info('Creating new Docusaurus project...');
 
   if (isValidGitRepoUrl(template)) {
-    logger.info`Cloning Git template path=${template}...`;
+    logger.info`Cloning Git template url=${template}...`;
     if (!gitStrategies.includes(gitStrategy)) {
       logger.error`Invalid git strategy: name=${gitStrategy}. Value must be one of ${gitStrategies.join(
         ', ',
@@ -416,7 +416,7 @@ export default async function init(
   }
 
   const useNpm = pkgManager === 'npm';
-  logger.success`Created path=${cdpath}.`;
+  logger.success`Created name=${cdpath}.`;
   logger.info`Inside that directory, you can run several commands:
 
   code=${`${pkgManager} start`}

packages/docusaurus-logger/README.md

@@ -8,7 +8,8 @@ It exports a single object as default export: `logger`. `logger` has the followi
 
 - Some useful colors.
 - Formatters. These functions have the same signature as the formatters of `picocolors`. Note that their implementations are not guaranteed. You should only care about their semantics.
-  - `path`: formats a file path or URL.
+  - `path`: formats a file path.
+  - `url`: formats a URL.
   - `id`: formats an identifier.
   - `code`: formats a code snippet.
   - `subdue`: subdues the text.
@@ -34,6 +35,7 @@ To buy anything, enter code=${'buy x'} where code=${'x'} is the item's name; to
 An embedded expression is optionally preceded by a flag in the form `%[a-z]+` (a percentage sign followed by a few lowercase letters). If it's not preceded by any flag, it's printed out as-is. Otherwise, it's formatted with one of the formatters:
 
 - `path=`: `path`
+- `url=`: `url`
 - `name=`: `id`
 - `code=`: `code`
 - `subdue=`: `subdue`

packages/docusaurus-logger/src/__tests__/index.test.ts

@@ -11,7 +11,12 @@ import logger from '../index';
 describe('formatters', () => {
   it('path', () => {
     // cSpell:ignore mhey
-    expect(logger.path('hey')).toMatchInlineSnapshot(`"hey"`);
+    expect(logger.path('hey')).toMatchInlineSnapshot(`"\\"hey\\""`);
+  });
+  it('url', () => {
+    expect(logger.url('https://docusaurus.io/')).toMatchInlineSnapshot(
+      `"https://docusaurus.io/"`,
+    );
   });
   it('id', () => {
     expect(logger.name('hey')).toMatchInlineSnapshot(`"hey"`);
@@ -40,8 +45,7 @@ describe('interpolate', () => {
     expect(
       logger.interpolate`The package at path=${'packages/docusaurus'} has number=${10} files. name=${'Babel'} is exported here subdue=${'(as a preset)'} that you can with code=${"require.resolve('@docusaurus/core/lib/babel/preset')"}`,
     ).toMatchInlineSnapshot(
-      // cSpell:ignore mpackages
-      `"The package at packages/docusaurus has 10 files. Babel is exported here (as a preset) that you can with \`require.resolve('@docusaurus/core/lib/babel/preset')\`"`,
+      `"The package at \\"packages/docusaurus\\" has 10 files. Babel is exported here (as a preset) that you can with \`require.resolve('@docusaurus/core/lib/babel/preset')\`"`,
     );
   });
   it('interpolates arrays with flags', () => {

packages/docusaurus-logger/src/index.ts

@@ -9,7 +9,8 @@ import chalk, {type Chalk} from 'chalk';
 
 type InterpolatableValue = string | number | (string | number)[];
 
-const path = (msg: unknown): string => chalk.cyan(chalk.underline(msg));
+const path = (msg: unknown): string => chalk.cyan(chalk.underline(`"${msg}"`));
+const url = (msg: unknown): string => chalk.cyan(chalk.underline(msg));
 const name = (msg: unknown): string => chalk.blue(chalk.bold(msg));
 const code = (msg: unknown): string => chalk.cyan(`\`${msg}\``);
 const subdue: Chalk = chalk.gray;
@@ -30,6 +31,8 @@ function interpolate(
       switch (flag[0]) {
         case 'path=':
           return path;
+        case 'url=':
+          return url;
         case 'number=':
           return num;
         case 'name=':
@@ -131,6 +134,7 @@ const logger = {
   bold: chalk.bold,
   dim: chalk.dim,
   path,
+  url,
   name,
   code,
   subdue,

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/feed.ts

@@ -9,7 +9,6 @@ import {Feed, type Author as FeedAuthor, type Item as FeedItem} from 'feed';
 import type {BlogPost} from './types';
 import {
   normalizeUrl,
-  posixPath,
   mapAsyncSequential,
   readOutputHTMLFile,
 } from '@docusaurus/utils';
@@ -128,10 +127,7 @@ async function createBlogFeedFile({
     }
   })();
   try {
-    await fs.outputFile(
-      posixPath(path.join(generatePath, feedPath)),
-      feedContent,
-    );
+    await fs.outputFile(path.join(generatePath, feedPath), feedContent);
   } catch (err) {
     throw new Error(`Generating ${feedType} feed failed: ${err}.`);
   }

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__/cli.test.ts

@@ -181,7 +181,7 @@ describe('docsVersion', () => {
         DEFAULT_OPTIONS,
       ),
     ).rejects.toThrowErrorMatchingInlineSnapshot(
-      `"[docs]: there is no docs to version!"`,
+      `"[docs]: no docs found in <PROJECT_ROOT>/packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/empty-site/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: {