@docusaurus/utils 2.0.0-beta.ff31de0ff → 2.0.1

package/lib/pathUtils.js

@@ -0,0 +1,115 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.addTrailingPathSeparator = exports.escapePath = exports.aliasedSitePath = exports.toMessageRelativeFilePath = exports.posixPath = exports.shortName = exports.isNameTooLong = void 0;
+const tslib_1 = require("tslib");
+const path_1 = tslib_1.__importDefault(require("path"));
+// Based on https://github.com/gatsbyjs/gatsby/pull/21518/files
+// 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;
+// Space for appending things to the string like file extensions and so on
+const SPACE_FOR_APPENDING = 10;
+const isMacOs = () => process.platform === 'darwin';
+const isWindows = () => process.platform === 'win32';
+const isNameTooLong = (str) => 
+// Not entirely correct: we can't assume FS from OS. But good enough?
+isMacOs() || isWindows()
+    ? // Windows (NTFS) and macOS (APFS) filename length limit (255 chars)
+        str.length + SPACE_FOR_APPENDING > MAX_PATH_SEGMENT_CHARS
+    : // Other (255 bytes)
+        Buffer.from(str).length + SPACE_FOR_APPENDING > MAX_PATH_SEGMENT_BYTES;
+exports.isNameTooLong = isNameTooLong;
+function shortName(str) {
+    if (isMacOs() || isWindows()) {
+        const overflowingChars = str.length - MAX_PATH_SEGMENT_CHARS;
+        return str.slice(0, str.length - overflowingChars - SPACE_FOR_APPENDING - 1);
+    }
+    const strBuffer = Buffer.from(str);
+    const overflowingBytes = Buffer.byteLength(strBuffer) - MAX_PATH_SEGMENT_BYTES;
+    return strBuffer
+        .slice(0, Buffer.byteLength(strBuffer) - overflowingBytes - SPACE_FOR_APPENDING - 1)
+        .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 = str.startsWith('\\\\?\\');
+    // 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;
+function addTrailingPathSeparator(str) {
+    return str.endsWith(path_1.default.sep)
+        ? str
+        : // If this is Windows, we need to change the forward slash to backward
+            `${str.replace(/\/$/, '')}${path_1.default.sep}`;
+}
+exports.addTrailingPathSeparator = addTrailingPathSeparator;
+//# sourceMappingURL=pathUtils.js.map

package/lib/pathUtils.js.map

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

package/lib/shellUtils.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 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 escapeShellArg(s: string): string;
+//# sourceMappingURL=shellUtils.d.ts.map

package/lib/shellUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shellUtils.d.ts","sourceRoot":"","sources":["../src/shellUtils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAQH,wBAAgB,cAAc,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAIhD"}

package/lib/shellUtils.js

@@ -0,0 +1,21 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.escapeShellArg = void 0;
+// TODO move from shelljs to execa later?
+// Execa is well maintained and widely used
+// Even shelljs recommends execa for security / escaping:
+// https://github.com/shelljs/shelljs/wiki/Security-guidelines
+// Inspired by https://github.com/xxorax/node-shell-escape/blob/master/shell-escape.js
+function escapeShellArg(s) {
+    let res = `'${s.replace(/'/g, "'\\''")}'`;
+    res = res.replace(/^(?:'')+/g, '').replace(/\\'''/g, "\\'");
+    return res;
+}
+exports.escapeShellArg = escapeShellArg;
+//# sourceMappingURL=shellUtils.js.map

package/lib/shellUtils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shellUtils.js","sourceRoot":"","sources":["../src/shellUtils.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;AAEH,yCAAyC;AACzC,2CAA2C;AAC3C,yDAAyD;AACzD,8DAA8D;AAE9D,sFAAsF;AACtF,SAAgB,cAAc,CAAC,CAAS;IACtC,IAAI,GAAG,GAAG,IAAI,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,GAAG,CAAC;IAC1C,GAAG,GAAG,GAAG,CAAC,OAAO,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;IAC5D,OAAO,GAAG,CAAC;AACb,CAAC;AAJD,wCAIC"}

package/lib/slugger.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 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 type SluggerOptions = {
+    /** Keep the headings' casing, otherwise make all lowercase. */
+    maintainCase?: boolean;
+};
+export declare type Slugger = {
+    /**
+     * Takes a Markdown heading like "Josh Cena" and sluggifies it according to
+     * GitHub semantics (in this case `josh-cena`). Stateful, because if you try
+     * to sluggify "Josh Cena" again it would return `josh-cena-1`.
+     */
+    slug: (value: string, options?: SluggerOptions) => string;
+};
+/**
+ * A thin wrapper around github-slugger. This is a factory function that returns
+ * a stateful Slugger object.
+ */
+export declare function createSlugger(): Slugger;
+//# sourceMappingURL=slugger.d.ts.map

package/lib/slugger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"slugger.d.ts","sourceRoot":"","sources":["../src/slugger.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAOH,oBAAY,cAAc,GAAG;IAC3B,+DAA+D;IAC/D,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB,CAAC;AAEF,oBAAY,OAAO,GAAG;IACpB;;;;OAIG;IACH,IAAI,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,KAAK,MAAM,CAAC;CAC3D,CAAC;AAEF;;;GAGG;AACH,wBAAgB,aAAa,IAAI,OAAO,CAKvC"}

package/lib/slugger.js

@@ -0,0 +1,23 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSlugger = void 0;
+const tslib_1 = require("tslib");
+const github_slugger_1 = tslib_1.__importDefault(require("github-slugger"));
+/**
+ * A thin wrapper around github-slugger. This is a factory function that returns
+ * a stateful Slugger object.
+ */
+function createSlugger() {
+    const githubSlugger = new github_slugger_1.default();
+    return {
+        slug: (value, options) => githubSlugger.slug(value, options?.maintainCase),
+    };
+}
+exports.createSlugger = createSlugger;
+//# sourceMappingURL=slugger.js.map

package/lib/slugger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"slugger.js","sourceRoot":"","sources":["../src/slugger.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;;AAEH,4EAA2C;AAmB3C;;;GAGG;AACH,SAAgB,aAAa;IAC3B,MAAM,aAAa,GAAG,IAAI,wBAAa,EAAE,CAAC;IAC1C,OAAO;QACL,IAAI,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,CAAC,aAAa,CAAC,IAAI,CAAC,KAAK,EAAE,OAAO,EAAE,YAAY,CAAC;KAC3E,CAAC;AACJ,CAAC;AALD,sCAKC"}

package/lib/tags.d.ts

@@ -0,0 +1,59 @@
+/**
+ * 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.
+ */
+/** What the user configures. */
+export declare type Tag = {
+    label: string;
+    /** Permalink to this tag's page, without the `/tags/` base path. */
+    permalink: string;
+};
+/** What the tags list page should know about each tag. */
+export declare type TagsListItem = Tag & {
+    /** Number of posts/docs with this tag. */
+    count: number;
+};
+/** What the tag's own page should know about the tag. */
+export declare type TagModule = TagsListItem & {
+    /** The tags list page's permalink. */
+    allTagsPath: string;
+};
+export declare type FrontMatterTag = string | Tag;
+/**
+ * Takes tag objects as they are defined in front matter, and normalizes each
+ * into a standard tag object. The permalink is created by appending the
+ * sluggified label to `tagsPath`. Front matter tags already containing
+ * permalinks would still have `tagsPath` prepended.
+ *
+ * The result will always be unique by permalinks. The behavior with colliding
+ * permalinks is undetermined.
+ */
+export declare function normalizeFrontMatterTags(
+/** Base path to append the tag permalinks to. */
+tagsPath: string, 
+/** Can be `undefined`, so that we can directly pipe in `frontMatter.tags`. */
+frontMatterTags?: FrontMatterTag[] | undefined): Tag[];
+declare type TaggedItemGroup<Item> = {
+    tag: Tag;
+    items: Item[];
+};
+/**
+ * Permits to group docs/blog posts by tag (provided by front matter).
+ *
+ * @returns a map from tag permalink to the items and other relevant tag data.
+ * The record is indexed by permalink, because routes must be unique in the end.
+ * Labels may vary on 2 MD files but they are normalized. Docs with
+ * label='some label' and label='some-label' should end up in the same page.
+ */
+export declare function groupTaggedItems<Item>(items: readonly Item[], 
+/**
+ * A callback telling me how to get the tags list of the current item. Usually
+ * simply getting it from some metadata of the current item.
+ */
+getItemTags: (item: Item) => readonly Tag[]): {
+    [permalink: string]: TaggedItemGroup<Item>;
+};
+export {};
+//# sourceMappingURL=tags.d.ts.map

package/lib/tags.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tags.d.ts","sourceRoot":"","sources":["../src/tags.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,gCAAgC;AAChC,oBAAY,GAAG,GAAG;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,oEAAoE;IACpE,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,0DAA0D;AAC1D,oBAAY,YAAY,GAAG,GAAG,GAAG;IAC/B,0CAA0C;IAC1C,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,yDAAyD;AACzD,oBAAY,SAAS,GAAG,YAAY,GAAG;IACrC,sCAAsC;IACtC,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,oBAAY,cAAc,GAAG,MAAM,GAAG,GAAG,CAAC;AAgC1C;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB;AACtC,iDAAiD;AACjD,QAAQ,EAAE,MAAM;AAChB,8EAA8E;AAC9E,eAAe,GAAE,cAAc,EAAE,GAAG,SAAc,GACjD,GAAG,EAAE,CAMP;AAED,aAAK,eAAe,CAAC,IAAI,IAAI;IAC3B,GAAG,EAAE,GAAG,CAAC;IACT,KAAK,EAAE,IAAI,EAAE,CAAC;CACf,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EACnC,KAAK,EAAE,SAAS,IAAI,EAAE;AACtB;;;GAGG;AACH,WAAW,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,SAAS,GAAG,EAAE,GAC1C;IAAC,CAAC,SAAS,EAAE,MAAM,GAAG,eAAe,CAAC,IAAI,CAAC,CAAA;CAAC,CA0B9C"}

package/lib/tags.js

@@ -0,0 +1,91 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.groupTaggedItems = exports.normalizeFrontMatterTags = void 0;
+const tslib_1 = require("tslib");
+const lodash_1 = tslib_1.__importDefault(require("lodash"));
+const urlUtils_1 = require("./urlUtils");
+function normalizeFrontMatterTag(tagsPath, frontMatterTag) {
+    function toTagObject(tagString) {
+        return {
+            label: tagString,
+            permalink: lodash_1.default.kebabCase(tagString),
+        };
+    }
+    // TODO maybe make ensure the permalink is valid url path?
+    function normalizeTagPermalink(permalink) {
+        // 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, urlUtils_1.normalizeUrl)([tagsPath, permalink]);
+    }
+    const tag = typeof frontMatterTag === 'string'
+        ? toTagObject(frontMatterTag)
+        : frontMatterTag;
+    return {
+        label: tag.label,
+        permalink: normalizeTagPermalink(tag.permalink),
+    };
+}
+/**
+ * Takes tag objects as they are defined in front matter, and normalizes each
+ * into a standard tag object. The permalink is created by appending the
+ * sluggified label to `tagsPath`. Front matter tags already containing
+ * permalinks would still have `tagsPath` prepended.
+ *
+ * The result will always be unique by permalinks. The behavior with colliding
+ * permalinks is undetermined.
+ */
+function normalizeFrontMatterTags(
+/** Base path to append the tag permalinks to. */
+tagsPath, 
+/** Can be `undefined`, so that we can directly pipe in `frontMatter.tags`. */
+frontMatterTags = []) {
+    const tags = frontMatterTags.map((tag) => normalizeFrontMatterTag(tagsPath, tag));
+    return lodash_1.default.uniqBy(tags, (tag) => tag.permalink);
+}
+exports.normalizeFrontMatterTags = normalizeFrontMatterTags;
+/**
+ * Permits to group docs/blog posts by tag (provided by front matter).
+ *
+ * @returns a map from tag permalink to the items and other relevant tag data.
+ * The record is indexed by permalink, because routes must be unique in the end.
+ * Labels may vary on 2 MD files but they are normalized. Docs with
+ * label='some label' and label='some-label' should end up in the same page.
+ */
+function groupTaggedItems(items, 
+/**
+ * A callback telling me how to get the tags list of the current item. Usually
+ * simply getting it from some metadata of the current item.
+ */
+getItemTags) {
+    const result = {};
+    items.forEach((item) => {
+        getItemTags(item).forEach((tag) => {
+            var _a;
+            // Init missing tag groups
+            // TODO: it's not really clear what should be the behavior if 2 tags have
+            // the same permalink but the label is different for each
+            // For now, the first tag found wins
+            result[_a = tag.permalink] ?? (result[_a] = {
+                tag,
+                items: [],
+            });
+            // Add item to group
+            result[tag.permalink].items.push(item);
+        });
+    });
+    // If user add twice the same tag to a md doc (weird but possible),
+    // we don't want the item to appear twice in the list...
+    Object.values(result).forEach((group) => {
+        group.items = lodash_1.default.uniq(group.items);
+    });
+    return result;
+}
+exports.groupTaggedItems = groupTaggedItems;
+//# sourceMappingURL=tags.js.map

package/lib/tags.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tags.js","sourceRoot":"","sources":["../src/tags.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;;AAEH,4DAAuB;AACvB,yCAAwC;AAuBxC,SAAS,uBAAuB,CAC9B,QAAgB,EAChB,cAA8B;IAE9B,SAAS,WAAW,CAAC,SAAiB;QACpC,OAAO;YACL,KAAK,EAAE,SAAS;YAChB,SAAS,EAAE,gBAAC,CAAC,SAAS,CAAC,SAAS,CAAC;SAClC,CAAC;IACJ,CAAC;IAED,0DAA0D;IAC1D,SAAS,qBAAqB,CAAC,SAAiB;QAC9C,2EAA2E;QAC3E,2EAA2E;QAC3E,mDAAmD;QACnD,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;AAED;;;;;;;;GAQG;AACH,SAAgB,wBAAwB;AACtC,iDAAiD;AACjD,QAAgB;AAChB,8EAA8E;AAC9E,kBAAgD,EAAE;IAElD,MAAM,IAAI,GAAG,eAAe,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CACvC,uBAAuB,CAAC,QAAQ,EAAE,GAAG,CAAC,CACvC,CAAC;IAEF,OAAO,gBAAC,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;AAChD,CAAC;AAXD,4DAWC;AAOD;;;;;;;GAOG;AACH,SAAgB,gBAAgB,CAC9B,KAAsB;AACtB;;;GAGG;AACH,WAA2C;IAE3C,MAAM,MAAM,GAAiD,EAAE,CAAC;IAEhE,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,EAAE;QACrB,WAAW,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,CAAC,GAAG,EAAE,EAAE;;YAChC,0BAA0B;YAC1B,yEAAyE;YACzE,yDAAyD;YACzD,oCAAoC;YACpC,MAAM,MAAC,GAAG,CAAC,SAAS,MAApB,MAAM,OAAoB;gBACxB,GAAG;gBACH,KAAK,EAAE,EAAE;aACV,EAAC;YAEF,oBAAoB;YACpB,MAAM,CAAC,GAAG,CAAC,SAAS,CAAE,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC1C,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,gBAAC,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IACpC,CAAC,CAAC,CAAC;IAEH,OAAO,MAAM,CAAC;AAChB,CAAC;AAjCD,4CAiCC"}

package/lib/urlUtils.d.ts

@@ -0,0 +1,66 @@
+/**
+ * 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.
+ */
+/**
+ * Much like `path.join`, but much better. Takes an array of URL segments, and
+ * joins them into a reasonable URL.
+ *
+ * - `["file:", "/home", "/user/", "website"]` => `file:///home/user/website`
+ * - `["file://", "home", "/user/", "website"]` => `file://home/user/website` (relative!)
+ * - Remove trailing slash before parameters or hash.
+ * - Replace `?` in query parameters with `&`.
+ * - Dedupe forward slashes in the entire path, avoiding protocol slashes.
+ *
+ * @throws {TypeError} If any of the URL segment is not a string, this throws.
+ */
+export declare function normalizeUrl(rawUrls: string[]): string;
+/**
+ * Takes a file's path, relative to its content folder, and computes its edit
+ * URL. If `editUrl` is `undefined`, this returns `undefined`, as is the case
+ * when the user doesn't want an edit URL in her config.
+ */
+export declare function getEditUrl(fileRelativePath: string, editUrl?: string): string | undefined;
+/**
+ * Converts file path to a reasonable URL path, e.g. `'index.md'` -> `'/'`,
+ * `'foo/bar.js'` -> `'/foo/bar'`
+ */
+export declare function fileToPath(file: string): string;
+/**
+ * Similar to `encodeURI`, but uses `encodeURIComponent` and assumes there's no
+ * query.
+ *
+ * `encodeURI("/question?/answer")` => `"/question?/answer#section"`;
+ * `encodePath("/question?/answer#section")` => `"/question%3F/answer%23foo"`
+ */
+export declare function encodePath(userPath: string): string;
+/**
+ * Whether `str` is a valid pathname. It must be absolute, and not contain
+ * special characters.
+ */
+export declare function isValidPathname(str: string): boolean;
+/**
+ * Resolve pathnames and fail-fast if resolution fails. Uses standard URL
+ * semantics (provided by `resolve-pathname` which is used internally by React
+ * router)
+ */
+export declare function resolvePathname(to: string, from?: string): string;
+/** Appends a leading slash to `str`, if one doesn't exist. */
+export declare function addLeadingSlash(str: string): string;
+/** Appends a trailing slash to `str`, if one doesn't exist. */
+export declare function addTrailingSlash(str: string): string;
+/** Removes the trailing slash from `str`. */
+export declare function removeTrailingSlash(str: string): string;
+/** Constructs an SSH URL that can be used to push to GitHub. */
+export declare function buildSshUrl(githubHost: string, organizationName: string, projectName: string, githubPort?: string): string;
+/** Constructs an HTTP URL that can be used to push to GitHub. */
+export declare function buildHttpsUrl(gitCredentials: string, githubHost: string, organizationName: string, projectName: string, githubPort?: string): string;
+/**
+ * Whether the current URL is an SSH protocol. In addition to looking for
+ * `ssh:`, it will also allow protocol-less URLs like
+ * `git@github.com:facebook/docusaurus.git`.
+ */
+export declare function hasSSHProtocol(sourceRepoUrl: string): boolean;
+//# 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;AAKH;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,MAAM,CAoFtD;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CACxB,gBAAgB,EAAE,MAAM,EACxB,OAAO,CAAC,EAAE,MAAM,GACf,MAAM,GAAG,SAAS,CAKpB;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAQ/C;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAKnD;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAUpD;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAEjE;AACD,8DAA8D;AAC9D,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEnD;AAGD,+DAA+D;AAC/D,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED,6CAA6C;AAC7C,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED,gEAAgE;AAChE,wBAAgB,WAAW,CACzB,UAAU,EAAE,MAAM,EAClB,gBAAgB,EAAE,MAAM,EACxB,WAAW,EAAE,MAAM,EACnB,UAAU,CAAC,EAAE,MAAM,GAClB,MAAM,CAKR;AAED,iEAAiE;AACjE,wBAAgB,aAAa,CAC3B,cAAc,EAAE,MAAM,EACtB,UAAU,EAAE,MAAM,EAClB,gBAAgB,EAAE,MAAM,EACxB,WAAW,EAAE,MAAM,EACnB,UAAU,CAAC,EAAE,MAAM,GAClB,MAAM,CAKR;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAU7D"}

package/lib/urlUtils.js

@@ -0,0 +1,207 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hasSSHProtocol = exports.buildHttpsUrl = exports.buildSshUrl = exports.removeTrailingSlash = exports.addTrailingSlash = exports.addLeadingSlash = exports.resolvePathname = exports.isValidPathname = exports.encodePath = exports.fileToPath = exports.getEditUrl = exports.normalizeUrl = void 0;
+const tslib_1 = require("tslib");
+const resolve_pathname_1 = tslib_1.__importDefault(require("resolve-pathname"));
+const jsUtils_1 = require("./jsUtils");
+/**
+ * Much like `path.join`, but much better. Takes an array of URL segments, and
+ * joins them into a reasonable URL.
+ *
+ * - `["file:", "/home", "/user/", "website"]` => `file:///home/user/website`
+ * - `["file://", "home", "/user/", "website"]` => `file://home/user/website` (relative!)
+ * - Remove trailing slash before parameters or hash.
+ * - Replace `?` in query parameters with `&`.
+ * - Dedupe forward slashes in the entire path, avoiding protocol slashes.
+ *
+ * @throws {TypeError} If any of the URL segment is not a string, this throws.
+ */
+function normalizeUrl(rawUrls) {
+    const urls = [...rawUrls];
+    const resultArray = [];
+    let hasStartingSlash = false;
+    let hasEndingSlash = false;
+    const isNonEmptyArray = (arr) => arr.length > 0;
+    if (!isNonEmptyArray(urls)) {
+        return '';
+    }
+    // If the first part is a plain protocol, we combine it with the next part.
+    if (urls[0].match(/^[^/:]+:\/*$/) && urls.length > 1) {
+        const first = urls.shift();
+        if (first.startsWith('file:') && urls[0].startsWith('/')) {
+            // Force a double slash here, else we lose the information that the next
+            // segment is an absolute path
+            urls[0] = `${first}//${urls[0]}`;
+        }
+        else {
+            urls[0] = first + urls[0];
+        }
+    }
+    // There must be two or three slashes in the file protocol,
+    // two slashes in anything else.
+    const replacement = urls[0].match(/^file:\/\/\//) ? '$1:///' : '$1://';
+    urls[0] = urls[0].replace(/^(?<protocol>[^/:]+):\/*/, replacement);
+    for (let i = 0; i < urls.length; i += 1) {
+        let component = urls[i];
+        if (typeof component !== 'string') {
+            throw new TypeError(`Url must be a string. Received ${typeof component}`);
+        }
+        if (component === '') {
+            if (i === urls.length - 1 && hasEndingSlash) {
+                resultArray.push('/');
+            }
+            continue;
+        }
+        if (component !== '/') {
+            if (i > 0) {
+                // Removing the starting slashes for each component but the first.
+                component = component.replace(/^\/+/, 
+                // Special case where the first element of rawUrls is empty
+                // ["", "/hello"] => /hello
+                component.startsWith('/') && !hasStartingSlash ? '/' : '');
+            }
+            hasEndingSlash = component.endsWith('/');
+            // Removing the ending slashes for each component but the last. For the
+            // last component we will combine multiple slashes to a single one.
+            component = component.replace(/\/+$/, i < urls.length - 1 ? '' : '/');
+        }
+        hasStartingSlash = true;
+        resultArray.push(component);
+    }
+    let str = resultArray.join('/');
+    // Each input component is now separated by a single slash except the possible
+    // first plain protocol part.
+    // Remove trailing slash before parameters or hash.
+    str = str.replace(/\/(?<search>\?|&|#[^!])/g, '$1');
+    // Replace ? in parameters with &.
+    const parts = str.split('?');
+    str = parts.shift() + (parts.length > 0 ? '?' : '') + parts.join('&');
+    // Dedupe forward slashes in the entire path, avoiding protocol slashes.
+    str = str.replace(/(?<textBefore>[^:/]\/)\/+/g, '$1');
+    // Dedupe forward slashes at the beginning of the path.
+    str = str.replace(/^\/+/g, '/');
+    return str;
+}
+exports.normalizeUrl = normalizeUrl;
+/**
+ * Takes a file's path, relative to its content folder, and computes its edit
+ * URL. If `editUrl` is `undefined`, this returns `undefined`, as is the case
+ * when the user doesn't want an edit URL in her config.
+ */
+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;
+/**
+ * Converts file path to a reasonable URL path, e.g. `'index.md'` -> `'/'`,
+ * `'foo/bar.js'` -> `'/foo/bar'`
+ */
+function fileToPath(file) {
+    const indexRE = /(?<dirname>^|.*\/)index\.(?:mdx?|jsx?|tsx?)$/i;
+    const extRE = /\.(?:mdx?|jsx?|tsx?)$/;
+    if (indexRE.test(file)) {
+        return file.replace(indexRE, '/$1');
+    }
+    return `/${file.replace(extRE, '').replace(/\\/g, '/')}`;
+}
+exports.fileToPath = fileToPath;
+/**
+ * Similar to `encodeURI`, but uses `encodeURIComponent` and assumes there's no
+ * query.
+ *
+ * `encodeURI("/question?/answer")` => `"/question?/answer#section"`;
+ * `encodePath("/question?/answer#section")` => `"/question%3F/answer%23foo"`
+ */
+function encodePath(userPath) {
+    return userPath
+        .split('/')
+        .map((item) => encodeURIComponent(item))
+        .join('/');
+}
+exports.encodePath = encodePath;
+/**
+ * Whether `str` is a valid pathname. It must be absolute, and not contain
+ * special characters.
+ */
+function isValidPathname(str) {
+    if (!str.startsWith('/')) {
+        return false;
+    }
+    try {
+        const parsedPathname = new URL(str, 'https://domain.com').pathname;
+        return parsedPathname === str || parsedPathname === encodeURI(str);
+    }
+    catch {
+        return false;
+    }
+}
+exports.isValidPathname = isValidPathname;
+/**
+ * Resolve pathnames and fail-fast if resolution fails. Uses standard URL
+ * semantics (provided by `resolve-pathname` which is used internally by React
+ * router)
+ */
+function resolvePathname(to, from) {
+    return (0, resolve_pathname_1.default)(to, from);
+}
+exports.resolvePathname = resolvePathname;
+/** Appends a leading slash to `str`, if one doesn't exist. */
+function addLeadingSlash(str) {
+    return str.startsWith('/') ? str : `/${str}`;
+}
+exports.addLeadingSlash = addLeadingSlash;
+// TODO deduplicate: also present in @docusaurus/utils-common
+/** Appends a trailing slash to `str`, if one doesn't exist. */
+function addTrailingSlash(str) {
+    return str.endsWith('/') ? str : `${str}/`;
+}
+exports.addTrailingSlash = addTrailingSlash;
+/** Removes the trailing slash from `str`. */
+function removeTrailingSlash(str) {
+    return (0, jsUtils_1.removeSuffix)(str, '/');
+}
+exports.removeTrailingSlash = removeTrailingSlash;
+/** Constructs an SSH URL that can be used to push to GitHub. */
+function buildSshUrl(githubHost, organizationName, projectName, githubPort) {
+    if (githubPort) {
+        return `ssh://git@${githubHost}:${githubPort}/${organizationName}/${projectName}.git`;
+    }
+    return `git@${githubHost}:${organizationName}/${projectName}.git`;
+}
+exports.buildSshUrl = buildSshUrl;
+/** Constructs an HTTP URL that can be used to push to GitHub. */
+function buildHttpsUrl(gitCredentials, githubHost, organizationName, projectName, githubPort) {
+    if (githubPort) {
+        return `https://${gitCredentials}@${githubHost}:${githubPort}/${organizationName}/${projectName}.git`;
+    }
+    return `https://${gitCredentials}@${githubHost}/${organizationName}/${projectName}.git`;
+}
+exports.buildHttpsUrl = buildHttpsUrl;
+/**
+ * Whether the current URL is an SSH protocol. In addition to looking for
+ * `ssh:`, it will also allow protocol-less URLs like
+ * `git@github.com:facebook/docusaurus.git`.
+ */
+function hasSSHProtocol(sourceRepoUrl) {
+    try {
+        if (new URL(sourceRepoUrl).protocol === 'ssh:') {
+            return true;
+        }
+        return false;
+    }
+    catch {
+        // Fails when there isn't a protocol
+        return /^(?:[\w-]+@)?[\w.-]+:[\w./-]+/.test(sourceRepoUrl);
+    }
+}
+exports.hasSSHProtocol = hasSSHProtocol;
+//# sourceMappingURL=urlUtils.js.map