@docusaurus/utils 2.0.0-beta.677e53d4d → 2.0.0-beta.7

package/lib/index.js

@@ -6,28 +6,37 @@
  * LICENSE file in the root directory of this source tree.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.parseMarkdownHeadingId = exports.updateTranslationFileMessages = exports.getSwizzledComponent = exports.mergeTranslations = exports.reportMessage = exports.getFolderContainingFile = exports.findFolderContainingFile = exports.findAsyncSequential = exports.mapAsyncSequencial = exports.getPluginI18nPath = exports.getElementsAround = exports.removePrefix = exports.removeSuffix = exports.removeTrailingSlash = exports.addTrailingSlash = exports.addTrailingPathSeparator = exports.addLeadingSlash = exports.resolvePathname = exports.isValidPathname = exports.getEditUrl = exports.aliasedSitePath = exports.normalizeUrl = exports.getSubFolder = exports.idx = exports.genChunkName = exports.toMessageRelativeFilePath = exports.genComponentName = exports.upperFirst = exports.encodePath = exports.fileToPath = exports.objectWithKeySorted = exports.generate = exports.docuHash = exports.simpleHash = exports.md5Hash = exports.posixPath = void 0;
+exports.parseMarkdownHeadingId = exports.updateTranslationFileMessages = exports.getSwizzledComponent = exports.mergeTranslations = exports.reportMessage = exports.getFolderContainingFile = exports.findFolderContainingFile = exports.findAsyncSequential = exports.mapAsyncSequencial = exports.getPluginI18nPath = exports.getElementsAround = exports.removePrefix = exports.removeSuffix = exports.removeTrailingSlash = exports.addTrailingSlash = exports.addTrailingPathSeparator = exports.addLeadingSlash = exports.resolvePathname = exports.isValidPathname = exports.getEditUrl = exports.aliasedSitePath = exports.getSubFolder = exports.idx = exports.genChunkName = exports.toMessageRelativeFilePath = exports.genComponentName = exports.upperFirst = exports.encodePath = exports.fileToPath = exports.objectWithKeySorted = exports.generate = exports.createAbsoluteFilePathMatcher = exports.createMatcher = exports.GlobExcludeDefault = exports.Globby = exports.docuHash = exports.simpleHash = exports.md5Hash = exports.posixPath = void 0;
 const tslib_1 = require("tslib");
-const chalk_1 = tslib_1.__importDefault(require("chalk"));
-const path_1 = tslib_1.__importDefault(require("path"));
+const chalk_1 = (0, tslib_1.__importDefault)(require("chalk"));
+const path_1 = (0, tslib_1.__importDefault)(require("path"));
 const crypto_1 = require("crypto");
 const lodash_1 = require("lodash");
-const escape_string_regexp_1 = tslib_1.__importDefault(require("escape-string-regexp"));
-const fs_extra_1 = tslib_1.__importDefault(require("fs-extra"));
+const escape_string_regexp_1 = (0, tslib_1.__importDefault)(require("escape-string-regexp"));
+const fs_extra_1 = (0, tslib_1.__importDefault)(require("fs-extra"));
 const url_1 = require("url");
 // @ts-expect-error: no typedefs :s
-const resolve_pathname_1 = tslib_1.__importDefault(require("resolve-pathname"));
+const resolve_pathname_1 = (0, tslib_1.__importDefault)(require("resolve-pathname"));
 const posixPath_1 = require("./posixPath");
 const hashUtils_1 = require("./hashUtils");
+const normalizeUrl_1 = require("./normalizeUrl");
+(0, tslib_1.__exportStar)(require("./mdxUtils"), exports);
+(0, tslib_1.__exportStar)(require("./normalizeUrl"), exports);
+(0, tslib_1.__exportStar)(require("./tags"), exports);
 exports.posixPath = posixPath_1.posixPath;
-tslib_1.__exportStar(require("./codeTranslationsUtils"), exports);
-tslib_1.__exportStar(require("./markdownParser"), exports);
-tslib_1.__exportStar(require("./markdownLinks"), exports);
-tslib_1.__exportStar(require("./escapePath"), exports);
+(0, tslib_1.__exportStar)(require("./codeTranslationsUtils"), exports);
+(0, tslib_1.__exportStar)(require("./markdownParser"), exports);
+(0, tslib_1.__exportStar)(require("./markdownLinks"), exports);
+(0, tslib_1.__exportStar)(require("./escapePath"), exports);
 var hashUtils_2 = require("./hashUtils");
 Object.defineProperty(exports, "md5Hash", { enumerable: true, get: function () { return hashUtils_2.md5Hash; } });
 Object.defineProperty(exports, "simpleHash", { enumerable: true, get: function () { return hashUtils_2.simpleHash; } });
 Object.defineProperty(exports, "docuHash", { enumerable: true, get: function () { return hashUtils_2.docuHash; } });
+var globUtils_1 = require("./globUtils");
+Object.defineProperty(exports, "Globby", { enumerable: true, get: function () { return globUtils_1.Globby; } });
+Object.defineProperty(exports, "GlobExcludeDefault", { enumerable: true, get: function () { return globUtils_1.GlobExcludeDefault; } });
+Object.defineProperty(exports, "createMatcher", { enumerable: true, get: function () { return globUtils_1.createMatcher; } });
+Object.defineProperty(exports, "createAbsoluteFilePathMatcher", { enumerable: true, get: function () { return globUtils_1.createAbsoluteFilePathMatcher; } });
 const fileHash = new Map();
 async function generate(generatedFilesDir, file, content, skipCache = process.env.NODE_ENV === 'production') {
     const filepath = path_1.default.join(generatedFilesDir, file);
@@ -42,10 +51,10 @@ async function generate(generatedFilesDir, file, content, skipCache = process.en
     // This is to avoid unnecessary overwriting and we can reuse old file.
     if (!lastHash && fs_extra_1.default.existsSync(filepath)) {
         const lastContent = await fs_extra_1.default.readFile(filepath, 'utf8');
-        lastHash = crypto_1.createHash('md5').update(lastContent).digest('hex');
+        lastHash = (0, crypto_1.createHash)('md5').update(lastContent).digest('hex');
         fileHash.set(filepath, lastHash);
     }
-    const currentHash = crypto_1.createHash('md5').update(content).digest('hex');
+    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);
@@ -99,8 +108,8 @@ function genComponentName(pagePath) {
     if (pagePath === '/') {
         return 'index';
     }
-    const pageHash = hashUtils_1.docuHash(pagePath);
-    return upperFirst(lodash_1.camelCase(pageHash));
+    const pageHash = (0, hashUtils_1.docuHash)(pagePath);
+    return upperFirst((0, lodash_1.camelCase)(pageHash));
 }
 exports.genComponentName = genComponentName;
 // When you want to display a path in a message/warning/error,
@@ -111,7 +120,7 @@ exports.genComponentName = genComponentName;
 // 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 exports.posixPath(path_1.default.relative(process.cwd(), filePath));
+    return (0, exports.posixPath)(path_1.default.relative(process.cwd(), filePath));
 }
 exports.toMessageRelativeFilePath = toMessageRelativeFilePath;
 const chunkNameCache = new Map();
@@ -122,15 +131,15 @@ function genChunkName(modulePath, prefix, preferredName, shortId = process.env.N
     let chunkName = chunkNameCache.get(modulePath);
     if (!chunkName) {
         if (shortId) {
-            chunkName = hashUtils_1.simpleHash(modulePath, 8);
+            chunkName = (0, hashUtils_1.simpleHash)(modulePath, 8);
         }
         else {
             let str = modulePath;
             if (preferredName) {
-                const shortHash = hashUtils_1.simpleHash(modulePath, 3);
+                const shortHash = (0, hashUtils_1.simpleHash)(modulePath, 3);
                 str = `${preferredName}${shortHash}`;
             }
-            const name = str === '/' ? 'index' : hashUtils_1.docuHash(str);
+            const name = str === '/' ? 'index' : (0, hashUtils_1.docuHash)(str);
             chunkName = prefix ? `${prefix}---${name}` : name;
         }
         chunkNameCache.set(modulePath, chunkName);
@@ -152,77 +161,20 @@ exports.idx = idx;
  * Given a filepath and dirpath, get the first directory.
  */
 function getSubFolder(file, refDir) {
-    const separator = escape_string_regexp_1.default(path_1.default.sep);
-    const baseDir = escape_string_regexp_1.default(path_1.default.basename(refDir));
+    const separator = (0, escape_string_regexp_1.default)(path_1.default.sep);
+    const baseDir = (0, escape_string_regexp_1.default)(path_1.default.basename(refDir));
     const regexSubFolder = new RegExp(`${baseDir}${separator}(.*?)${separator}.*`);
     const match = regexSubFolder.exec(file);
     return match && match[1];
 }
 exports.getSubFolder = getSubFolder;
-function normalizeUrl(rawUrls) {
-    const urls = [...rawUrls];
-    const resultArray = [];
-    let hasStartingSlash = false;
-    let hasEndingSlash = false;
-    // 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();
-        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(/^([^/:]+):\/*/, replacement);
-    // eslint-disable-next-line
-    for (let i = 0; i < urls.length; i++) {
-        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('/');
-            }
-            // eslint-disable-next-line
-            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[0] === '/' && !hasStartingSlash ? '/' : '');
-            }
-            hasEndingSlash = component[component.length - 1] === '/';
-            // 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(/\/(\?|&|#[^!])/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(/([^:]\/)\/+/g, '$1');
-    // Dedupe forward slashes at the beginning of the path.
-    str = str.replace(/^\/+/g, '/');
-    return str;
-}
-exports.normalizeUrl = normalizeUrl;
 /**
  * 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 = exports.posixPath(path_1.default.relative(siteDir, filePath));
+    const relativePath = (0, exports.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}`;
@@ -230,7 +182,7 @@ function aliasedSitePath(filePath, siteDir) {
 exports.aliasedSitePath = aliasedSitePath;
 function getEditUrl(fileRelativePath, editUrl) {
     return editUrl
-        ? normalizeUrl([editUrl, exports.posixPath(fileRelativePath)])
+        ? (0, normalizeUrl_1.normalizeUrl)([editUrl, (0, exports.posixPath)(fileRelativePath)])
         : undefined;
 }
 exports.getEditUrl = getEditUrl;
@@ -250,7 +202,7 @@ function isValidPathname(str) {
 exports.isValidPathname = isValidPathname;
 // resolve pathname and fail fast if resolution fails
 function resolvePathname(to, from) {
-    return resolve_pathname_1.default(to, from);
+    return (0, resolve_pathname_1.default)(to, from);
 }
 exports.resolvePathname = resolvePathname;
 function addLeadingSlash(str) {
@@ -378,7 +330,7 @@ exports.getSwizzledComponent = getSwizzledComponent;
 function updateTranslationFileMessages(translationFile, updateMessage) {
     return {
         ...translationFile,
-        content: lodash_1.mapValues(translationFile.content, (translation) => ({
+        content: (0, lodash_1.mapValues)(translationFile.content, (translation) => ({
             ...translation,
             message: updateMessage(translation.message),
         })),

package/lib/markdownLinks.js

@@ -7,7 +7,8 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.replaceMarkdownLinks = void 0;
-const url_1 = require("url");
+const tslib_1 = require("tslib");
+const path_1 = (0, tslib_1.__importDefault)(require("path"));
 const index_1 = require("./index");
 function replaceMarkdownLinks({ siteDir, fileString, filePath, contentPaths, sourceToPermalink, }) {
     const { contentPath, contentPathLocalized } = contentPaths;
@@ -30,12 +31,24 @@ function replaceMarkdownLinks({ siteDir, fileString, filePath, contentPaths, sou
         while (mdMatch !== null) {
             // Replace it to correct html link.
             const mdLink = mdMatch[1];
-            const aliasedSource = (source) => index_1.aliasedSitePath(source, siteDir);
-            const permalink = sourceToPermalink[aliasedSource(url_1.resolve(filePath, mdLink))] ||
-                sourceToPermalink[aliasedSource(`${contentPathLocalized}/${mdLink}`)] ||
-                sourceToPermalink[aliasedSource(`${contentPath}/${mdLink}`)];
+            const sourcesToTry = [
+                path_1.default.resolve(path_1.default.dirname(filePath), decodeURIComponent(mdLink)),
+                `${contentPathLocalized}/${decodeURIComponent(mdLink)}`,
+                `${contentPath}/${decodeURIComponent(mdLink)}`,
+            ];
+            const aliasedSourceMatch = sourcesToTry
+                .map((source) => (0, index_1.aliasedSitePath)(source, siteDir))
+                .find((source) => sourceToPermalink[source]);
+            const permalink = aliasedSourceMatch
+                ? sourceToPermalink[aliasedSourceMatch]
+                : undefined;
             if (permalink) {
-                modifiedLine = modifiedLine.replace(mdLink, permalink);
+                // MDX won't be happy if the permalink contains a space, we need to convert it to %20
+                const encodedPermalink = permalink
+                    .split('/')
+                    .map((part) => part.replace(/\s/g, '%20'))
+                    .join('/');
+                modifiedLine = modifiedLine.replace(mdLink, encodedPermalink);
             }
             else {
                 const brokenMarkdownLink = {

package/lib/markdownParser.js

@@ -8,9 +8,9 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.parseMarkdownFile = exports.parseMarkdownString = exports.parseMarkdownContentTitle = exports.parseFrontMatter = exports.createExcerpt = void 0;
 const tslib_1 = require("tslib");
-const chalk_1 = tslib_1.__importDefault(require("chalk"));
-const fs_extra_1 = tslib_1.__importDefault(require("fs-extra"));
-const gray_matter_1 = tslib_1.__importDefault(require("gray-matter"));
+const chalk_1 = (0, tslib_1.__importDefault)(require("chalk"));
+const fs_extra_1 = (0, tslib_1.__importDefault)(require("fs-extra"));
+const gray_matter_1 = (0, tslib_1.__importDefault)(require("gray-matter"));
 // 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.
@@ -20,6 +20,7 @@ function createExcerpt(fileString) {
         // Remove Markdown alternate title
         .replace(/^[^\n]*\n[=]+/g, '')
         .split('\n');
+    let inCode = false;
     /* eslint-disable no-continue */
     // eslint-disable-next-line no-restricted-syntax
     for (const fileLine of fileLines) {
@@ -31,6 +32,14 @@ function createExcerpt(fileString) {
         if (/^\s*?import\s.*(from.*)?;?|export\s.*{.*};?/.test(fileLine)) {
             continue;
         }
+        // Skip code block line.
+        if (fileLine.trim().startsWith('```')) {
+            inCode = !inCode;
+            continue;
+        }
+        else if (inCode) {
+            continue;
+        }
         const cleanedLine = fileLine
             // Remove HTML tags.
             .replace(/<[^>]*>/g, '')
@@ -66,7 +75,7 @@ function createExcerpt(fileString) {
 exports.createExcerpt = createExcerpt;
 function parseFrontMatter(markdownFileContent) {
     var _a;
-    const { data, content } = gray_matter_1.default(markdownFileContent);
+    const { data, content } = (0, gray_matter_1.default)(markdownFileContent);
     return {
         frontMatter: data !== null && data !== void 0 ? data : {},
         content: (_a = content === null || content === void 0 ? void 0 : content.trim()) !== null && _a !== void 0 ? _a : '',
@@ -86,8 +95,7 @@ function parseMarkdownContentTitle(contentUntrimmed, options) {
     var _a, _b;
     const removeContentTitleOption = (_a = options === null || options === void 0 ? void 0 : options.removeContentTitle) !== null && _a !== void 0 ? _a : false;
     const content = contentUntrimmed.trim();
-    const IMPORT_STATEMENT = /import\s+(([\w*{}\s\n,]+)from\s+)?["'\s]([@\w/_.-]+)["'\s];?|\n/
-        .source;
+    const IMPORT_STATEMENT = /import\s+(([\w*{}\s\n,]+)from\s+)?["'\s]([@\w/_.-]+)["'\s];?|\n/.source;
     const REGULAR_TITLE = /(?<pattern>#\s*(?<title>[^#\n{]*)+[ \t]*(?<suffix>({#*[\w-]+})|#)?\n*?)/
         .source;
     const ALTERNATE_TITLE = /(?<pattern>\s*(?<title>[^\n]*)\s*\n[=]+)/.source;

package/lib/mdxUtils.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 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.
+ */
+/**
+ * Transform mdx text to plain html text
+ * Initially created to convert MDX blog posts to HTML for the RSS feed
+ * without import/export nodes
+ *
+ * TODO not ideal implementation, won't work well with MDX elements!
+ * TODO theme+global site config should be able to declare MDX comps in scope for rendering the RSS feeds
+ * see also https://github.com/facebook/docusaurus/issues/4625
+ */
+export declare function mdxToHtml(mdxStr: string): string;

package/lib/mdxUtils.js

@@ -0,0 +1,30 @@
+"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.mdxToHtml = void 0;
+const tslib_1 = require("tslib");
+const react_1 = (0, tslib_1.__importDefault)(require("react"));
+const server_1 = (0, tslib_1.__importDefault)(require("react-dom/server"));
+const runtime_1 = (0, tslib_1.__importDefault)(require("@mdx-js/runtime"));
+const remark_mdx_remove_imports_1 = (0, tslib_1.__importDefault)(require("remark-mdx-remove-imports"));
+const remark_mdx_remove_exports_1 = (0, tslib_1.__importDefault)(require("remark-mdx-remove-exports"));
+/**
+ * Transform mdx text to plain html text
+ * Initially created to convert MDX blog posts to HTML for the RSS feed
+ * without import/export nodes
+ *
+ * TODO not ideal implementation, won't work well with MDX elements!
+ * TODO theme+global site config should be able to declare MDX comps in scope for rendering the RSS feeds
+ * see also https://github.com/facebook/docusaurus/issues/4625
+ */
+function mdxToHtml(mdxStr) {
+    return server_1.default.renderToString(react_1.default.createElement(runtime_1.default, { remarkPlugins: [remark_mdx_remove_imports_1.default, remark_mdx_remove_exports_1.default] }, [
+        mdxStr,
+    ]));
+}
+exports.mdxToHtml = mdxToHtml;

package/lib/normalizeUrl.d.ts

@@ -0,0 +1,7 @@
+/**
+ * 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 normalizeUrl(rawUrls: string[]): string;

package/lib/normalizeUrl.js

@@ -0,0 +1,66 @@
+"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.normalizeUrl = void 0;
+function normalizeUrl(rawUrls) {
+    const urls = [...rawUrls];
+    const resultArray = [];
+    let hasStartingSlash = false;
+    let hasEndingSlash = false;
+    // 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();
+        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(/^([^/:]+):\/*/, replacement);
+    // eslint-disable-next-line
+    for (let i = 0; i < urls.length; i++) {
+        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('/');
+            }
+            // eslint-disable-next-line
+            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[0] === '/' && !hasStartingSlash ? '/' : '');
+            }
+            hasEndingSlash = component[component.length - 1] === '/';
+            // 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(/\/(\?|&|#[^!])/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(/([^:]\/)\/+/g, '$1');
+    // Dedupe forward slashes at the beginning of the path.
+    str = str.replace(/^\/+/g, '/');
+    return str;
+}
+exports.normalizeUrl = normalizeUrl;

package/lib/tags.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 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 Tag = {
+    label: string;
+    permalink: string;
+};
+export declare type FrontMatterTag = string | Tag;
+export declare function normalizeFrontMatterTag(tagsPath: string, frontMatterTag: FrontMatterTag): Tag;
+export declare function normalizeFrontMatterTags(tagsPath: string, frontMatterTags: FrontMatterTag[] | undefined): Tag[];
+export declare type TaggedItemGroup<Item> = {
+    tag: Tag;
+    items: Item[];
+};
+export declare function groupTaggedItems<Item>(items: Item[], getItemTags: (item: Item) => Tag[]): Record<string, TaggedItemGroup<Item>>;

package/lib/tags.js

@@ -0,0 +1,72 @@
+"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 = exports.normalizeFrontMatterTag = void 0;
+const lodash_1 = require("lodash");
+const normalizeUrl_1 = require("./normalizeUrl");
+function normalizeFrontMatterTag(tagsPath, frontMatterTag) {
+    function toTagObject(tagString) {
+        return {
+            label: tagString,
+            permalink: (0, lodash_1.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, normalizeUrl_1.normalizeUrl)([tagsPath, permalink]);
+    }
+    const tag = typeof frontMatterTag === 'string'
+        ? toTagObject(frontMatterTag)
+        : frontMatterTag;
+    return {
+        label: tag.label,
+        permalink: normalizeTagPermalink(tag.permalink),
+    };
+}
+exports.normalizeFrontMatterTag = normalizeFrontMatterTag;
+function normalizeFrontMatterTags(tagsPath, frontMatterTags) {
+    var _a;
+    const tags = (_a = frontMatterTags === null || frontMatterTags === void 0 ? void 0 : frontMatterTags.map((tag) => normalizeFrontMatterTag(tagsPath, tag))) !== null && _a !== void 0 ? _a : [];
+    return (0, lodash_1.uniqBy)(tags, (tag) => tag.permalink);
+}
+exports.normalizeFrontMatterTags = normalizeFrontMatterTags;
+// Permits to group docs/blogPosts by tag (provided by FrontMatter)
+// Note: groups are 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 group/page in the end
+// We can't create 2 routes /some-label because one would override the other
+function groupTaggedItems(items, getItemTags) {
+    const result = {};
+    function handleItemTag(item, tag) {
+        var _a;
+        // Init missing tag groups
+        // TODO: it's not really clear what should be the behavior if 2 items have the same tag but the permalink is different for each
+        // For now, the first tag found wins
+        result[tag.permalink] = (_a = result[tag.permalink]) !== null && _a !== void 0 ? _a : {
+            tag,
+            items: [],
+        };
+        // Add item to group
+        result[tag.permalink].items.push(item);
+    }
+    items.forEach((item) => {
+        getItemTags(item).forEach((tag) => {
+            handleItemTag(item, tag);
+        });
+    });
+    // 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 = (0, lodash_1.uniq)(group.items);
+    });
+    return result;
+}
+exports.groupTaggedItems = groupTaggedItems;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/utils",
-  "version": "2.0.0-beta.677e53d4d",
+  "version": "2.0.0-beta.7",
   "description": "Node utility functions for Docusaurus packages.",
   "main": "./lib/index.js",
   "types": "./lib/index.d.ts",
@@ -18,22 +18,33 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@docusaurus/types": "2.0.0-beta.677e53d4d",
+    "@docusaurus/types": "2.0.0-beta.7",
+    "@mdx-js/runtime": "^1.6.22",
     "@types/github-slugger": "^1.3.0",
-    "chalk": "^4.1.1",
+    "chalk": "^4.1.2",
     "escape-string-regexp": "^4.0.0",
     "fs-extra": "^10.0.0",
+    "globby": "^11.0.4",
     "gray-matter": "^4.0.3",
     "lodash": "^4.17.20",
+    "micromatch": "^4.0.4",
+    "remark-mdx-remove-exports": "^1.6.22",
+    "remark-mdx-remove-imports": "^1.6.22",
     "resolve-pathname": "^3.0.0",
-    "tslib": "^2.2.0"
+    "tslib": "^2.3.1"
   },
   "engines": {
     "node": ">=12.13.0"
   },
   "devDependencies": {
     "@types/dedent": "^0.7.0",
+    "@types/micromatch": "^4.0.2",
+    "@types/react-dom": "^17.0.1",
     "dedent": "^0.7.0"
   },
-  "gitHead": "7fd8a4f8df207d6c603dec985604207d3b32a8bd"
+  "peerDependencies": {
+    "react": "*",
+    "react-dom": "*"
+  },
+  "gitHead": "71a934b4d7319cd026657e3bb7e5832447454d07"
 }