@docusaurus/utils 3.4.0 → 3.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/utils",
-  "version": "3.4.0",
+  "version": "3.5.0",
   "description": "Node utility functions for Docusaurus packages.",
   "main": "./lib/index.js",
   "types": "./lib/index.d.ts",
@@ -18,8 +18,8 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@docusaurus/logger": "3.4.0",
-    "@docusaurus/utils-common": "3.4.0",
+    "@docusaurus/logger": "3.5.0",
+    "@docusaurus/utils-common": "3.5.0",
     "@svgr/webpack": "^8.1.0",
     "escape-string-regexp": "^4.0.0",
     "file-loader": "^6.2.0",
@@ -43,7 +43,7 @@
     "node": ">=18.0"
   },
   "devDependencies": {
-    "@docusaurus/types": "3.4.0",
+    "@docusaurus/types": "3.5.0",
     "@types/dedent": "^0.7.0",
     "@types/github-slugger": "^1.3.0",
     "@types/micromatch": "^4.0.2",
@@ -59,5 +59,5 @@
       "optional": true
     }
   },
-  "gitHead": "49e9a2143274a8dd795659b417b470bc42abbd6e"
+  "gitHead": "cb5829f3c34b26d798b869e38ee25073488140bd"
 }

package/src/dataFileUtils.ts

@@ -43,30 +43,28 @@ export async function getDataFilePath({
 }
 
 /**
- * Looks up for a data file in the content paths, returns the object validated
- * and normalized according to the `validate` callback.
+ * Looks up for a data file in the content paths
+ * Favors the localized content path over the base content path
+ * Currently supports Yaml and JSON data files
+ * It is the caller responsibility to validate and normalize the resulting data
  *
  * @returns `undefined` when file not found
- * @throws Throws when validation fails, displaying a helpful context message.
+ * @throws Throws when data file can't be parsed
  */
-export async function getDataFileData<T>(
-  params: DataFileParams & {
-    /** Used for the "The X file looks invalid" message. */
-    fileType: string;
-  },
-  validate: (content: unknown) => T,
-): Promise<T | undefined> {
+export async function readDataFile(params: DataFileParams): Promise<unknown> {
   const filePath = await getDataFilePath(params);
   if (!filePath) {
     return undefined;
   }
   try {
     const contentString = await fs.readFile(filePath, {encoding: 'utf8'});
-    const unsafeContent = Yaml.load(contentString);
-    return validate(unsafeContent);
+    return Yaml.load(contentString);
   } catch (err) {
-    logger.error`The ${params.fileType} file at path=${filePath} looks invalid.`;
-    throw err;
+    const msg = logger.interpolate`The file at path=${path.relative(
+      process.cwd(),
+      filePath,
+    )} looks invalid (not Yaml nor JSON).`;
+    throw new Error(msg, {cause: err as Error});
   }
 }
 

package/src/index.ts

@@ -109,7 +109,7 @@ export {escapeShellArg} from './shellUtils';
 export {loadFreshModule} from './moduleUtils';
 export {
   getDataFilePath,
-  getDataFileData,
+  readDataFile,
   getContentPathList,
   findFolderContainingFile,
   getFolderContainingFile,

package/src/markdownUtils.ts

@@ -70,9 +70,9 @@ export function escapeMarkdownHeadingIds(content: string): string {
 export function unwrapMdxCodeBlocks(content: string): string {
   // We only support 3/4 backticks on purpose, should be good enough
   const regexp3 =
-    /(?<begin>^|\r?\n)```(?<spaces>\x20*)mdx-code-block\r?\n(?<children>.*?)\r?\n```(?<end>\r?\n|$)/gs;
+    /(?<begin>^|\r?\n)(?<indentStart>\x20*)```(?<spaces>\x20*)mdx-code-block\r?\n(?<children>.*?)\r?\n(?<indentEnd>\x20*)```(?<end>\r?\n|$)/gs;
   const regexp4 =
-    /(?<begin>^|\r?\n)````(?<spaces>\x20*)mdx-code-block\r?\n(?<children>.*?)\r?\n````(?<end>\r?\n|$)/gs;
+    /(?<begin>^|\r?\n)(?<indentStart>\x20*)````(?<spaces>\x20*)mdx-code-block\r?\n(?<children>.*?)\r?\n(?<indentEnd>\x20*)````(?<end>\r?\n|$)/gs;
 
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   const replacer = (substring: string, ...args: any[]) => {

package/src/tags.ts

@@ -28,7 +28,7 @@ export type TagsPluginOptions = {
   // TODO allow option tags later? | TagsFile;
   /** Path to the tags file. */
   tags: string | false | null | undefined;
-  /** The behavior of Docusaurus when it found inline tags. */
+  /** The behavior of Docusaurus when it finds inline tags. */
   onInlineTags: 'ignore' | 'log' | 'warn' | 'throw';
 };
 
@@ -45,6 +45,7 @@ export type TagsListItem = Tag & {
 /** What the tag's own page should know about the tag. */
 export type TagModule = TagsListItem & {
   /** The tags list page's permalink. */
+  // TODO move this global value to a shared docs/blog bundle
   allTagsPath: string;
   /** Is this tag unlisted? (when it only contains unlisted items) */
   unlisted: boolean;