create-docusaurus 3.9.2 → 3.10.1

package/bin/index.js

@@ -8,8 +8,9 @@
 
 // @ts-check
 
-import path from 'path';
-import {createRequire} from 'module';
+import path from 'node:path';
+import {inspect} from 'node:util';
+import {createRequire} from 'node:module';
 import {logger} from '@docusaurus/logger';
 import semver from 'semver';
 import {program} from 'commander';
@@ -61,7 +62,7 @@ if (!process.argv.slice(1).length) {
   program.outputHelp();
 }
 
-process.on('unhandledRejection', (err) => {
-  logger.error(err);
+process.on('unhandledRejection', (error) => {
+  logger.error(inspect(error));
   process.exit(1);
 });

package/lib/index.js

@@ -4,17 +4,17 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import fs from 'fs-extra';
-import { fileURLToPath } from 'url';
-import path from 'path';
-import _ from 'lodash';
+import * as fs from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+// KEEP DEPENDENCY SMALL HERE!
+// create-docusaurus CLI should be as lightweight as possible
+// TODO try to remove these third-party dependencies if possible
 import { logger } from '@docusaurus/logger';
-import execa from 'execa';
 import prompts from 'prompts';
 import supportsColor from 'supports-color';
-// TODO remove dependency on large @docusaurus/utils
-//  would be better to have a new smaller @docusaurus/utils-cli package
-import { askPreferredLanguage } from '@docusaurus/utils';
+import { runCommand, siteNameToPackageName } from './utils.js';
+import { askPreferredLanguage } from './prompts.js';
 async function getLanguage(options) {
     if (options.typescript) {
         return 'typescript';
@@ -34,10 +34,16 @@ const lockfileNames = {
     bun: 'bun.lockb',
 };
 const packageManagers = Object.keys(lockfileNames);
+function pathExists(filePath) {
+    return fs
+        .access(filePath, fs.constants.F_OK)
+        .then(() => true)
+        .catch(() => false);
+}
 async function findPackageManagerFromLockFile(rootDir) {
     for (const packageManager of packageManagers) {
         const lockFilePath = path.join(rootDir, lockfileNames[packageManager]);
-        if (await fs.pathExists(lockFilePath)) {
+        if (await pathExists(lockFilePath)) {
             return packageManager;
         }
     }
@@ -47,9 +53,9 @@ function findPackageManagerFromUserAgent() {
     return packageManagers.find((packageManager) => process.env.npm_config_user_agent?.startsWith(packageManager));
 }
 async function askForPackageManagerChoice() {
-    const hasYarn = (await execa.command('yarn --version')).exitCode === 0;
-    const hasPnpm = (await execa.command('pnpm --version')).exitCode === 0;
-    const hasBun = (await execa.command('bun --version')).exitCode === 0;
+    const hasYarn = (await runCommand('yarn --version')) === 0;
+    const hasPnpm = (await runCommand('pnpm --version')) === 0;
+    const hasBun = (await runCommand('bun --version')) === 0;
     if (!hasYarn && !hasPnpm && !hasBun) {
         return 'npm';
     }
@@ -96,18 +102,29 @@ async function readTemplates() {
         return {
             name,
             path: path.join(templatesDir, name),
-            tsVariantPath: (await fs.pathExists(tsVariantPath))
+            tsVariantPath: (await pathExists(tsVariantPath))
                 ? tsVariantPath
                 : undefined,
         };
     }));
     // Classic should be first in list!
-    return _.sortBy(templates, (t) => t.name !== recommendedTemplate);
+    return templates.sort((a, b) => {
+        if (a.name === recommendedTemplate) {
+            return -1;
+        }
+        if (b.name === recommendedTemplate) {
+            return 1;
+        }
+        return 0;
+    });
 }
 async function copyTemplate(template, dest, language) {
-    await fs.copy(path.join(templatesDir, 'shared'), dest);
+    await fs.cp(path.join(templatesDir, 'shared'), dest, {
+        recursive: true,
+    });
     const sourcePath = language === 'typescript' ? template.tsVariantPath : template.path;
-    await fs.copy(sourcePath, dest, {
+    await fs.cp(sourcePath, dest, {
+        recursive: true,
         // Symlinks don't exist in published npm packages anymore, so this is only
         // to prevent errors during local testing
         filter: async (filePath) => !(await fs.lstat(filePath)).isSymbolicLink(),
@@ -176,7 +193,10 @@ async function getSiteName(reqName, rootDir) {
             return 'A website name is required.';
         }
         const dest = path.resolve(rootDir, siteName);
-        if (await fs.pathExists(dest)) {
+        if (siteName === '.' && (await fs.readdir(dest)).length > 0) {
+            return logger.interpolate `Directory not empty at path=${dest}!`;
+        }
+        if (siteName !== '.' && (await pathExists(dest))) {
             return logger.interpolate `Directory already exists at path=${dest}!`;
         }
         return true;
@@ -236,7 +256,7 @@ async function getUserProvidedSource({ reqTemplate, templates, cliOptions, }) {
             strategy: cliOptions.gitStrategy ?? 'deep',
         };
     }
-    if (await fs.pathExists(path.resolve(reqTemplate))) {
+    if (await pathExists(path.resolve(reqTemplate))) {
         return {
             type: 'local',
             path: path.resolve(reqTemplate),
@@ -303,7 +323,7 @@ async function askLocalSource() {
         validate: async (dir) => {
             if (dir) {
                 const fullDir = path.resolve(dir);
-                if (await fs.pathExists(fullDir)) {
+                if (await pathExists(fullDir)) {
                     return true;
                 }
                 return logger.red(logger.interpolate `path=${fullDir} does not exist.`);
@@ -339,9 +359,10 @@ async function getSource(reqTemplate, templates, cliOptions) {
     });
 }
 async function updatePkg(pkgPath, obj) {
-    const pkg = (await fs.readJSON(pkgPath));
+    const pkg = JSON.parse(await fs.readFile(pkgPath, 'utf8'));
     const newPkg = Object.assign(pkg, obj);
-    await fs.outputFile(pkgPath, `${JSON.stringify(newPkg, null, 2)}\n`);
+    await fs.mkdir(path.dirname(pkgPath), { recursive: true });
+    await fs.writeFile(pkgPath, `${JSON.stringify(newPkg, null, 2)}\n`);
 }
 export default async function init(rootDir, reqName, reqTemplate, cliOptions = {}) {
     const [templates, siteName] = await Promise.all([
@@ -353,12 +374,15 @@ export default async function init(rootDir, reqName, reqTemplate, cliOptions = {
     logger.info('Creating new Docusaurus project...');
     if (source.type === 'git') {
         const gitCommand = await getGitCommand(source.strategy);
-        if ((await execa(gitCommand, [source.url, dest])).exitCode !== 0) {
+        if ((await runCommand(gitCommand, [source.url, dest])) !== 0) {
             logger.error `Cloning Git template failed!`;
             process.exit(1);
         }
         if (source.strategy === 'copy') {
-            await fs.remove(path.join(dest, '.git'));
+            await fs.rm(path.join(dest, '.git'), {
+                force: true,
+                recursive: true,
+            });
         }
     }
     else if (source.type === 'template') {
@@ -366,38 +390,35 @@ export default async function init(rootDir, reqName, reqTemplate, cliOptions = {
             await copyTemplate(source.template, dest, source.language);
         }
         catch (err) {
-            logger.error `Copying Docusaurus template name=${source.template.name} failed!`;
-            throw err;
+            throw new Error(logger.interpolate `Copying Docusaurus template name=${source.template.name} failed!`, { cause: err });
         }
     }
     else {
         try {
-            await fs.copy(source.path, dest);
+            await fs.cp(source.path, dest, { recursive: true });
         }
         catch (err) {
-            logger.error `Copying local template path=${source.path} failed!`;
-            throw err;
+            throw new Error(logger.interpolate `Copying local template path=${source.path} failed!`, { cause: err });
         }
     }
     // Update package.json info.
     try {
         await updatePkg(path.join(dest, 'package.json'), {
-            name: _.kebabCase(siteName),
+            name: siteNameToPackageName(siteName),
             version: '0.0.0',
             private: true,
         });
     }
     catch (err) {
-        logger.error('Failed to update package.json.');
-        throw err;
+        throw new Error('Failed to update package.json.', { cause: err });
     }
     // We need to rename the gitignore file to .gitignore
-    if (!(await fs.pathExists(path.join(dest, '.gitignore'))) &&
-        (await fs.pathExists(path.join(dest, 'gitignore')))) {
-        await fs.move(path.join(dest, 'gitignore'), path.join(dest, '.gitignore'));
+    if (!(await pathExists(path.join(dest, '.gitignore'))) &&
+        (await pathExists(path.join(dest, 'gitignore')))) {
+        await fs.rename(path.join(dest, 'gitignore'), path.join(dest, '.gitignore'));
     }
-    if (await fs.pathExists(path.join(dest, 'gitignore'))) {
-        await fs.remove(path.join(dest, 'gitignore'));
+    if (await pathExists(path.join(dest, 'gitignore'))) {
+        await fs.rm(path.join(dest, 'gitignore'));
     }
     // Display the most elegant way to cd.
     const cdpath = path.relative('.', dest);
@@ -406,17 +427,17 @@ export default async function init(rootDir, reqName, reqTemplate, cliOptions = {
         process.chdir(dest);
         logger.info `Installing dependencies with name=${pkgManager}...`;
         // ...
-        if ((await execa.command(pkgManager === 'yarn'
+        if ((await runCommand(pkgManager === 'yarn'
             ? 'yarn'
             : pkgManager === 'bun'
                 ? 'bun install'
-                : `${pkgManager} install --color always`, {
+                : `${pkgManager} install --color always`, [], {
             env: {
                 ...process.env,
                 // Force coloring the output
                 ...(supportsColor.stdout ? { FORCE_COLOR: '1' } : {}),
             },
-        })).exitCode !== 0) {
+        })) !== 0) {
             logger.error('Dependency installation failed.');
             logger.info `The site directory has already been created, and you can retry by typing:
 

package/lib/prompts.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+export declare function askPreferredLanguage(): Promise<'javascript' | 'typescript'>;

package/lib/prompts.js

@@ -0,0 +1,23 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import prompts from 'prompts';
+import { logger } from '@docusaurus/logger';
+export async function askPreferredLanguage() {
+    const { language } = await prompts({
+        type: 'select',
+        name: 'language',
+        message: 'Which language do you want to use?',
+        choices: [
+            { title: logger.bold('JavaScript'), value: 'javascript' },
+            { title: logger.bold('TypeScript'), value: 'typescript' },
+        ],
+    });
+    if (!language) {
+        process.exit(0);
+    }
+    return language;
+}

package/lib/types.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+export type PackageManager = 'npm' | 'yarn' | 'pnpm' | 'bun';

package/lib/types.js

@@ -0,0 +1,7 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+export {};

package/lib/utils.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import type { SpawnOptions } from 'node:child_process';
+/**
+ * Run a command, similar to execa(cmd,args) but simpler
+ * @param command
+ * @param args
+ * @param options
+ * @returns the command exit code
+ */
+export declare function runCommand(command: string, args?: string[], options?: SpawnOptions): Promise<number>;
+/**
+ * We use a simple kebab-case-like conversion
+ * It's not perfect, but good enough
+ * We don't want to depend on lodash in this package
+ * See https://github.com/facebook/docusaurus/pull/11653
+ * @param siteName
+ */
+export declare function siteNameToPackageName(siteName: string): string;

package/lib/utils.js

@@ -0,0 +1,50 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+// @ts-expect-error: no types, but same as spawn()
+import CrossSpawn from 'cross-spawn';
+// We use cross-spawn instead of spawn because of Windows compatibility issues.
+// For example, "yarn" doesn't work on Windows, it requires "yarn.cmd"
+// Tools like execa() use cross-spawn under the hood, and "resolve" the command
+const crossSpawn = CrossSpawn;
+/**
+ * Run a command, similar to execa(cmd,args) but simpler
+ * @param command
+ * @param args
+ * @param options
+ * @returns the command exit code
+ */
+export async function runCommand(command, args = [], options = {}) {
+    // This does something similar to execa.command()
+    // we split a string command (with optional args) into command+args
+    // this way it's compatible with spawn()
+    const [realCommand, ...baseArgs] = command.split(' ');
+    const allArgs = [...baseArgs, ...args];
+    if (!realCommand) {
+        throw new Error(`Invalid command: ${command}`);
+    }
+    return new Promise((resolve, reject) => {
+        const p = crossSpawn(realCommand, allArgs, { stdio: 'ignore', ...options });
+        p.on('error', reject);
+        p.on('close', (exitCode) => exitCode !== null
+            ? resolve(exitCode)
+            : reject(new Error(`No exit code for command ${command}`)));
+    });
+}
+/**
+ * We use a simple kebab-case-like conversion
+ * It's not perfect, but good enough
+ * We don't want to depend on lodash in this package
+ * See https://github.com/facebook/docusaurus/pull/11653
+ * @param siteName
+ */
+export function siteNameToPackageName(siteName) {
+    const match = siteName.match(/[A-Z]{2,}(?=[A-Z][a-z]+\d*|\b|_)|[A-Z]?[a-z]+\d*|[A-Z]|\d+/g);
+    if (match) {
+        return match.map((x) => x.toLowerCase()).join('-');
+    }
+    return siteName;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-docusaurus",
-  "version": "3.9.2",
+  "version": "3.10.1",
   "description": "Create Docusaurus apps easily.",
   "type": "module",
   "repository": {
@@ -22,12 +22,9 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@docusaurus/logger": "3.9.2",
-    "@docusaurus/utils": "3.9.2",
+    "@docusaurus/logger": "3.10.1",
     "commander": "^5.1.0",
-    "execa": "5.1.1",
-    "fs-extra": "^11.1.1",
-    "lodash": "^4.17.21",
+    "cross-spawn": "^7.0.0",
     "prompts": "^2.4.2",
     "semver": "^7.5.4",
     "supports-color": "^9.4.0",
@@ -39,5 +36,5 @@
   "engines": {
     "node": ">=20.0"
   },
-  "gitHead": "abfbe5621b08407bc3dcbe6111ff118d4c22f7a1"
+  "gitHead": "41c1a458ecb07d61b6df2761ea4bc1b13db49d12"
 }

package/templates/classic/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docusaurus-2-classic-template",
-  "version": "3.9.2",
+  "version": "3.10.1",
   "private": true,
   "scripts": {
     "docusaurus": "docusaurus",
@@ -14,8 +14,9 @@
     "write-heading-ids": "docusaurus write-heading-ids"
   },
   "dependencies": {
-    "@docusaurus/core": "3.9.2",
-    "@docusaurus/preset-classic": "3.9.2",
+    "@docusaurus/core": "3.10.1",
+    "@docusaurus/faster": "3.10.1",
+    "@docusaurus/preset-classic": "3.10.1",
     "@mdx-js/react": "^3.0.0",
     "clsx": "^2.0.0",
     "prism-react-renderer": "^2.3.0",
@@ -23,8 +24,8 @@
     "react-dom": "^19.0.0"
   },
   "devDependencies": {
-    "@docusaurus/module-type-aliases": "3.9.2",
-    "@docusaurus/types": "3.9.2"
+    "@docusaurus/module-type-aliases": "3.10.1",
+    "@docusaurus/types": "3.10.1"
   },
   "browserslist": {
     "production": [

package/templates/classic-typescript/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docusaurus-2-classic-typescript-template",
-  "version": "3.9.2",
+  "version": "3.10.1",
   "private": true,
   "scripts": {
     "docusaurus": "docusaurus",
@@ -15,8 +15,9 @@
     "typecheck": "tsc"
   },
   "dependencies": {
-    "@docusaurus/core": "3.9.2",
-    "@docusaurus/preset-classic": "3.9.2",
+    "@docusaurus/core": "3.10.1",
+    "@docusaurus/faster": "3.10.1",
+    "@docusaurus/preset-classic": "3.10.1",
     "@mdx-js/react": "^3.0.0",
     "clsx": "^2.0.0",
     "prism-react-renderer": "^2.3.0",
@@ -24,10 +25,11 @@
     "react-dom": "^19.0.0"
   },
   "devDependencies": {
-    "@docusaurus/module-type-aliases": "3.9.2",
-    "@docusaurus/tsconfig": "3.9.2",
-    "@docusaurus/types": "3.9.2",
-    "typescript": "~5.6.2"
+    "@docusaurus/module-type-aliases": "3.10.1",
+    "@docusaurus/tsconfig": "3.10.1",
+    "@docusaurus/types": "3.10.1",
+    "@types/react": "^19.0.0",
+    "typescript": "~6.0.2"
   },
   "browserslist": {
     "production": [

package/templates/classic-typescript/tsconfig.json

@@ -1,8 +1,12 @@
+// This file is not used by "docusaurus start/build" commands.
+// It is here to improve your IDE experience (type-checking, autocompletion...),
+// and can also run the package.json "typecheck" script manually.
 {
-  // This file is not used in compilation. It is here just for a nice editor experience.
   "extends": "@docusaurus/tsconfig",
   "compilerOptions": {
-    "baseUrl": "."
+    "baseUrl": ".",
+    "ignoreDeprecations": "6.0",
+    "strict": true
   },
   "exclude": [".docusaurus", "build"]
 }

package/templates/shared/blog/{2019-05-28-first-blog-post.md → 2019-05-28-first-blog-post.mdx}

@@ -7,6 +7,6 @@ tags: [hola, docusaurus]
 
 Lorem ipsum dolor sit amet...
 
-<!-- truncate -->
+{/* truncate */}
 
 ...consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet

package/templates/shared/blog/{2019-05-29-long-blog-post.md → 2019-05-29-long-blog-post.mdx}

@@ -7,9 +7,9 @@ tags: [hello, docusaurus]
 
 This is the summary of a very long blog post,
 
-Use a `<!--` `truncate` `-->` comment to limit blog post size in the list view.
+Use a `{/*` `truncate` `*/}` comment to limit blog post size in the list view.
 
-<!-- truncate -->
+{/* truncate */}
 
 Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
 

package/templates/shared/blog/2021-08-26-welcome/{index.md → index.mdx}

@@ -9,7 +9,7 @@ tags: [facebook, hello, docusaurus]
 
 Here are a few tips you might find useful.
 
-<!-- truncate -->
+{/* truncate */}
 
 Simply add Markdown files (or folders) to the `blog` directory.
 

package/templates/shared/docs/tutorial-basics/{congratulations.md → congratulations.mdx}

@@ -8,7 +8,7 @@ You have just learned the **basics of Docusaurus** and made some changes to the
 
 Docusaurus has **much more to offer**!
 
-Have **5 more minutes**? Take a look at **[versioning](../tutorial-extras/manage-docs-versions.md)** and **[i18n](../tutorial-extras/translate-your-site.md)**.
+Have **5 more minutes**? Take a look at **[versioning](../tutorial-extras/manage-docs-versions.mdx)** and **[i18n](../tutorial-extras/translate-your-site.mdx)**.
 
 Anything **unclear** or **buggy** in this tutorial? [Please report it!](https://github.com/facebook/docusaurus/discussions/4610)
 

package/templates/shared/docs/tutorial-basics/markdown-features.mdx

@@ -20,9 +20,25 @@ slug: /my-custom-url
 ---
 // highlight-end
 
-## Markdown heading
+Markdown content
+```
+
+## Headings {/* #my-heading-id */}
+
+Markdown headings are supported using the standard “#” syntax and are automatically added to the table of contents. The number of `#` corresponds to the heading level.
+
+```md
+## Headings
 
-Markdown text with [links](./hello.md)
+My text
+```
+
+### Heading Ids {/* #my-custom-id */}
+
+Add `{/* #my-custom-id */}` after the heading text to assign it an explicit anchor id, used for linking.
+
+```md
+### Heading Ids {/_ #my-custom-id _/}
 ```
 
 ## Links
@@ -34,10 +50,10 @@ Let's see how to [Create a page](/create-a-page).
 ```
 
 ```md
-Let's see how to [Create a page](./create-a-page.md).
+Let's see how to [Create a page](./create-a-page.mdx).
 ```
 
-**Result:** Let's see how to [Create a page](./create-a-page.md).
+**Result:** Let's see how to [Create a page](./create-a-page.mdx).
 
 ## Images
 
@@ -80,26 +96,26 @@ function HelloDocusaurus() {
 Docusaurus has a special syntax to create admonitions and callouts:
 
 ```md
-:::tip My tip
+:::tip[My tip]
 
 Use this awesome feature option
 
 :::
 
-:::danger Take care
+:::danger[Take care]
 
 This action is dangerous
 
 :::
 ```
 
-:::tip My tip
+:::tip[My tip]
 
 Use this awesome feature option
 
 :::
 
-:::danger Take care
+:::danger[Take care]
 
 This action is dangerous