@docusaurus/utils 0.0.0-4347 → 0.0.0-4355

package/lib/pathUtils.js

@@ -6,8 +6,10 @@
  * LICENSE file in the root directory of this source tree.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.shortName = exports.isNameTooLong = void 0;
+exports.escapePath = exports.aliasedSitePath = exports.toMessageRelativeFilePath = exports.posixPath = exports.shortName = exports.isNameTooLong = void 0;
+const tslib_1 = require("tslib");
 // Based on https://github.com/gatsbyjs/gatsby/pull/21518/files
+const path_1 = (0, tslib_1.__importDefault)(require("path"));
 // MacOS (APFS) and Windows (NTFS) filename length limit = 255 chars, Others = 255 bytes
 const MAX_PATH_SEGMENT_CHARS = 255;
 const MAX_PATH_SEGMENT_BYTES = 255;
@@ -31,4 +33,64 @@ const shortName = (str) => {
         .toString();
 };
 exports.shortName = shortName;
+/**
+ * Convert Windows backslash paths to posix style paths.
+ * E.g: endi\lie -> endi/lie
+ *
+ * Returns original path if the posix counterpart is not valid Windows path.
+ * This makes the legacy code that uses posixPath safe; but also makes it less
+ * useful when you actually want a path with forward slashes (e.g. for URL)
+ *
+ * Adopted from https://github.com/sindresorhus/slash/blob/main/index.js
+ */
+function posixPath(str) {
+    const isExtendedLengthPath = /^\\\\\?\\/.test(str);
+    // Forward slashes are only valid Windows paths when they don't contain non-ascii characters.
+    // eslint-disable-next-line no-control-regex
+    const hasNonAscii = /[^\u0000-\u0080]+/.test(str);
+    if (isExtendedLengthPath || hasNonAscii) {
+        return str;
+    }
+    return str.replace(/\\/g, '/');
+}
+exports.posixPath = posixPath;
+// When you want to display a path in a message/warning/error,
+// it's more convenient to:
+// - make it relative to cwd()
+// - convert to posix (ie not using windows \ path separator)
+// This way, Jest tests can run more reliably on any computer/CI
+// on both Unix/Windows
+// For Windows users this is not perfect (as they see / instead of \) but it's probably good enough
+function toMessageRelativeFilePath(filePath) {
+    return posixPath(path_1.default.relative(process.cwd(), filePath));
+}
+exports.toMessageRelativeFilePath = toMessageRelativeFilePath;
+/**
+ * Alias filepath relative to site directory, very useful so that we
+ * don't expose user's site structure.
+ * Example: some/path/to/website/docs/foo.md -> @site/docs/foo.md
+ */
+function aliasedSitePath(filePath, siteDir) {
+    const relativePath = posixPath(path_1.default.relative(siteDir, filePath));
+    // Cannot use path.join() as it resolves '../' and removes
+    // the '@site'. Let webpack loader resolve it.
+    return `@site/${relativePath}`;
+}
+exports.aliasedSitePath = aliasedSitePath;
+/**
+ * When you have a path like C:\X\Y
+ * It is not safe to use directly when generating code
+ * For example, this would fail due to unescaped \: `<img src={require('${filePath}')} />`
+ * But this would work: `<img src={require('${escapePath(filePath)}')} />`
+ *
+ * posixPath can't be used in all cases, because forward slashes are only valid
+ * Windows paths when they don't contain non-ascii characters, and posixPath
+ * doesn't escape those that fail to be converted.
+ */
+function escapePath(str) {
+    const escaped = JSON.stringify(str);
+    // Remove the " around the json string;
+    return escaped.substring(1, escaped.length - 1);
+}
+exports.escapePath = escapePath;
 //# sourceMappingURL=pathUtils.js.map

package/lib/pathUtils.js.map

@@ -1 +1 @@
-{"version":3,"file":"pathUtils.js","sourceRoot":"","sources":["../src/pathUtils.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;AAEH,+DAA+D;AAE/D,wFAAwF;AACxF,MAAM,sBAAsB,GAAG,GAAG,CAAC;AACnC,MAAM,sBAAsB,GAAG,GAAG,CAAC;AACnC,0EAA0E;AAC1E,MAAM,mBAAmB,GAAG,EAAE,CAAC;AAE/B,MAAM,OAAO,GAAG,OAAO,CAAC,QAAQ,KAAK,QAAQ,CAAC;AAC9C,MAAM,SAAS,GAAG,OAAO,CAAC,QAAQ,KAAK,OAAO,CAAC;AAExC,MAAM,aAAa,GAAG,CAAC,GAAW,EAAW,EAAE,CACpD,OAAO,IAAI,SAAS;IAClB,CAAC,CAAC,GAAG,CAAC,MAAM,GAAG,mBAAmB,GAAG,sBAAsB,CAAC,oEAAoE;IAChI,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,MAAM,GAAG,mBAAmB,GAAG,sBAAsB,CAAC,CAAC,oBAAoB;AAHrF,QAAA,aAAa,iBAGmD;AAEtE,MAAM,SAAS,GAAG,CAAC,GAAW,EAAU,EAAE;IAC/C,IAAI,OAAO,IAAI,SAAS,EAAE;QACxB,MAAM,gBAAgB,GAAG,GAAG,CAAC,MAAM,GAAG,sBAAsB,CAAC;QAC7D,OAAO,GAAG,CAAC,KAAK,CACd,CAAC,EACD,GAAG,CAAC,MAAM,GAAG,gBAAgB,GAAG,mBAAmB,GAAG,CAAC,CACxD,CAAC;KACH;IACD,MAAM,SAAS,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACnC,MAAM,gBAAgB,GACpB,MAAM,CAAC,UAAU,CAAC,SAAS,CAAC,GAAG,sBAAsB,CAAC;IACxD,OAAO,SAAS;SACb,KAAK,CACJ,CAAC,EACD,MAAM,CAAC,UAAU,CAAC,SAAS,CAAC,GAAG,gBAAgB,GAAG,mBAAmB,GAAG,CAAC,CAC1E;SACA,QAAQ,EAAE,CAAC;AAChB,CAAC,CAAC;AAjBW,QAAA,SAAS,aAiBpB"}
+{"version":3,"file":"pathUtils.js","sourceRoot":"","sources":["../src/pathUtils.ts"],"names":[],"mappings":"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"}

package/lib/tags.js

@@ -8,7 +8,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.groupTaggedItems = exports.normalizeFrontMatterTags = exports.normalizeFrontMatterTag = void 0;
 const lodash_1 = require("lodash");
-const normalizeUrl_1 = require("./normalizeUrl");
+const urlUtils_1 = require("./urlUtils");
 function normalizeFrontMatterTag(tagsPath, frontMatterTag) {
     function toTagObject(tagString) {
         return {
@@ -21,7 +21,7 @@ function normalizeFrontMatterTag(tagsPath, frontMatterTag) {
         // note: we always apply tagsPath on purpose
         // for versioned docs, v1/doc.md and v2/doc.md tags with custom permalinks don't lead to the same created page
         // tagsPath is different for each doc version
-        return (0, normalizeUrl_1.normalizeUrl)([tagsPath, permalink]);
+        return (0, urlUtils_1.normalizeUrl)([tagsPath, permalink]);
     }
     const tag = typeof frontMatterTag === 'string'
         ? toTagObject(frontMatterTag)

package/lib/tags.js.map

@@ -1 +1 @@
-{"version":3,"file":"tags.js","sourceRoot":"","sources":["../src/tags.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;AAEH,mCAA+C;AAC/C,iDAA4C;AAS5C,SAAgB,uBAAuB,CACrC,QAAgB,EAChB,cAA8B;IAE9B,SAAS,WAAW,CAAC,SAAiB;QACpC,OAAO;YACL,KAAK,EAAE,SAAS;YAChB,SAAS,EAAE,IAAA,kBAAS,EAAC,SAAS,CAAC;SAChC,CAAC;IACJ,CAAC;IAED,0DAA0D;IAC1D,SAAS,qBAAqB,CAAC,SAAiB;QAC9C,4CAA4C;QAC5C,8GAA8G;QAC9G,6CAA6C;QAC7C,OAAO,IAAA,2BAAY,EAAC,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC,CAAC;IAC7C,CAAC;IAED,MAAM,GAAG,GACP,OAAO,cAAc,KAAK,QAAQ;QAChC,CAAC,CAAC,WAAW,CAAC,cAAc,CAAC;QAC7B,CAAC,CAAC,cAAc,CAAC;IAErB,OAAO;QACL,KAAK,EAAE,GAAG,CAAC,KAAK;QAChB,SAAS,EAAE,qBAAqB,CAAC,GAAG,CAAC,SAAS,CAAC;KAChD,CAAC;AACJ,CAAC;AA5BD,0DA4BC;AAED,SAAgB,wBAAwB,CACtC,QAAgB,EAChB,eAA6C;;IAE7C,MAAM,IAAI,GACR,MAAA,eAAe,aAAf,eAAe,uBAAf,eAAe,CAAE,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,uBAAuB,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC,mCAAI,EAAE,CAAC;IAE9E,OAAO,IAAA,eAAM,EAAC,IAAI,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;AAC9C,CAAC;AARD,4DAQC;AAOD,mEAAmE;AACnE,kFAAkF;AAClF,yDAAyD;AACzD,sGAAsG;AACtG,4EAA4E;AAC5E,SAAgB,gBAAgB,CAC9B,KAAa,EACb,WAAkC;IAElC,MAAM,MAAM,GAA0C,EAAE,CAAC;IAEzD,SAAS,aAAa,CAAC,IAAU,EAAE,GAAQ;;QACzC,0BAA0B;QAC1B,+HAA+H;QAC/H,oCAAoC;QACpC,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC,GAAG,MAAA,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC,mCAAI;YAC/C,GAAG;YACH,KAAK,EAAE,EAAE;SACV,CAAC;QAEF,oBAAoB;QACpB,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACzC,CAAC;IAED,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,EAAE;QACrB,WAAW,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,CAAC,GAAG,EAAE,EAAE;YAChC,aAAa,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;QAC3B,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,mEAAmE;IACnE,wDAAwD;IACxD,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,EAAE;QACtC,KAAK,CAAC,KAAK,GAAG,IAAA,aAAI,EAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IAClC,CAAC,CAAC,CAAC;IAEH,OAAO,MAAM,CAAC;AAChB,CAAC;AAhCD,4CAgCC"}
+{"version":3,"file":"tags.js","sourceRoot":"","sources":["../src/tags.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;AAEH,mCAA+C;AAC/C,yCAAwC;AASxC,SAAgB,uBAAuB,CACrC,QAAgB,EAChB,cAA8B;IAE9B,SAAS,WAAW,CAAC,SAAiB;QACpC,OAAO;YACL,KAAK,EAAE,SAAS;YAChB,SAAS,EAAE,IAAA,kBAAS,EAAC,SAAS,CAAC;SAChC,CAAC;IACJ,CAAC;IAED,0DAA0D;IAC1D,SAAS,qBAAqB,CAAC,SAAiB;QAC9C,4CAA4C;QAC5C,8GAA8G;QAC9G,6CAA6C;QAC7C,OAAO,IAAA,uBAAY,EAAC,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC,CAAC;IAC7C,CAAC;IAED,MAAM,GAAG,GACP,OAAO,cAAc,KAAK,QAAQ;QAChC,CAAC,CAAC,WAAW,CAAC,cAAc,CAAC;QAC7B,CAAC,CAAC,cAAc,CAAC;IAErB,OAAO;QACL,KAAK,EAAE,GAAG,CAAC,KAAK;QAChB,SAAS,EAAE,qBAAqB,CAAC,GAAG,CAAC,SAAS,CAAC;KAChD,CAAC;AACJ,CAAC;AA5BD,0DA4BC;AAED,SAAgB,wBAAwB,CACtC,QAAgB,EAChB,eAA6C;;IAE7C,MAAM,IAAI,GACR,MAAA,eAAe,aAAf,eAAe,uBAAf,eAAe,CAAE,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,uBAAuB,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC,mCAAI,EAAE,CAAC;IAE9E,OAAO,IAAA,eAAM,EAAC,IAAI,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;AAC9C,CAAC;AARD,4DAQC;AAOD,mEAAmE;AACnE,kFAAkF;AAClF,yDAAyD;AACzD,sGAAsG;AACtG,4EAA4E;AAC5E,SAAgB,gBAAgB,CAC9B,KAAa,EACb,WAAkC;IAElC,MAAM,MAAM,GAA0C,EAAE,CAAC;IAEzD,SAAS,aAAa,CAAC,IAAU,EAAE,GAAQ;;QACzC,0BAA0B;QAC1B,+HAA+H;QAC/H,oCAAoC;QACpC,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC,GAAG,MAAA,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC,mCAAI;YAC/C,GAAG;YACH,KAAK,EAAE,EAAE;SACV,CAAC;QAEF,oBAAoB;QACpB,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACzC,CAAC;IAED,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,EAAE;QACrB,WAAW,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,CAAC,GAAG,EAAE,EAAE;YAChC,aAAa,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;QAC3B,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,mEAAmE;IACnE,wDAAwD;IACxD,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,EAAE;QACtC,KAAK,CAAC,KAAK,GAAG,IAAA,aAAI,EAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IAClC,CAAC,CAAC,CAAC;IAEH,OAAO,MAAM,CAAC;AAChB,CAAC;AAhCD,4CAgCC"}

package/lib/{normalizeUrl.d.ts → urlUtils.d.ts}

@@ -5,4 +5,5 @@
  * LICENSE file in the root directory of this source tree.
  */
 export declare function normalizeUrl(rawUrls: string[]): string;
-//# sourceMappingURL=normalizeUrl.d.ts.map
+export declare function getEditUrl(fileRelativePath: string, editUrl?: string): string | undefined;
+//# sourceMappingURL=urlUtils.d.ts.map

package/lib/urlUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"urlUtils.d.ts","sourceRoot":"","sources":["../src/urlUtils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,MAAM,CAwEtD;AAED,wBAAgB,UAAU,CACxB,gBAAgB,EAAE,MAAM,EACxB,OAAO,CAAC,EAAE,MAAM,GACf,MAAM,GAAG,SAAS,CAKpB"}

package/lib/{normalizeUrl.js → urlUtils.js}

@@ -6,7 +6,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.normalizeUrl = void 0;
+exports.getEditUrl = exports.normalizeUrl = void 0;
 function normalizeUrl(rawUrls) {
     const urls = [...rawUrls];
     const resultArray = [];
@@ -64,4 +64,11 @@ function normalizeUrl(rawUrls) {
     return str;
 }
 exports.normalizeUrl = normalizeUrl;
-//# sourceMappingURL=normalizeUrl.js.map
+function getEditUrl(fileRelativePath, editUrl) {
+    return editUrl
+        ? // Don't use posixPath for this: we need to force a forward slash path
+            normalizeUrl([editUrl, fileRelativePath.replace(/\\/g, '/')])
+        : undefined;
+}
+exports.getEditUrl = getEditUrl;
+//# sourceMappingURL=urlUtils.js.map

package/lib/urlUtils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"urlUtils.js","sourceRoot":"","sources":["../src/urlUtils.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;AAEH,SAAgB,YAAY,CAAC,OAAiB;IAC5C,MAAM,IAAI,GAAG,CAAC,GAAG,OAAO,CAAC,CAAC;IAC1B,MAAM,WAAW,GAAG,EAAE,CAAC;IAEvB,IAAI,gBAAgB,GAAG,KAAK,CAAC;IAC7B,IAAI,cAAc,GAAG,KAAK,CAAC;IAE3B,2EAA2E;IAC3E,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,cAAc,CAAC,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE;QACpD,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,EAAE,CAAC;QAC3B,IAAI,CAAC,CAAC,CAAC,GAAG,KAAK,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;KAC3B;IAED,2DAA2D;IAC3D,gCAAgC;IAChC,MAAM,WAAW,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC;IACvE,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,eAAe,EAAE,WAAW,CAAC,CAAC;IAExD,2BAA2B;IAC3B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE;QACpC,IAAI,SAAS,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;QAExB,IAAI,OAAO,SAAS,KAAK,QAAQ,EAAE;YACjC,MAAM,IAAI,SAAS,CAAC,kCAAkC,OAAO,SAAS,EAAE,CAAC,CAAC;SAC3E;QAED,IAAI,SAAS,KAAK,EAAE,EAAE;YACpB,IAAI,CAAC,KAAK,IAAI,CAAC,MAAM,GAAG,CAAC,IAAI,cAAc,EAAE;gBAC3C,WAAW,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;aACvB;YACD,2BAA2B;YAC3B,SAAS;SACV;QAED,IAAI,SAAS,KAAK,GAAG,EAAE;YACrB,IAAI,CAAC,GAAG,CAAC,EAAE;gBACT,kEAAkE;gBAClE,SAAS,GAAG,SAAS,CAAC,OAAO,CAC3B,OAAO;gBACP,oFAAoF;gBACpF,SAAS,CAAC,CAAC,CAAC,KAAK,GAAG,IAAI,CAAC,gBAAgB,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CACrD,CAAC;aACH;YAED,cAAc,GAAG,SAAS,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC,KAAK,GAAG,CAAC;YACzD,+DAA+D;YAC/D,2EAA2E;YAC3E,SAAS,GAAG,SAAS,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;SACxE;QAED,gBAAgB,GAAG,IAAI,CAAC;QACxB,WAAW,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;KAC7B;IAED,IAAI,GAAG,GAAG,WAAW,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAChC,0DAA0D;IAC1D,iDAAiD;IAEjD,mDAAmD;IACnD,GAAG,GAAG,GAAG,CAAC,OAAO,CAAC,iBAAiB,EAAE,IAAI,CAAC,CAAC;IAE3C,kCAAkC;IAClC,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC7B,GAAG,GAAG,KAAK,CAAC,KAAK,EAAE,GAAG,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAEtE,wEAAwE;IACxE,GAAG,GAAG,GAAG,CAAC,OAAO,CAAC,cAAc,EAAE,IAAI,CAAC,CAAC;IAExC,uDAAuD;IACvD,GAAG,GAAG,GAAG,CAAC,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;IAEhC,OAAO,GAAG,CAAC;AACb,CAAC;AAxED,oCAwEC;AAED,SAAgB,UAAU,CACxB,gBAAwB,EACxB,OAAgB;IAEhB,OAAO,OAAO;QACZ,CAAC,CAAC,sEAAsE;YACtE,YAAY,CAAC,CAAC,OAAO,EAAE,gBAAgB,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,CAAC;QAC/D,CAAC,CAAC,SAAS,CAAC;AAChB,CAAC;AARD,gCAQC"}

package/lib/webpackUtils.js

@@ -9,7 +9,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.getFileLoaderUtils = void 0;
 const tslib_1 = require("tslib");
 const path_1 = (0, tslib_1.__importDefault)(require("path"));
-const escapePath_1 = require("./escapePath");
+const pathUtils_1 = require("./pathUtils");
 const constants_1 = require("./constants");
 // Inspired by https://github.com/gatsbyjs/gatsby/blob/8e6e021014da310b9cc7d02e58c9b3efe938c665/packages/gatsby/src/utils/webpack-utils.ts#L447
 function getFileLoaderUtils() {
@@ -37,8 +37,8 @@ function getFileLoaderUtils() {
         // Maybe with the ideal image plugin, all md images should be "ideal"?
         // This is used to force url-loader+file-loader on markdown images
         // https://webpack.js.org/concepts/loaders/#inline
-        inlineMarkdownImageFileLoader: `!${(0, escapePath_1.escapePath)(require.resolve('url-loader'))}?limit=${urlLoaderLimit}&name=${fileLoaderFileName('images')}&fallback=${(0, escapePath_1.escapePath)(require.resolve('file-loader'))}!`,
-        inlineMarkdownLinkFileLoader: `!${(0, escapePath_1.escapePath)(require.resolve('file-loader'))}?name=${fileLoaderFileName('files')}!`,
+        inlineMarkdownImageFileLoader: `!${(0, pathUtils_1.escapePath)(require.resolve('url-loader'))}?limit=${urlLoaderLimit}&name=${fileLoaderFileName('images')}&fallback=${(0, pathUtils_1.escapePath)(require.resolve('file-loader'))}!`,
+        inlineMarkdownLinkFileLoader: `!${(0, pathUtils_1.escapePath)(require.resolve('file-loader'))}?name=${fileLoaderFileName('files')}!`,
     };
     const rules = {
         /**

package/lib/webpackUtils.js.map

@@ -1 +1 @@
-{"version":3,"file":"webpackUtils.js","sourceRoot":"","sources":["../src/webpackUtils.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"webpackUtils.js","sourceRoot":"","sources":["../src/webpackUtils.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/utils",
-  "version": "0.0.0-4347",
+  "version": "0.0.0-4355",
   "description": "Node utility functions for Docusaurus packages.",
   "main": "./lib/index.js",
   "types": "./lib/index.d.ts",
@@ -18,15 +18,15 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@docusaurus/logger": "0.0.0-4347",
+    "@docusaurus/logger": "0.0.0-4355",
     "@mdx-js/runtime": "^1.6.22",
     "@svgr/webpack": "^6.0.0",
-    "escape-string-regexp": "^4.0.0",
     "file-loader": "^6.2.0",
     "fs-extra": "^10.0.0",
     "github-slugger": "^1.4.0",
     "globby": "^11.0.4",
     "gray-matter": "^4.0.3",
+    "js-yaml": "^4.0.0",
     "lodash": "^4.17.20",
     "micromatch": "^4.0.4",
     "remark-mdx-remove-exports": "^1.6.22",
@@ -39,7 +39,7 @@
     "node": ">=14"
   },
   "devDependencies": {
-    "@docusaurus/types": "0.0.0-4347",
+    "@docusaurus/types": "0.0.0-4355",
     "@types/dedent": "^0.7.0",
     "@types/github-slugger": "^1.3.0",
     "@types/micromatch": "^4.0.2",
@@ -52,5 +52,5 @@
     "react-dom": "*",
     "webpack": "5.x"
   },
-  "gitHead": "12d0a21340f5e0dff5ffe7c3699f3851c8b85ac0"
+  "gitHead": "4ad639a600a7aa5415733d798ed53a5a99ac7da0"
 }

package/src/dataFileUtils.ts

@@ -0,0 +1,93 @@
+/**
+ * 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 fs from 'fs-extra';
+import Yaml from 'js-yaml';
+import path from 'path';
+import {findAsyncSequential} from './index';
+import type {ContentPaths} from './markdownLinks';
+import logger from '@docusaurus/logger';
+
+type DataFileParams = {
+  filePath: string;
+  contentPaths: ContentPaths;
+};
+
+export async function getDataFilePath({
+  filePath,
+  contentPaths,
+}: DataFileParams): Promise<string | undefined> {
+  // Loads a localized data file in priority
+  const contentPath = await findFolderContainingFile(
+    getContentPathList(contentPaths),
+    filePath,
+  );
+  if (contentPath) {
+    return path.join(contentPath, filePath);
+  }
+  return undefined;
+}
+
+/**
+ * Looks up for a data file in the content paths, returns the normalized object.
+ * Throws when validation fails; returns undefined when file not found
+ */
+export async function getDataFileData<T>(
+  params: DataFileParams & {fileType: string},
+  validate: (content: unknown) => T,
+): Promise<T | undefined> {
+  const filePath = await getDataFilePath(params);
+  if (!filePath) {
+    return undefined;
+  }
+  if (await fs.pathExists(filePath)) {
+    try {
+      const contentString = await fs.readFile(filePath, {encoding: 'utf8'});
+      const unsafeContent = Yaml.load(contentString);
+      return validate(unsafeContent);
+    } catch (e) {
+      // TODO replace later by error cause, see https://v8.dev/features/error-cause
+      logger.error`The ${params.fileType} file at path=${filePath} looks invalid.`;
+      throw e;
+    }
+  }
+  return undefined;
+}
+
+// Order matters: we look in priority in localized folder
+export function getContentPathList(contentPaths: ContentPaths): string[] {
+  return [contentPaths.contentPathLocalized, contentPaths.contentPath];
+}
+
+// return the first folder path in which the file exists in
+export async function findFolderContainingFile(
+  folderPaths: string[],
+  relativeFilePath: string,
+): Promise<string | undefined> {
+  return findAsyncSequential(folderPaths, (folderPath) =>
+    fs.pathExists(path.join(folderPath, relativeFilePath)),
+  );
+}
+
+export async function getFolderContainingFile(
+  folderPaths: string[],
+  relativeFilePath: string,
+): Promise<string> {
+  const maybeFolderPath = await findFolderContainingFile(
+    folderPaths,
+    relativeFilePath,
+  );
+  // should never happen, as the source was read from the FS anyway...
+  if (!maybeFolderPath) {
+    throw new Error(
+      `File "${relativeFilePath}" does not exist in any of these folders:\n- ${folderPaths.join(
+        '\n- ',
+      )}]`,
+    );
+  }
+  return maybeFolderPath;
+}

package/src/index.ts

@@ -8,11 +8,10 @@
 import logger from '@docusaurus/logger';
 import path from 'path';
 import {createHash} from 'crypto';
-import {camelCase, mapValues} from 'lodash';
-import escapeStringRegexp from 'escape-string-regexp';
+import {mapValues} from 'lodash';
 import fs from 'fs-extra';
 import {URL} from 'url';
-import {
+import type {
   ReportingSeverity,
   TranslationFileContent,
   TranslationFile,
@@ -20,30 +19,21 @@ import {
 
 import resolvePathnameUnsafe from 'resolve-pathname';
 
-import {posixPath as posixPathImport} from './posixPath';
 import {simpleHash, docuHash} from './hashUtils';
-import {normalizeUrl} from './normalizeUrl';
 import {DEFAULT_PLUGIN_ID} from './constants';
 
 export * from './constants';
 export * from './mdxUtils';
-export * from './normalizeUrl';
+export * from './urlUtils';
 export * from './tags';
-
-export const posixPath = posixPathImport;
-
 export * from './markdownParser';
 export * from './markdownLinks';
-export * from './escapePath';
 export * from './slugger';
-export {md5Hash, simpleHash, docuHash} from './hashUtils';
-export {
-  Globby,
-  GlobExcludeDefault,
-  createMatcher,
-  createAbsoluteFilePathMatcher,
-} from './globUtils';
+export * from './pathUtils';
+export * from './hashUtils';
+export * from './globUtils';
 export * from './webpackUtils';
+export * from './dataFileUtils';
 
 const fileHash = new Map();
 export async function generate(
@@ -80,18 +70,6 @@ export async function generate(
   }
 }
 
-export function objectWithKeySorted<T>(
-  obj: Record<string, T>,
-): Record<string, T> {
-  // https://github.com/lodash/lodash/issues/1459#issuecomment-460941233
-  return Object.keys(obj)
-    .sort()
-    .reduce((acc: Record<string, T>, key: string) => {
-      acc[key] = obj[key];
-      return acc;
-    }, {});
-}
-
 const indexRE = /(^|.*\/)index\.(md|mdx|js|jsx|ts|tsx)$/i;
 const extRE = /\.(md|mdx|js|jsx|ts|tsx)$/;
 
@@ -113,37 +91,6 @@ export function encodePath(userpath: string): string {
     .join('/');
 }
 
-/**
- * Convert first string character to the upper case.
- * E.g: docusaurus -> Docusaurus
- */
-export function upperFirst(str: string): string {
-  return str ? str.charAt(0).toUpperCase() + str.slice(1) : '';
-}
-
-/**
- * Generate unique React Component Name.
- * E.g: /foo-bar -> FooBar096
- */
-export function genComponentName(pagePath: string): string {
-  if (pagePath === '/') {
-    return 'index';
-  }
-  const pageHash = docuHash(pagePath);
-  return upperFirst(camelCase(pageHash));
-}
-
-// When you want to display a path in a message/warning/error,
-// it's more convenient to:
-// - make it relative to cwd()
-// - convert to posix (ie not using windows \ path separator)
-// This way, Jest tests can run more reliably on any computer/CI
-// on both Unix/Windows
-// For Windows users this is not perfect (as they see / instead of \) but it's probably good enough
-export function toMessageRelativeFilePath(filePath: string): string {
-  return posixPath(path.relative(process.cwd(), filePath));
-}
-
 const chunkNameCache = new Map();
 /**
  * Generate unique chunk name given a module path.
@@ -172,52 +119,6 @@ export function genChunkName(
   return chunkName;
 }
 
-// Too dynamic
-// eslint-disable-next-line @typescript-eslint/explicit-module-boundary-types, @typescript-eslint/no-explicit-any
-export function idx(target: any, keyPaths?: string | (string | number)[]): any {
-  return (
-    target &&
-    keyPaths &&
-    (Array.isArray(keyPaths)
-      ? keyPaths.reduce((obj, key) => obj && obj[key], target)
-      : target[keyPaths])
-  );
-}
-
-/**
- * Given a filepath and dirpath, get the first directory.
- */
-export function getSubFolder(file: string, refDir: string): string | null {
-  const separator = escapeStringRegexp(path.sep);
-  const baseDir = escapeStringRegexp(path.basename(refDir));
-  const regexSubFolder = new RegExp(
-    `${baseDir}${separator}(.*?)${separator}.*`,
-  );
-  const match = regexSubFolder.exec(file);
-  return match && match[1];
-}
-
-/**
- * Alias filepath relative to site directory, very useful so that we
- * don't expose user's site structure.
- * Example: some/path/to/website/docs/foo.md -> @site/docs/foo.md
- */
-export function aliasedSitePath(filePath: string, siteDir: string): string {
-  const relativePath = posixPath(path.relative(siteDir, filePath));
-  // Cannot use path.join() as it resolves '../' and removes
-  // the '@site'. Let webpack loader resolve it.
-  return `@site/${relativePath}`;
-}
-
-export function getEditUrl(
-  fileRelativePath: string,
-  editUrl?: string,
-): string | undefined {
-  return editUrl
-    ? normalizeUrl([editUrl, posixPath(fileRelativePath)])
-    : undefined;
-}
-
 export function isValidPathname(str: string): boolean {
   if (!str.startsWith('/')) {
     return false;
@@ -306,7 +207,7 @@ export function getPluginI18nPath({
   );
 }
 
-export async function mapAsyncSequencial<T, R>(
+export async function mapAsyncSequential<T, R>(
   array: T[],
   action: (t: T) => Promise<R>,
 ): Promise<R[]> {
@@ -332,35 +233,6 @@ export async function findAsyncSequential<T>(
   return undefined;
 }
 
-// return the  first folder path in which the file exists in
-export async function findFolderContainingFile(
-  folderPaths: string[],
-  relativeFilePath: string,
-): Promise<string | undefined> {
-  return findAsyncSequential(folderPaths, (folderPath) =>
-    fs.pathExists(path.join(folderPath, relativeFilePath)),
-  );
-}
-
-export async function getFolderContainingFile(
-  folderPaths: string[],
-  relativeFilePath: string,
-): Promise<string> {
-  const maybeFolderPath = await findFolderContainingFile(
-    folderPaths,
-    relativeFilePath,
-  );
-  // should never happen, as the source was read from the FS anyway...
-  if (!maybeFolderPath) {
-    throw new Error(
-      `File "${relativeFilePath}" does not exist in any of these folders:\n- ${folderPaths.join(
-        '\n- ',
-      )}]`,
-    );
-  }
-  return maybeFolderPath;
-}
-
 export function reportMessage(
   message: string,
   reportingSeverity: ReportingSeverity,
@@ -420,21 +292,3 @@ export function updateTranslationFileMessages(
     })),
   };
 }
-
-// Input: ## Some heading {#some-heading}
-// Output: {text: "## Some heading", id: "some-heading"}
-export function parseMarkdownHeadingId(heading: string): {
-  text: string;
-  id?: string;
-} {
-  const customHeadingIdRegex = /^(.*?)\s*\{#([\w-]+)\}$/;
-  const matches = customHeadingIdRegex.exec(heading);
-  if (matches) {
-    return {
-      text: matches[1],
-      id: matches[2],
-    };
-  } else {
-    return {text: heading, id: undefined};
-  }
-}

package/src/markdownLinks.ts

@@ -6,7 +6,7 @@
  */
 
 import path from 'path';
-import {aliasedSitePath} from './index';
+import {aliasedSitePath} from './pathUtils';
 
 export type ContentPaths = {
   contentPath: string;

package/src/markdownParser.ts

@@ -9,6 +9,24 @@ import logger from '@docusaurus/logger';
 import fs from 'fs-extra';
 import matter from 'gray-matter';
 
+// Input: ## Some heading {#some-heading}
+// Output: {text: "## Some heading", id: "some-heading"}
+export function parseMarkdownHeadingId(heading: string): {
+  text: string;
+  id?: string;
+} {
+  const customHeadingIdRegex = /^(.*?)\s*\{#([\w-]+)\}$/;
+  const matches = customHeadingIdRegex.exec(heading);
+  if (matches) {
+    return {
+      text: matches[1],
+      id: matches[2],
+    };
+  } else {
+    return {text: heading, id: undefined};
+  }
+}
+
 // Hacky way of stripping out import statements from the excerpt
 // TODO: Find a better way to do so, possibly by compiling the Markdown content,
 // stripping out HTML tags and obtaining the first line.

package/src/pathUtils.ts

@@ -7,6 +7,8 @@
 
 // Based on https://github.com/gatsbyjs/gatsby/pull/21518/files
 
+import path from 'path';
+
 // MacOS (APFS) and Windows (NTFS) filename length limit = 255 chars, Others = 255 bytes
 const MAX_PATH_SEGMENT_CHARS = 255;
 const MAX_PATH_SEGMENT_BYTES = 255;
@@ -39,3 +41,66 @@ export const shortName = (str: string): string => {
     )
     .toString();
 };
+
+/**
+ * Convert Windows backslash paths to posix style paths.
+ * E.g: endi\lie -> endi/lie
+ *
+ * Returns original path if the posix counterpart is not valid Windows path.
+ * This makes the legacy code that uses posixPath safe; but also makes it less
+ * useful when you actually want a path with forward slashes (e.g. for URL)
+ *
+ * Adopted from https://github.com/sindresorhus/slash/blob/main/index.js
+ */
+export function posixPath(str: string): string {
+  const isExtendedLengthPath = /^\\\\\?\\/.test(str);
+
+  // Forward slashes are only valid Windows paths when they don't contain non-ascii characters.
+  // eslint-disable-next-line no-control-regex
+  const hasNonAscii = /[^\u0000-\u0080]+/.test(str);
+
+  if (isExtendedLengthPath || hasNonAscii) {
+    return str;
+  }
+  return str.replace(/\\/g, '/');
+}
+
+// When you want to display a path in a message/warning/error,
+// it's more convenient to:
+// - make it relative to cwd()
+// - convert to posix (ie not using windows \ path separator)
+// This way, Jest tests can run more reliably on any computer/CI
+// on both Unix/Windows
+// For Windows users this is not perfect (as they see / instead of \) but it's probably good enough
+export function toMessageRelativeFilePath(filePath: string): string {
+  return posixPath(path.relative(process.cwd(), filePath));
+}
+
+/**
+ * Alias filepath relative to site directory, very useful so that we
+ * don't expose user's site structure.
+ * Example: some/path/to/website/docs/foo.md -> @site/docs/foo.md
+ */
+export function aliasedSitePath(filePath: string, siteDir: string): string {
+  const relativePath = posixPath(path.relative(siteDir, filePath));
+  // Cannot use path.join() as it resolves '../' and removes
+  // the '@site'. Let webpack loader resolve it.
+  return `@site/${relativePath}`;
+}
+
+/**
+ * When you have a path like C:\X\Y
+ * It is not safe to use directly when generating code
+ * For example, this would fail due to unescaped \: `<img src={require('${filePath}')} />`
+ * But this would work: `<img src={require('${escapePath(filePath)}')} />`
+ *
+ * posixPath can't be used in all cases, because forward slashes are only valid
+ * Windows paths when they don't contain non-ascii characters, and posixPath
+ * doesn't escape those that fail to be converted.
+ */
+export function escapePath(str: string): string {
+  const escaped = JSON.stringify(str);
+
+  // Remove the " around the json string;
+  return escaped.substring(1, escaped.length - 1);
+}