@docusaurus/utils 2.0.0-beta.17 → 2.0.0-beta.18

package/lib/constants.d.ts

@@ -4,17 +4,65 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
+/** Node major version, directly read from env. */
 export declare const NODE_MAJOR_VERSION: number;
+/** Node minor version, directly read from env. */
 export declare const NODE_MINOR_VERSION: number;
+/**
+ * Can be overridden with cli option `--out-dir`. Code should generally use
+ * `context.outDir` instead (which is always absolute and localized).
+ */
 export declare const DEFAULT_BUILD_DIR_NAME = "build";
+/**
+ * Can be overridden with cli option `--config`. Code should generally use
+ * `context.siteConfigPath` instead (which is always absolute).
+ */
 export declare const DEFAULT_CONFIG_FILE_NAME = "docusaurus.config.js";
+/** Can be absolute or relative to site directory. */
 export declare const BABEL_CONFIG_FILE_NAME: string;
+/**
+ * Can be absolute or relative to site directory. Code should generally use
+ * `context.generatedFilesDir` instead (which is always absolute).
+ */
 export declare const GENERATED_FILES_DIR_NAME: string;
+/**
+ * We would assume all of the site's JS code lives in here and not outside.
+ * Relative to the site directory.
+ */
 export declare const SRC_DIR_NAME = "src";
-export declare const STATIC_DIR_NAME = "static";
+/**
+ * Can be overridden with `config.staticDirectories`. Code should use
+ * `context.siteConfig.staticDirectories` instead (which is always absolute).
+ */
+export declare const DEFAULT_STATIC_DIR_NAME = "static";
+/**
+ * Files here are handled by webpack, hashed (can be cached aggressively).
+ * Relative to the build output folder.
+ */
 export declare const OUTPUT_STATIC_ASSETS_DIR_NAME = "assets";
+/**
+ * Components in this directory will receive the `@theme` alias and be able to
+ * shadow default theme components.
+ */
 export declare const THEME_PATH: string;
+/**
+ * All translation-related data live here, relative to site directory. Content
+ * will be namespaced by locale.
+ */
+export declare const I18N_DIR_NAME = "i18n";
+/**
+ * Translations for React code.
+ */
+export declare const CODE_TRANSLATIONS_FILE_NAME = "code.json";
+/** Dev server opens on this port by default. */
 export declare const DEFAULT_PORT = 3000;
+/** Default plugin ID. */
 export declare const DEFAULT_PLUGIN_ID = "default";
+/**
+ * Allow overriding the limit after which the url loader will no longer inline
+ * assets.
+ *
+ * @see https://github.com/facebook/docusaurus/issues/5493
+ */
 export declare const WEBPACK_URL_LOADER_LIMIT: string | number;
 //# sourceMappingURL=constants.d.ts.map

package/lib/constants.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,eAAO,MAAM,kBAAkB,QAG9B,CAAC;AACF,eAAO,MAAM,kBAAkB,QAG9B,CAAC;AAGF,eAAO,MAAM,sBAAsB,UAAU,CAAC;AAG9C,eAAO,MAAM,wBAAwB,yBAAyB,CAAC;AAE/D,eAAO,MAAM,sBAAsB,QACiC,CAAC;AAErE,eAAO,MAAM,wBAAwB,QAC6B,CAAC;AAEnE,eAAO,MAAM,YAAY,QAAQ,CAAC;AAClC,eAAO,MAAM,eAAe,WAAW,CAAC;AACxC,eAAO,MAAM,6BAA6B,WAAW,CAAC;AACtD,eAAO,MAAM,UAAU,QAA0B,CAAC;AAClD,eAAO,MAAM,YAAY,OAAO,CAAC;AACjC,eAAO,MAAM,iBAAiB,YAAY,CAAC;AAG3C,eAAO,MAAM,wBAAwB,iBACU,CAAC"}
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,kDAAkD;AAClD,eAAO,MAAM,kBAAkB,QAG9B,CAAC;AACF,kDAAkD;AAClD,eAAO,MAAM,kBAAkB,QAG9B,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,sBAAsB,UAAU,CAAC;AAE9C;;;GAGG;AACH,eAAO,MAAM,wBAAwB,yBAAyB,CAAC;AAE/D,qDAAqD;AACrD,eAAO,MAAM,sBAAsB,QACiC,CAAC;AAErE;;;GAGG;AACH,eAAO,MAAM,wBAAwB,QAC6B,CAAC;AAEnE;;;GAGG;AACH,eAAO,MAAM,YAAY,QAAQ,CAAC;AAElC;;;GAGG;AACH,eAAO,MAAM,uBAAuB,WAAW,CAAC;AAEhD;;;GAGG;AACH,eAAO,MAAM,6BAA6B,WAAW,CAAC;AAEtD;;;GAGG;AACH,eAAO,MAAM,UAAU,QAA0B,CAAC;AAElD;;;GAGG;AACH,eAAO,MAAM,aAAa,SAAS,CAAC;AAEpC;;GAEG;AACH,eAAO,MAAM,2BAA2B,cAAc,CAAC;AAEvD,gDAAgD;AAChD,eAAO,MAAM,YAAY,OAAO,CAAC;AAEjC,yBAAyB;AACzB,eAAO,MAAM,iBAAiB,YAAY,CAAC;AAE3C;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,iBACU,CAAC"}

package/lib/constants.js

@@ -6,21 +6,66 @@
  * LICENSE file in the root directory of this source tree.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.WEBPACK_URL_LOADER_LIMIT = exports.DEFAULT_PLUGIN_ID = exports.DEFAULT_PORT = exports.THEME_PATH = exports.OUTPUT_STATIC_ASSETS_DIR_NAME = exports.STATIC_DIR_NAME = exports.SRC_DIR_NAME = exports.GENERATED_FILES_DIR_NAME = exports.BABEL_CONFIG_FILE_NAME = exports.DEFAULT_CONFIG_FILE_NAME = exports.DEFAULT_BUILD_DIR_NAME = exports.NODE_MINOR_VERSION = exports.NODE_MAJOR_VERSION = void 0;
+exports.WEBPACK_URL_LOADER_LIMIT = exports.DEFAULT_PLUGIN_ID = exports.DEFAULT_PORT = exports.CODE_TRANSLATIONS_FILE_NAME = exports.I18N_DIR_NAME = exports.THEME_PATH = exports.OUTPUT_STATIC_ASSETS_DIR_NAME = exports.DEFAULT_STATIC_DIR_NAME = exports.SRC_DIR_NAME = exports.GENERATED_FILES_DIR_NAME = exports.BABEL_CONFIG_FILE_NAME = exports.DEFAULT_CONFIG_FILE_NAME = exports.DEFAULT_BUILD_DIR_NAME = exports.NODE_MINOR_VERSION = exports.NODE_MAJOR_VERSION = void 0;
+/** Node major version, directly read from env. */
 exports.NODE_MAJOR_VERSION = parseInt(process.versions.node.split('.')[0], 10);
+/** Node minor version, directly read from env. */
 exports.NODE_MINOR_VERSION = parseInt(process.versions.node.split('.')[1], 10);
-// Can be overridden with cli option --out-dir
+/**
+ * Can be overridden with cli option `--out-dir`. Code should generally use
+ * `context.outDir` instead (which is always absolute and localized).
+ */
 exports.DEFAULT_BUILD_DIR_NAME = 'build';
-// Can be overridden with cli option --config
+/**
+ * Can be overridden with cli option `--config`. Code should generally use
+ * `context.siteConfigPath` instead (which is always absolute).
+ */
 exports.DEFAULT_CONFIG_FILE_NAME = 'docusaurus.config.js';
-exports.BABEL_CONFIG_FILE_NAME = process.env.DOCUSAURUS_BABEL_CONFIG_FILE_NAME || 'babel.config.js';
-exports.GENERATED_FILES_DIR_NAME = process.env.DOCUSAURUS_GENERATED_FILES_DIR_NAME || '.docusaurus';
+/** Can be absolute or relative to site directory. */
+exports.BABEL_CONFIG_FILE_NAME = process.env.DOCUSAURUS_BABEL_CONFIG_FILE_NAME ?? 'babel.config.js';
+/**
+ * Can be absolute or relative to site directory. Code should generally use
+ * `context.generatedFilesDir` instead (which is always absolute).
+ */
+exports.GENERATED_FILES_DIR_NAME = process.env.DOCUSAURUS_GENERATED_FILES_DIR_NAME ?? '.docusaurus';
+/**
+ * We would assume all of the site's JS code lives in here and not outside.
+ * Relative to the site directory.
+ */
 exports.SRC_DIR_NAME = 'src';
-exports.STATIC_DIR_NAME = 'static';
-exports.OUTPUT_STATIC_ASSETS_DIR_NAME = 'assets'; // files handled by webpack, hashed (can be cached aggressively)
+/**
+ * Can be overridden with `config.staticDirectories`. Code should use
+ * `context.siteConfig.staticDirectories` instead (which is always absolute).
+ */
+exports.DEFAULT_STATIC_DIR_NAME = 'static';
+/**
+ * Files here are handled by webpack, hashed (can be cached aggressively).
+ * Relative to the build output folder.
+ */
+exports.OUTPUT_STATIC_ASSETS_DIR_NAME = 'assets';
+/**
+ * Components in this directory will receive the `@theme` alias and be able to
+ * shadow default theme components.
+ */
 exports.THEME_PATH = `${exports.SRC_DIR_NAME}/theme`;
+/**
+ * All translation-related data live here, relative to site directory. Content
+ * will be namespaced by locale.
+ */
+exports.I18N_DIR_NAME = 'i18n';
+/**
+ * Translations for React code.
+ */
+exports.CODE_TRANSLATIONS_FILE_NAME = 'code.json';
+/** Dev server opens on this port by default. */
 exports.DEFAULT_PORT = 3000;
+/** Default plugin ID. */
 exports.DEFAULT_PLUGIN_ID = 'default';
-// Temporary fix for https://github.com/facebook/docusaurus/issues/5493
+/**
+ * Allow overriding the limit after which the url loader will no longer inline
+ * assets.
+ *
+ * @see https://github.com/facebook/docusaurus/issues/5493
+ */
 exports.WEBPACK_URL_LOADER_LIMIT = process.env.WEBPACK_URL_LOADER_LIMIT ?? 10000;
 //# sourceMappingURL=constants.js.map

package/lib/constants.js.map

@@ -1 +1 @@
-{"version":3,"file":"constants.js","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;AAEU,QAAA,kBAAkB,GAAG,QAAQ,CACxC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EACnC,EAAE,CACH,CAAC;AACW,QAAA,kBAAkB,GAAG,QAAQ,CACxC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EACnC,EAAE,CACH,CAAC;AAEF,8CAA8C;AACjC,QAAA,sBAAsB,GAAG,OAAO,CAAC;AAE9C,6CAA6C;AAChC,QAAA,wBAAwB,GAAG,sBAAsB,CAAC;AAElD,QAAA,sBAAsB,GACjC,OAAO,CAAC,GAAG,CAAC,iCAAiC,IAAI,iBAAiB,CAAC;AAExD,QAAA,wBAAwB,GACnC,OAAO,CAAC,GAAG,CAAC,mCAAmC,IAAI,aAAa,CAAC;AAEtD,QAAA,YAAY,GAAG,KAAK,CAAC;AACrB,QAAA,eAAe,GAAG,QAAQ,CAAC;AAC3B,QAAA,6BAA6B,GAAG,QAAQ,CAAC,CAAC,gEAAgE;AAC1G,QAAA,UAAU,GAAG,GAAG,oBAAY,QAAQ,CAAC;AACrC,QAAA,YAAY,GAAG,IAAI,CAAC;AACpB,QAAA,iBAAiB,GAAG,SAAS,CAAC;AAE3C,uEAAuE;AAC1D,QAAA,wBAAwB,GACnC,OAAO,CAAC,GAAG,CAAC,wBAAwB,IAAI,KAAK,CAAC"}
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;AAEH,kDAAkD;AACrC,QAAA,kBAAkB,GAAG,QAAQ,CACxC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAE,EACpC,EAAE,CACH,CAAC;AACF,kDAAkD;AACrC,QAAA,kBAAkB,GAAG,QAAQ,CACxC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAE,EACpC,EAAE,CACH,CAAC;AAEF;;;GAGG;AACU,QAAA,sBAAsB,GAAG,OAAO,CAAC;AAE9C;;;GAGG;AACU,QAAA,wBAAwB,GAAG,sBAAsB,CAAC;AAE/D,qDAAqD;AACxC,QAAA,sBAAsB,GACjC,OAAO,CAAC,GAAG,CAAC,iCAAiC,IAAI,iBAAiB,CAAC;AAErE;;;GAGG;AACU,QAAA,wBAAwB,GACnC,OAAO,CAAC,GAAG,CAAC,mCAAmC,IAAI,aAAa,CAAC;AAEnE;;;GAGG;AACU,QAAA,YAAY,GAAG,KAAK,CAAC;AAElC;;;GAGG;AACU,QAAA,uBAAuB,GAAG,QAAQ,CAAC;AAEhD;;;GAGG;AACU,QAAA,6BAA6B,GAAG,QAAQ,CAAC;AAEtD;;;GAGG;AACU,QAAA,UAAU,GAAG,GAAG,oBAAY,QAAQ,CAAC;AAElD;;;GAGG;AACU,QAAA,aAAa,GAAG,MAAM,CAAC;AAEpC;;GAEG;AACU,QAAA,2BAA2B,GAAG,WAAW,CAAC;AAEvD,gDAAgD;AACnC,QAAA,YAAY,GAAG,IAAI,CAAC;AAEjC,yBAAyB;AACZ,QAAA,iBAAiB,GAAG,SAAS,CAAC;AAE3C;;;;;GAKG;AACU,QAAA,wBAAwB,GACnC,OAAO,CAAC,GAAG,CAAC,wBAAwB,IAAI,KAAK,CAAC"}

package/lib/dataFileUtils.d.ts

@@ -6,19 +6,55 @@
  */
 import type { ContentPaths } from './markdownLinks';
 declare type DataFileParams = {
+    /** Path to the potential data file, relative to `contentPaths` */
     filePath: string;
+    /**
+     * Includes the base path and localized path, both of which are eligible for
+     * sourcing data files. Both paths should be absolute.
+     */
     contentPaths: ContentPaths;
 };
+/**
+ * Looks for a data file in the potential content paths; loads a localized data
+ * file in priority.
+ *
+ * @returns An absolute path to the data file, or `undefined` if there isn't one.
+ */
 export declare function getDataFilePath({ filePath, contentPaths, }: DataFileParams): Promise<string | 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
+ * Looks up for a data file in the content paths, returns the object validated
+ * and normalized according to the `validate` callback.
+ *
+ * @returns `undefined` when file not found
+ * @throws Throws when validation fails, displaying a helpful context message.
  */
 export declare function getDataFileData<T>(params: DataFileParams & {
+    /** Used for the "The X file looks invalid" message. */
     fileType: string;
 }, validate: (content: unknown) => T): Promise<T | undefined>;
+/**
+ * Takes the `contentPaths` data structure and returns an ordered path list
+ * indicating their priorities. For all data, we look in the localized folder
+ * in priority.
+ */
 export declare function getContentPathList(contentPaths: ContentPaths): string[];
+/**
+ * @param folderPaths a list of absolute paths.
+ * @param relativeFilePath file path relative to each `folderPaths`.
+ * @returns the first folder path in which the file exists, or `undefined` if
+ * none is found.
+ */
 export declare function findFolderContainingFile(folderPaths: string[], relativeFilePath: string): Promise<string | undefined>;
+/**
+ * Fail-fast alternative to `findFolderContainingFile`.
+ *
+ * @param folderPaths a list of absolute paths.
+ * @param relativeFilePath file path relative to each `folderPaths`.
+ * @returns the first folder path in which the file exists.
+ * @throws Throws if no file can be found. You should use this method only when
+ * you actually know the file exists (e.g. when the `relativeFilePath` is read
+ * with a glob and you are just trying to localize it)
+ */
 export declare function getFolderContainingFile(folderPaths: string[], relativeFilePath: string): Promise<string>;
 export {};
 //# sourceMappingURL=dataFileUtils.d.ts.map

package/lib/dataFileUtils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dataFileUtils.d.ts","sourceRoot":"","sources":["../src/dataFileUtils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,iBAAiB,CAAC;AAGlD,aAAK,cAAc,GAAG;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,YAAY,CAAC;CAC5B,CAAC;AAEF,wBAAsB,eAAe,CAAC,EACpC,QAAQ,EACR,YAAY,GACb,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAU9C;AAED;;;GAGG;AACH,wBAAsB,eAAe,CAAC,CAAC,EACrC,MAAM,EAAE,cAAc,GAAG;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAC,EAC3C,QAAQ,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,CAAC,GAChC,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAcxB;AAGD,wBAAgB,kBAAkB,CAAC,YAAY,EAAE,YAAY,GAAG,MAAM,EAAE,CAEvE;AAGD,wBAAsB,wBAAwB,CAC5C,WAAW,EAAE,MAAM,EAAE,EACrB,gBAAgB,EAAE,MAAM,GACvB,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAI7B;AAED,wBAAsB,uBAAuB,CAC3C,WAAW,EAAE,MAAM,EAAE,EACrB,gBAAgB,EAAE,MAAM,GACvB,OAAO,CAAC,MAAM,CAAC,CAcjB"}
+{"version":3,"file":"dataFileUtils.d.ts","sourceRoot":"","sources":["../src/dataFileUtils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,iBAAiB,CAAC;AAGlD,aAAK,cAAc,GAAG;IACpB,kEAAkE;IAClE,QAAQ,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,YAAY,EAAE,YAAY,CAAC;CAC5B,CAAC;AAEF;;;;;GAKG;AACH,wBAAsB,eAAe,CAAC,EACpC,QAAQ,EACR,YAAY,GACb,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAS9C;AAED;;;;;;GAMG;AACH,wBAAsB,eAAe,CAAC,CAAC,EACrC,MAAM,EAAE,cAAc,GAAG;IACvB,uDAAuD;IACvD,QAAQ,EAAE,MAAM,CAAC;CAClB,EACD,QAAQ,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,CAAC,GAChC,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAaxB;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,YAAY,EAAE,YAAY,GAAG,MAAM,EAAE,CAEvE;AAED;;;;;GAKG;AACH,wBAAsB,wBAAwB,CAC5C,WAAW,EAAE,MAAM,EAAE,EACrB,gBAAgB,EAAE,MAAM,GACvB,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAI7B;AAED;;;;;;;;;GASG;AACH,wBAAsB,uBAAuB,CAC3C,WAAW,EAAE,MAAM,EAAE,EACrB,gBAAgB,EAAE,MAAM,GACvB,OAAO,CAAC,MAAM,CAAC,CAYjB"}

package/lib/dataFileUtils.js

@@ -13,8 +13,13 @@ const js_yaml_1 = tslib_1.__importDefault(require("js-yaml"));
 const path_1 = tslib_1.__importDefault(require("path"));
 const index_1 = require("./index");
 const logger_1 = tslib_1.__importDefault(require("@docusaurus/logger"));
+/**
+ * Looks for a data file in the potential content paths; loads a localized data
+ * file in priority.
+ *
+ * @returns An absolute path to the data file, or `undefined` if there isn't one.
+ */
 async function getDataFilePath({ filePath, contentPaths, }) {
-    // Loads a localized data file in priority
     const contentPath = await findFolderContainingFile(getContentPathList(contentPaths), filePath);
     if (contentPath) {
         return path_1.default.join(contentPath, filePath);
@@ -23,8 +28,11 @@ async function getDataFilePath({ filePath, contentPaths, }) {
 }
 exports.getDataFilePath = getDataFilePath;
 /**
- * Looks up for a data file in the content paths, returns the normalized object.
- * Throws when validation fails; returns undefined when file not found
+ * Looks up for a data file in the content paths, returns the object validated
+ * and normalized according to the `validate` callback.
+ *
+ * @returns `undefined` when file not found
+ * @throws Throws when validation fails, displaying a helpful context message.
  */
 async function getDataFileData(params, validate) {
     const filePath = await getDataFilePath(params);
@@ -37,27 +45,45 @@ async function getDataFileData(params, validate) {
         return validate(unsafeContent);
     }
     catch (err) {
-        // TODO replace later by error cause, see https://v8.dev/features/error-cause
         logger_1.default.error `The ${params.fileType} file at path=${filePath} looks invalid.`;
         throw err;
     }
 }
 exports.getDataFileData = getDataFileData;
-// Order matters: we look in priority in localized folder
+/**
+ * Takes the `contentPaths` data structure and returns an ordered path list
+ * indicating their priorities. For all data, we look in the localized folder
+ * in priority.
+ */
 function getContentPathList(contentPaths) {
     return [contentPaths.contentPathLocalized, contentPaths.contentPath];
 }
 exports.getContentPathList = getContentPathList;
-// return the first folder path in which the file exists in
+/**
+ * @param folderPaths a list of absolute paths.
+ * @param relativeFilePath file path relative to each `folderPaths`.
+ * @returns the first folder path in which the file exists, or `undefined` if
+ * none is found.
+ */
 async function findFolderContainingFile(folderPaths, relativeFilePath) {
     return (0, index_1.findAsyncSequential)(folderPaths, (folderPath) => fs_extra_1.default.pathExists(path_1.default.join(folderPath, relativeFilePath)));
 }
 exports.findFolderContainingFile = findFolderContainingFile;
+/**
+ * Fail-fast alternative to `findFolderContainingFile`.
+ *
+ * @param folderPaths a list of absolute paths.
+ * @param relativeFilePath file path relative to each `folderPaths`.
+ * @returns the first folder path in which the file exists.
+ * @throws Throws if no file can be found. You should use this method only when
+ * you actually know the file exists (e.g. when the `relativeFilePath` is read
+ * with a glob and you are just trying to localize it)
+ */
 async function getFolderContainingFile(folderPaths, relativeFilePath) {
     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- ')}]`);
+        throw new Error(`File "${relativeFilePath}" does not exist in any of these folders:
+- ${folderPaths.join('\n- ')}`);
     }
     return maybeFolderPath;
 }

package/lib/dataFileUtils.js.map

@@ -1 +1 @@
-{"version":3,"file":"dataFileUtils.js","sourceRoot":"","sources":["../src/dataFileUtils.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;;AAEH,gEAA0B;AAC1B,8DAA2B;AAC3B,wDAAwB;AACxB,mCAA4C;AAE5C,wEAAwC;AAOjC,KAAK,UAAU,eAAe,CAAC,EACpC,QAAQ,EACR,YAAY,GACG;IACf,0CAA0C;IAC1C,MAAM,WAAW,GAAG,MAAM,wBAAwB,CAChD,kBAAkB,CAAC,YAAY,CAAC,EAChC,QAAQ,CACT,CAAC;IACF,IAAI,WAAW,EAAE;QACf,OAAO,cAAI,CAAC,IAAI,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC;KACzC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAbD,0CAaC;AAED;;;GAGG;AACI,KAAK,UAAU,eAAe,CACnC,MAA2C,EAC3C,QAAiC;IAEjC,MAAM,QAAQ,GAAG,MAAM,eAAe,CAAC,MAAM,CAAC,CAAC;IAC/C,IAAI,CAAC,QAAQ,EAAE;QACb,OAAO,SAAS,CAAC;KAClB;IACD,IAAI;QACF,MAAM,aAAa,GAAG,MAAM,kBAAE,CAAC,QAAQ,CAAC,QAAQ,EAAE,EAAC,QAAQ,EAAE,MAAM,EAAC,CAAC,CAAC;QACtE,MAAM,aAAa,GAAG,iBAAI,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;QAC/C,OAAO,QAAQ,CAAC,aAAa,CAAC,CAAC;KAChC;IAAC,OAAO,GAAG,EAAE;QACZ,6EAA6E;QAC7E,gBAAM,CAAC,KAAK,CAAA,OAAO,MAAM,CAAC,QAAQ,iBAAiB,QAAQ,iBAAiB,CAAC;QAC7E,MAAM,GAAG,CAAC;KACX;AACH,CAAC;AAjBD,0CAiBC;AAED,yDAAyD;AACzD,SAAgB,kBAAkB,CAAC,YAA0B;IAC3D,OAAO,CAAC,YAAY,CAAC,oBAAoB,EAAE,YAAY,CAAC,WAAW,CAAC,CAAC;AACvE,CAAC;AAFD,gDAEC;AAED,2DAA2D;AACpD,KAAK,UAAU,wBAAwB,CAC5C,WAAqB,EACrB,gBAAwB;IAExB,OAAO,IAAA,2BAAmB,EAAC,WAAW,EAAE,CAAC,UAAU,EAAE,EAAE,CACrD,kBAAE,CAAC,UAAU,CAAC,cAAI,CAAC,IAAI,CAAC,UAAU,EAAE,gBAAgB,CAAC,CAAC,CACvD,CAAC;AACJ,CAAC;AAPD,4DAOC;AAEM,KAAK,UAAU,uBAAuB,CAC3C,WAAqB,EACrB,gBAAwB;IAExB,MAAM,eAAe,GAAG,MAAM,wBAAwB,CACpD,WAAW,EACX,gBAAgB,CACjB,CAAC;IACF,oEAAoE;IACpE,IAAI,CAAC,eAAe,EAAE;QACpB,MAAM,IAAI,KAAK,CACb,SAAS,gBAAgB,gDAAgD,WAAW,CAAC,IAAI,CACvF,MAAM,CACP,GAAG,CACL,CAAC;KACH;IACD,OAAO,eAAe,CAAC;AACzB,CAAC;AAjBD,0DAiBC"}
+{"version":3,"file":"dataFileUtils.js","sourceRoot":"","sources":["../src/dataFileUtils.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;;AAEH,gEAA0B;AAC1B,8DAA2B;AAC3B,wDAAwB;AACxB,mCAA4C;AAE5C,wEAAwC;AAYxC;;;;;GAKG;AACI,KAAK,UAAU,eAAe,CAAC,EACpC,QAAQ,EACR,YAAY,GACG;IACf,MAAM,WAAW,GAAG,MAAM,wBAAwB,CAChD,kBAAkB,CAAC,YAAY,CAAC,EAChC,QAAQ,CACT,CAAC;IACF,IAAI,WAAW,EAAE;QACf,OAAO,cAAI,CAAC,IAAI,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC;KACzC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAZD,0CAYC;AAED;;;;;;GAMG;AACI,KAAK,UAAU,eAAe,CACnC,MAGC,EACD,QAAiC;IAEjC,MAAM,QAAQ,GAAG,MAAM,eAAe,CAAC,MAAM,CAAC,CAAC;IAC/C,IAAI,CAAC,QAAQ,EAAE;QACb,OAAO,SAAS,CAAC;KAClB;IACD,IAAI;QACF,MAAM,aAAa,GAAG,MAAM,kBAAE,CAAC,QAAQ,CAAC,QAAQ,EAAE,EAAC,QAAQ,EAAE,MAAM,EAAC,CAAC,CAAC;QACtE,MAAM,aAAa,GAAG,iBAAI,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;QAC/C,OAAO,QAAQ,CAAC,aAAa,CAAC,CAAC;KAChC;IAAC,OAAO,GAAG,EAAE;QACZ,gBAAM,CAAC,KAAK,CAAA,OAAO,MAAM,CAAC,QAAQ,iBAAiB,QAAQ,iBAAiB,CAAC;QAC7E,MAAM,GAAG,CAAC;KACX;AACH,CAAC;AAnBD,0CAmBC;AAED;;;;GAIG;AACH,SAAgB,kBAAkB,CAAC,YAA0B;IAC3D,OAAO,CAAC,YAAY,CAAC,oBAAoB,EAAE,YAAY,CAAC,WAAW,CAAC,CAAC;AACvE,CAAC;AAFD,gDAEC;AAED;;;;;GAKG;AACI,KAAK,UAAU,wBAAwB,CAC5C,WAAqB,EACrB,gBAAwB;IAExB,OAAO,IAAA,2BAAmB,EAAC,WAAW,EAAE,CAAC,UAAU,EAAE,EAAE,CACrD,kBAAE,CAAC,UAAU,CAAC,cAAI,CAAC,IAAI,CAAC,UAAU,EAAE,gBAAgB,CAAC,CAAC,CACvD,CAAC;AACJ,CAAC;AAPD,4DAOC;AAED;;;;;;;;;GASG;AACI,KAAK,UAAU,uBAAuB,CAC3C,WAAqB,EACrB,gBAAwB;IAExB,MAAM,eAAe,GAAG,MAAM,wBAAwB,CACpD,WAAW,EACX,gBAAgB,CACjB,CAAC;IACF,IAAI,CAAC,eAAe,EAAE;QACpB,MAAM,IAAI,KAAK,CACb,SAAS,gBAAgB;IAC3B,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CACzB,CAAC;KACH;IACD,OAAO,eAAe,CAAC;AACzB,CAAC;AAfD,0DAeC"}

package/lib/emitUtils.d.ts

@@ -5,6 +5,16 @@
  * LICENSE file in the root directory of this source tree.
  */
 /// <reference types="node" />
+/**
+ * Outputs a file to the generated files directory. Only writes files if content
+ * differs from cache (for hot reload performance).
+ *
+ * @param generatedFilesDir Absolute path.
+ * @param file Path relative to `generatedFilesDir`.
+ * @param content String content to write.
+ * @param skipCache If `true` (defaults as `true` for production), file is
+ * force-rewritten, skipping cache.
+ */
 export declare function generate(generatedFilesDir: string, file: string, content: string, skipCache?: boolean): Promise<void>;
 /**
  * Generate unique chunk name given a module path.
@@ -18,6 +28,8 @@ export declare function genChunkName(modulePath: string, prefix?: string, prefer
  * @returns This returns a buffer, which you have to decode string yourself if
  * needed. (Not always necessary since the output isn't for human consumption
  * anyways, and most HTML manipulation libs accept buffers)
+ * @throws Throws when the HTML file is not found at any of the potential paths.
+ * This should never happen as it would lead to a 404.
  */
 export declare function readOutputHTMLFile(permalink: string, outDir: string, trailingSlash: boolean | undefined): Promise<Buffer>;
 //# sourceMappingURL=emitUtils.d.ts.map

package/lib/emitUtils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"emitUtils.d.ts","sourceRoot":"","sources":["../src/emitUtils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;;AAUH,wBAAsB,QAAQ,CAC5B,iBAAiB,EAAE,MAAM,EACzB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,SAAS,GAAE,OAA+C,GACzD,OAAO,CAAC,IAAI,CAAC,CA2Bf;AAID;;GAEG;AACH,wBAAgB,YAAY,CAC1B,UAAU,EAAE,MAAM,EAClB,MAAM,CAAC,EAAE,MAAM,EACf,aAAa,CAAC,EAAE,MAAM,EACtB,OAAO,GAAE,OAA+C,GACvD,MAAM,CAiBR;AAED;;;;;;;;GAQG;AACH,wBAAsB,kBAAkB,CACtC,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,aAAa,EAAE,OAAO,GAAG,SAAS,GACjC,OAAO,CAAC,MAAM,CAAC,CAqBjB"}
+{"version":3,"file":"emitUtils.d.ts","sourceRoot":"","sources":["../src/emitUtils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;;AAUH;;;;;;;;;GASG;AACH,wBAAsB,QAAQ,CAC5B,iBAAiB,EAAE,MAAM,EACzB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,SAAS,GAAE,OAA+C,GACzD,OAAO,CAAC,IAAI,CAAC,CAgCf;AAID;;GAEG;AACH,wBAAgB,YAAY,CAC1B,UAAU,EAAE,MAAM,EAClB,MAAM,CAAC,EAAE,MAAM,EACf,aAAa,CAAC,EAAE,MAAM,EACtB,OAAO,GAAE,OAA+C,GACvD,MAAM,CAiBR;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,kBAAkB,CACtC,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,aAAa,EAAE,OAAO,GAAG,SAAS,GACjC,OAAO,CAAC,MAAM,CAAC,CAqBjB"}

package/lib/emitUtils.js

@@ -14,17 +14,33 @@ const crypto_1 = require("crypto");
 const hashUtils_1 = require("./hashUtils");
 const jsUtils_1 = require("./jsUtils");
 const fileHash = new Map();
+/**
+ * Outputs a file to the generated files directory. Only writes files if content
+ * differs from cache (for hot reload performance).
+ *
+ * @param generatedFilesDir Absolute path.
+ * @param file Path relative to `generatedFilesDir`.
+ * @param content String content to write.
+ * @param skipCache If `true` (defaults as `true` for production), file is
+ * force-rewritten, skipping cache.
+ */
 async function generate(generatedFilesDir, file, content, skipCache = process.env.NODE_ENV === 'production') {
     const filepath = path_1.default.join(generatedFilesDir, file);
     if (skipCache) {
-        await fs_extra_1.default.ensureDir(path_1.default.dirname(filepath));
-        await fs_extra_1.default.writeFile(filepath, content);
+        await fs_extra_1.default.outputFile(filepath, content);
+        // Cache still needs to be reset, otherwise, writing "A", "B", and "A" where
+        // "B" skips cache will cause the last "A" not be able to overwrite as the
+        // first "A" remains in cache. But if the file never existed in cache, no
+        // need to register it.
+        if (fileHash.get(filepath)) {
+            fileHash.set(filepath, (0, crypto_1.createHash)('md5').update(content).digest('hex'));
+        }
         return;
     }
     let lastHash = fileHash.get(filepath);
-    // If file already exists but its not in runtime cache yet,
-    // we try to calculate the content hash and then compare
-    // This is to avoid unnecessary overwriting and we can reuse old file.
+    // If file already exists but it's not in runtime cache yet, we try to
+    // calculate the content hash and then compare. This is to avoid unnecessary
+    // overwriting and we can reuse old file.
     if (!lastHash && (await fs_extra_1.default.pathExists(filepath))) {
         const lastContent = await fs_extra_1.default.readFile(filepath, 'utf8');
         lastHash = (0, crypto_1.createHash)('md5').update(lastContent).digest('hex');
@@ -32,8 +48,7 @@ async function generate(generatedFilesDir, file, content, skipCache = process.en
     }
     const currentHash = (0, crypto_1.createHash)('md5').update(content).digest('hex');
     if (lastHash !== currentHash) {
-        await fs_extra_1.default.ensureDir(path_1.default.dirname(filepath));
-        await fs_extra_1.default.writeFile(filepath, content);
+        await fs_extra_1.default.outputFile(filepath, content);
         fileHash.set(filepath, currentHash);
     }
 }
@@ -70,6 +85,8 @@ exports.genChunkName = genChunkName;
  * @returns This returns a buffer, which you have to decode string yourself if
  * needed. (Not always necessary since the output isn't for human consumption
  * anyways, and most HTML manipulation libs accept buffers)
+ * @throws Throws when the HTML file is not found at any of the potential paths.
+ * This should never happen as it would lead to a 404.
  */
 async function readOutputHTMLFile(permalink, outDir, trailingSlash) {
     const withTrailingSlashPath = path_1.default.join(outDir, permalink, 'index.html');

package/lib/emitUtils.js.map

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

package/lib/gitUtils.d.ts

@@ -4,14 +4,63 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
+/** Custom error thrown when git is not found in `PATH`. */
 export declare class GitNotFoundError extends Error {
 }
-export declare const getFileCommitDate: (file: string, { age, includeAuthor, }: {
-    age?: "oldest" | "newest" | undefined;
-    includeAuthor?: boolean | undefined;
-}) => {
+/** Custom error thrown when the current file is not tracked by git. */
+export declare class FileNotTrackedError extends Error {
+}
+/**
+ * Fetches the git history of a file and returns a relevant commit date.
+ * It gets the commit date instead of author date so that amended commits
+ * can have their dates updated.
+ *
+ * @throws {GitNotFoundError} If git is not found in `PATH`.
+ * @throws {FileNotTrackedError} If the current file is not tracked by git.
+ * @throws Also throws when `git log` exited with non-zero, or when it outputs
+ * unexpected text.
+ */
+export declare function getFileCommitDate(
+/** Absolute path to the file. */
+file: string, args: {
+    /**
+     * `"oldest"` is the commit that added the file, following renames;
+     * `"newest"` is the last commit that edited the file.
+     */
+    age?: 'oldest' | 'newest';
+    /** Use `includeAuthor: true` to get the author information as well. */
+    includeAuthor?: false;
+}): {
+    /** Relevant commit date. */
+    date: Date;
+    /** Timestamp in **seconds**, as returned from git. */
+    timestamp: number;
+};
+/**
+ * Fetches the git history of a file and returns a relevant commit date.
+ * It gets the commit date instead of author date so that amended commits
+ * can have their dates updated.
+ *
+ * @throws {GitNotFoundError} If git is not found in `PATH`.
+ * @throws {FileNotTrackedError} If the current file is not tracked by git.
+ * @throws Also throws when `git log` exited with non-zero, or when it outputs
+ * unexpected text.
+ */
+export declare function getFileCommitDate(
+/** Absolute path to the file. */
+file: string, args: {
+    /**
+     * `"oldest"` is the commit that added the file, following renames;
+     * `"newest"` is the last commit that edited the file.
+     */
+    age?: 'oldest' | 'newest';
+    includeAuthor: true;
+}): {
+    /** Relevant commit date. */
     date: Date;
+    /** Timestamp in **seconds**, as returned from git. */
     timestamp: number;
-    author?: string | undefined;
+    /** The author's name, as returned from git. */
+    author: string;
 };
 //# sourceMappingURL=gitUtils.d.ts.map

package/lib/gitUtils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"gitUtils.d.ts","sourceRoot":"","sources":["../src/gitUtils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,qBAAa,gBAAiB,SAAQ,KAAK;CAAG;AAE9C,eAAO,MAAM,iBAAiB,SACtB,MAAM;;;;UASN,IAAI;eACC,MAAM;;CAqElB,CAAC"}
+{"version":3,"file":"gitUtils.d.ts","sourceRoot":"","sources":["../src/gitUtils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,2DAA2D;AAC3D,qBAAa,gBAAiB,SAAQ,KAAK;CAAG;AAE9C,uEAAuE;AACvE,qBAAa,mBAAoB,SAAQ,KAAK;CAAG;AAEjD;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB;AAC/B,iCAAiC;AACjC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE;IACJ;;;OAGG;IACH,GAAG,CAAC,EAAE,QAAQ,GAAG,QAAQ,CAAC;IAC1B,uEAAuE;IACvE,aAAa,CAAC,EAAE,KAAK,CAAC;CACvB,GACA;IACD,4BAA4B;IAC5B,IAAI,EAAE,IAAI,CAAC;IACX,sDAAsD;IACtD,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AACF;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB;AAC/B,iCAAiC;AACjC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE;IACJ;;;OAGG;IACH,GAAG,CAAC,EAAE,QAAQ,GAAG,QAAQ,CAAC;IAC1B,aAAa,EAAE,IAAI,CAAC;CACrB,GACA;IACD,4BAA4B;IAC5B,IAAI,EAAE,IAAI,CAAC;IACX,sDAAsD;IACtD,SAAS,EAAE,MAAM,CAAC;IAClB,+CAA+C;IAC/C,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC"}

package/lib/gitUtils.js

@@ -6,22 +6,25 @@
  * LICENSE file in the root directory of this source tree.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getFileCommitDate = exports.GitNotFoundError = void 0;
+exports.getFileCommitDate = exports.FileNotTrackedError = exports.GitNotFoundError = void 0;
 const tslib_1 = require("tslib");
 const path_1 = tslib_1.__importDefault(require("path"));
 const shelljs_1 = tslib_1.__importDefault(require("shelljs"));
+/** Custom error thrown when git is not found in `PATH`. */
 class GitNotFoundError extends Error {
 }
 exports.GitNotFoundError = GitNotFoundError;
-const getFileCommitDate = (file, { age = 'oldest', includeAuthor = false, }) => {
+/** Custom error thrown when the current file is not tracked by git. */
+class FileNotTrackedError extends Error {
+}
+exports.FileNotTrackedError = FileNotTrackedError;
+function getFileCommitDate(file, { age = 'oldest', includeAuthor = false, }) {
     if (!shelljs_1.default.which('git')) {
         throw new GitNotFoundError(`Failed to retrieve git history for "${file}" because git is not installed.`);
     }
     if (!shelljs_1.default.test('-f', file)) {
         throw new Error(`Failed to retrieve git history for "${file}" because the file does not exist.`);
     }
-    const fileBasename = path_1.default.basename(file);
-    const fileDirname = path_1.default.dirname(file);
     let formatArg = '--format=%ct';
     if (includeAuthor) {
         formatArg += ',%an';
@@ -32,9 +35,9 @@ const getFileCommitDate = (file, { age = 'oldest', includeAuthor = false, }) =>
         // --diff-filter=A ensures we only get the commit which (A)dded the file
         extraArgs += ' --follow --diff-filter=A';
     }
-    const result = shelljs_1.default.exec(`git log ${extraArgs} ${formatArg} -- "${fileBasename}"`, {
+    const result = shelljs_1.default.exec(`git log ${extraArgs} ${formatArg} -- "${path_1.default.basename(file)}"`, {
         // cwd is important, see: https://github.com/facebook/docusaurus/pull/5048
-        cwd: fileDirname,
+        cwd: path_1.default.dirname(file),
         silent: true,
     });
     if (result.code !== 0) {
@@ -45,11 +48,11 @@ const getFileCommitDate = (file, { age = 'oldest', includeAuthor = false, }) =>
         regex = /^(?<timestamp>\d+),(?<author>.+)$/;
     }
     const output = result.stdout.trim();
+    if (!output) {
+        throw new FileNotTrackedError(`Failed to retrieve the git history for file "${file}" because the file is not tracked by git.`);
+    }
     const match = output.match(regex);
-    if (!match ||
-        !match.groups ||
-        !match.groups.timestamp ||
-        (includeAuthor && !match.groups.author)) {
+    if (!match) {
         throw new Error(`Failed to retrieve the git history for file "${file}" with unexpected output: ${output}`);
     }
     const timestamp = Number(match.groups.timestamp);
@@ -58,6 +61,6 @@ const getFileCommitDate = (file, { age = 'oldest', includeAuthor = false, }) =>
         return { date, timestamp, author: match.groups.author };
     }
     return { date, timestamp };
-};
+}
 exports.getFileCommitDate = getFileCommitDate;
 //# sourceMappingURL=gitUtils.js.map

package/lib/gitUtils.js.map

@@ -1 +1 @@
-{"version":3,"file":"gitUtils.js","sourceRoot":"","sources":["../src/gitUtils.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;;AAEH,wDAAwB;AACxB,8DAA4B;AAE5B,MAAa,gBAAiB,SAAQ,KAAK;CAAG;AAA9C,4CAA8C;AAEvC,MAAM,iBAAiB,GAAG,CAC/B,IAAY,EACZ,EACE,GAAG,GAAG,QAAQ,EACd,aAAa,GAAG,KAAK,GAItB,EAKD,EAAE;IACF,IAAI,CAAC,iBAAK,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE;QACvB,MAAM,IAAI,gBAAgB,CACxB,uCAAuC,IAAI,iCAAiC,CAC7E,CAAC;KACH;IAED,IAAI,CAAC,iBAAK,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE;QAC3B,MAAM,IAAI,KAAK,CACb,uCAAuC,IAAI,oCAAoC,CAChF,CAAC;KACH;IAED,MAAM,YAAY,GAAG,cAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;IACzC,MAAM,WAAW,GAAG,cAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAEvC,IAAI,SAAS,GAAG,cAAc,CAAC;IAC/B,IAAI,aAAa,EAAE;QACjB,SAAS,IAAI,MAAM,CAAC;KACrB;IAED,IAAI,SAAS,GAAG,eAAe,CAAC;IAChC,IAAI,GAAG,KAAK,QAAQ,EAAE;QACpB,+CAA+C;QAC/C,wEAAwE;QACxE,SAAS,IAAI,2BAA2B,CAAC;KAC1C;IAED,MAAM,MAAM,GAAG,iBAAK,CAAC,IAAI,CACvB,WAAW,SAAS,IAAI,SAAS,QAAQ,YAAY,GAAG,EACxD;QACE,0EAA0E;QAC1E,GAAG,EAAE,WAAW;QAChB,MAAM,EAAE,IAAI;KACb,CACF,CAAC;IACF,IAAI,MAAM,CAAC,IAAI,KAAK,CAAC,EAAE;QACrB,MAAM,IAAI,KAAK,CACb,gDAAgD,IAAI,oBAAoB,MAAM,CAAC,IAAI,KAAK,MAAM,CAAC,MAAM,EAAE,CACxG,CAAC;KACH;IACD,IAAI,KAAK,GAAG,qBAAqB,CAAC;IAClC,IAAI,aAAa,EAAE;QACjB,KAAK,GAAG,mCAAmC,CAAC;KAC7C;IAED,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;IACpC,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IAElC,IACE,CAAC,KAAK;QACN,CAAC,KAAK,CAAC,MAAM;QACb,CAAC,KAAK,CAAC,MAAM,CAAC,SAAS;QACvB,CAAC,aAAa,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,EACvC;QACA,MAAM,IAAI,KAAK,CACb,gDAAgD,IAAI,6BAA6B,MAAM,EAAE,CAC1F,CAAC;KACH;IAED,MAAM,SAAS,GAAG,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IACjD,MAAM,IAAI,GAAG,IAAI,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,CAAC;IAExC,IAAI,aAAa,EAAE;QACjB,OAAO,EAAC,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAC,CAAC;KACvD;IACD,OAAO,EAAC,IAAI,EAAE,SAAS,EAAC,CAAC;AAC3B,CAAC,CAAC;AAhFW,QAAA,iBAAiB,qBAgF5B"}
+{"version":3,"file":"gitUtils.js","sourceRoot":"","sources":["../src/gitUtils.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;;AAEH,wDAAwB;AACxB,8DAA4B;AAE5B,2DAA2D;AAC3D,MAAa,gBAAiB,SAAQ,KAAK;CAAG;AAA9C,4CAA8C;AAE9C,uEAAuE;AACvE,MAAa,mBAAoB,SAAQ,KAAK;CAAG;AAAjD,kDAAiD;AA2DjD,SAAgB,iBAAiB,CAC/B,IAAY,EACZ,EACE,GAAG,GAAG,QAAQ,EACd,aAAa,GAAG,KAAK,GAItB;IAMD,IAAI,CAAC,iBAAK,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE;QACvB,MAAM,IAAI,gBAAgB,CACxB,uCAAuC,IAAI,iCAAiC,CAC7E,CAAC;KACH;IAED,IAAI,CAAC,iBAAK,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE;QAC3B,MAAM,IAAI,KAAK,CACb,uCAAuC,IAAI,oCAAoC,CAChF,CAAC;KACH;IAED,IAAI,SAAS,GAAG,cAAc,CAAC;IAC/B,IAAI,aAAa,EAAE;QACjB,SAAS,IAAI,MAAM,CAAC;KACrB;IAED,IAAI,SAAS,GAAG,eAAe,CAAC;IAChC,IAAI,GAAG,KAAK,QAAQ,EAAE;QACpB,+CAA+C;QAC/C,wEAAwE;QACxE,SAAS,IAAI,2BAA2B,CAAC;KAC1C;IAED,MAAM,MAAM,GAAG,iBAAK,CAAC,IAAI,CACvB,WAAW,SAAS,IAAI,SAAS,QAAQ,cAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,EAC/D;QACE,0EAA0E;QAC1E,GAAG,EAAE,cAAI,CAAC,OAAO,CAAC,IAAI,CAAC;QACvB,MAAM,EAAE,IAAI;KACb,CACF,CAAC;IACF,IAAI,MAAM,CAAC,IAAI,KAAK,CAAC,EAAE;QACrB,MAAM,IAAI,KAAK,CACb,gDAAgD,IAAI,oBAAoB,MAAM,CAAC,IAAI,KAAK,MAAM,CAAC,MAAM,EAAE,CACxG,CAAC;KACH;IACD,IAAI,KAAK,GAAG,qBAAqB,CAAC;IAClC,IAAI,aAAa,EAAE;QACjB,KAAK,GAAG,mCAAmC,CAAC;KAC7C;IAED,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;IAEpC,IAAI,CAAC,MAAM,EAAE;QACX,MAAM,IAAI,mBAAmB,CAC3B,gDAAgD,IAAI,2CAA2C,CAChG,CAAC;KACH;IAED,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IAElC,IAAI,CAAC,KAAK,EAAE;QACV,MAAM,IAAI,KAAK,CACb,gDAAgD,IAAI,6BAA6B,MAAM,EAAE,CAC1F,CAAC;KACH;IAED,MAAM,SAAS,GAAG,MAAM,CAAC,KAAK,CAAC,MAAO,CAAC,SAAS,CAAC,CAAC;IAClD,MAAM,IAAI,GAAG,IAAI,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,CAAC;IAExC,IAAI,aAAa,EAAE;QACjB,OAAO,EAAC,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,CAAC,MAAO,CAAC,MAAO,EAAC,CAAC;KACzD;IACD,OAAO,EAAC,IAAI,EAAE,SAAS,EAAC,CAAC;AAC3B,CAAC;AA/ED,8CA+EC"}

package/lib/globUtils.d.ts

@@ -4,9 +4,36 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
+/** A re-export of the globby instance. */
 export { default as Globby } from 'globby';
+/**
+ * The default glob patterns we ignore when sourcing content.
+ * - Ignore files and folders starting with `_` recursively
+ * - Ignore tests
+ */
 export declare const GlobExcludeDefault: string[];
 declare type Matcher = (str: string) => boolean;
+/**
+ * A very thin wrapper around `Micromatch.makeRe`.
+ *
+ * @see {@link createAbsoluteFilePathMatcher}
+ * @param patterns A list of glob patterns.
+ * @returns A matcher handle that tells if a file path is matched by any of the
+ * patterns.
+ */
 export declare function createMatcher(patterns: string[]): Matcher;
+/**
+ * We use match patterns like `"** /_* /**"` (ignore the spaces), where `"_*"`
+ * should only be matched within a subfolder. This function would:
+ * - Match `/user/sebastien/website/docs/_partials/xyz.md`
+ * - Ignore `/user/_sebastien/website/docs/partials/xyz.md`
+ *
+ * @param patterns A list of glob patterns.
+ * @param rootFolders A list of root folders to resolve the glob from.
+ * @returns A matcher handle that tells if a file path is matched by any of the
+ * patterns, resolved from the first root folder that contains the path.
+ * @throws Throws when the returned matcher receives a path that doesn't belong
+ * to any of the `rootFolders`.
+ */
 export declare function createAbsoluteFilePathMatcher(patterns: string[], rootFolders: string[]): Matcher;
 //# sourceMappingURL=globUtils.d.ts.map

package/lib/globUtils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"globUtils.d.ts","sourceRoot":"","sources":["../src/globUtils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAOH,OAAO,EAAC,OAAO,IAAI,MAAM,EAAC,MAAM,QAAQ,CAAC;AAIzC,eAAO,MAAM,kBAAkB,UAU9B,CAAC;AAEF,aAAK,OAAO,GAAG,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;AAExC,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,OAAO,CAKzD;AAMD,wBAAgB,6BAA6B,CAC3C,QAAQ,EAAE,MAAM,EAAE,EAClB,WAAW,EAAE,MAAM,EAAE,GACpB,OAAO,CAmBT"}
+{"version":3,"file":"globUtils.d.ts","sourceRoot":"","sources":["../src/globUtils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAOH,0CAA0C;AAC1C,OAAO,EAAC,OAAO,IAAI,MAAM,EAAC,MAAM,QAAQ,CAAC;AAEzC;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,UAK9B,CAAC;AAEF,aAAK,OAAO,GAAG,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;AAExC;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,OAAO,CAKzD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,6BAA6B,CAC3C,QAAQ,EAAE,MAAM,EAAE,EAClB,WAAW,EAAE,MAAM,EAAE,GACpB,OAAO,CAmBT"}