@docusaurus/core 4.0.0-canary-6972 → 4.0.0-canary-6973

package/lib/commands/cli.js

@@ -141,7 +141,7 @@ async function createCLIProgram({ cli, cliArgs, siteDir, config, }) {
     cli
         .command('write-heading-ids [siteDir] [files...]')
         .description('Generate heading ids in Markdown content.')
-        .option('--syntax <syntax>', 'heading ID syntax: "classic" ({#id}) or "mdx-comment" ({/* #id */}) (default: "classic")')
+        .addOption(new commander_1.Option('--syntax <syntax>', 'heading ID syntax: "classic" ({#id}) or "mdx-comment" ({/* #id */}) (default: "classic" for files compiled as CommonMark, "mdx-comment" for files compiled as MDX)').choices(writeHeadingIds_1.HeadingIdSyntaxes))
         .option('--migrate', 'migrate existing heading IDs to the target --syntax, if they are using a different syntax (default: false)')
         .option('--overwrite', 'overwrite existing heading IDs, re-generate them from the heading text (default: false)')
         .option('--maintain-case', "keep the headings' casing, otherwise make all lowercase (default: false)")

package/lib/commands/writeHeadingIds.d.ts

@@ -5,4 +5,5 @@
  * LICENSE file in the root directory of this source tree.
  */
 import { type WriteHeadingIDOptions } from '@docusaurus/utils';
+export declare const HeadingIdSyntaxes: ["classic", "mdx-comment"];
 export declare function writeHeadingIds(siteDirParam?: string, files?: string[], options?: WriteHeadingIDOptions): Promise<void>;

package/lib/commands/writeHeadingIds.js

@@ -6,29 +6,37 @@
  * LICENSE file in the root directory of this source tree.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.HeadingIdSyntaxes = void 0;
 exports.writeHeadingIds = writeHeadingIds;
 const tslib_1 = require("tslib");
+const node_path_1 = tslib_1.__importDefault(require("node:path"));
 const logger_1 = tslib_1.__importDefault(require("@docusaurus/logger"));
 const utils_1 = require("@docusaurus/utils");
 const glob_1 = require("@docusaurus/glob");
 const fs_1 = require("@docusaurus/fs");
 const site_1 = require("../server/site");
 const init_1 = require("../server/plugins/init");
-function inferFallbackSyntax(_filepath) {
-    // TODO Docusaurus v4 - infer the syntax based on the file extensions?
-    // This is not ideal because we have many ways to define the syntax
-    // (front matter "format", siteConfig.markdown.format etc...)
-    // but probably good enough for now
-    // Until then, we default to the classic syntax
-    // The mdx-comment syntax is opt-in
-    return 'classic';
-}
-function getHeadingIdSyntax(filepath, options) {
-    return options?.syntax ?? inferFallbackSyntax(filepath);
+exports.HeadingIdSyntaxes = [
+    'classic',
+    'mdx-comment',
+];
+/**
+ * Infer the heading ID syntax that compiles for a given file:
+ * - `classic` ({#id}) for files compiled as CommonMark
+ * - `mdx-comment` ({/* #id * /}) for files compiled as MDX
+ *
+ * The front matter `format` is not taken into account, but users can still
+ * use the `--syntax` option to target a specific syntax.
+ */
+function inferFallbackSyntax(filepath, markdownConfig) {
+    const isCommonMark = markdownConfig.format === 'detect'
+        ? node_path_1.default.extname(filepath) === '.md'
+        : markdownConfig.format === 'md';
+    return isCommonMark ? 'classic' : 'mdx-comment';
 }
-async function transformMarkdownFile(filepath, options) {
+async function transformMarkdownFile(filepath, markdownConfig, options) {
     const content = await fs_1.fs.readFile(filepath, 'utf8');
-    const syntax = getHeadingIdSyntax(filepath, options);
+    const syntax = options.syntax ?? inferFallbackSyntax(filepath, markdownConfig);
     const updatedContent = (0, utils_1.writeMarkdownHeadingId)(content, {
         ...options,
         syntax,
@@ -49,16 +57,14 @@ async function globMarkdownFiles(patterns) {
  * not belong to a content plugin. For example ./README.md should not be
  * transformed
  */
-async function getPathsToWatch(siteDir) {
-    const context = await (0, site_1.loadContext)({ siteDir });
+async function getPathsToWatch(context) {
     const plugins = await (0, init_1.initPlugins)(context);
     return plugins.flatMap((plugin) => plugin.getPathsToWatch?.() ?? []);
 }
-// TODO Docusaurus v4 - Upgrade commander, use choices() API?
+// The CLI already validates --syntax, but not the programmatic API
 function validateOptions(options) {
-    const validSyntaxValues = ['classic', 'mdx-comment'];
-    if (options.syntax && !validSyntaxValues.includes(options.syntax)) {
-        throw new Error(`Invalid --syntax value "${options.syntax}". Valid values: ${validSyntaxValues.join(', ')}`);
+    if (options.syntax && !exports.HeadingIdSyntaxes.includes(options.syntax)) {
+        throw new Error(`Invalid --syntax value "${options.syntax}". Valid values: ${exports.HeadingIdSyntaxes.join(', ')}`);
     }
     if (options.overwrite && options.migrate) {
         throw new Error("Options --overwrite and --migrate cannot be used together.\nThe --overwrite already re-generates IDs in the target syntax, so the --migrate option wouldn't have any effect.");
@@ -67,13 +73,14 @@ function validateOptions(options) {
 async function writeHeadingIds(siteDirParam = '.', files = [], options = {}) {
     validateOptions(options);
     const siteDir = await (0, fs_1.realpath)(siteDirParam);
-    const patterns = files.length ? files : await getPathsToWatch(siteDir);
+    const context = await (0, site_1.loadContext)({ siteDir });
+    const patterns = files.length ? files : await getPathsToWatch(context);
     const markdownFiles = await globMarkdownFiles(patterns);
     if (markdownFiles.length === 0) {
         logger_1.default.warn `No markdown files found in siteDir path=${siteDir} for patterns: ${patterns}`;
         return;
     }
-    const result = await Promise.all(markdownFiles.map((p) => transformMarkdownFile(p, options)));
+    const result = await Promise.all(markdownFiles.map((p) => transformMarkdownFile(p, context.siteConfig.markdown, options)));
     const pathsModified = result.filter(Boolean);
     if (pathsModified.length) {
         logger_1.default.success `Heading ids added to Markdown files (number=${`${pathsModified.length}/${markdownFiles.length}`} files): ${pathsModified}`;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@docusaurus/core",
   "description": "Easy to Maintain Open Source Documentation Websites",
-  "version": "4.0.0-canary-6972",
+  "version": "4.0.0-canary-6973",
   "license": "MIT",
   "publishConfig": {
     "access": "public"
@@ -27,15 +27,15 @@
     "url": "https://github.com/facebook/docusaurus/issues"
   },
   "dependencies": {
-    "@docusaurus/babel": "4.0.0-canary-6972",
-    "@docusaurus/bundler": "4.0.0-canary-6972",
-    "@docusaurus/fs": "4.0.0-canary-6972",
-    "@docusaurus/glob": "4.0.0-canary-6972",
-    "@docusaurus/logger": "4.0.0-canary-6972",
-    "@docusaurus/mdx-loader": "4.0.0-canary-6972",
-    "@docusaurus/utils": "4.0.0-canary-6972",
-    "@docusaurus/utils-common": "4.0.0-canary-6972",
-    "@docusaurus/utils-validation": "4.0.0-canary-6972",
+    "@docusaurus/babel": "4.0.0-canary-6973",
+    "@docusaurus/bundler": "4.0.0-canary-6973",
+    "@docusaurus/fs": "4.0.0-canary-6973",
+    "@docusaurus/glob": "4.0.0-canary-6973",
+    "@docusaurus/logger": "4.0.0-canary-6973",
+    "@docusaurus/mdx-loader": "4.0.0-canary-6973",
+    "@docusaurus/utils": "4.0.0-canary-6973",
+    "@docusaurus/utils-common": "4.0.0-canary-6973",
+    "@docusaurus/utils-validation": "4.0.0-canary-6973",
     "@rspack/core": "^2.2.3",
     "@rspack/dev-server": "^2.2.1",
     "boxen": "^9.0.0",
@@ -68,8 +68,8 @@
     "webpack-merge": "^6.0.1"
   },
   "devDependencies": {
-    "@docusaurus/module-type-aliases": "4.0.0-canary-6972",
-    "@docusaurus/types": "4.0.0-canary-6972",
+    "@docusaurus/module-type-aliases": "4.0.0-canary-6973",
+    "@docusaurus/types": "4.0.0-canary-6973",
     "@total-typescript/shoehorn": "^0.1.2",
     "@types/escape-html": "^1.0.4",
     "@types/history": "^4.7.11",