@docusaurus/utils 2.0.0-beta.15a2b59f9 → 2.0.0-beta.17

package/src/markdownLinks.ts

@@ -5,8 +5,8 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import {resolve} from 'url';
-import {aliasedSitePath} from './index';
+import path from 'path';
+import {aliasedSitePath} from './pathUtils';
 
 export type ContentPaths = {
   contentPath: string;
@@ -45,9 +45,17 @@ export function replaceMarkdownLinks<T extends ContentPaths>({
 
   // Replace internal markdown linking (except in fenced blocks).
   let fencedBlock = false;
+  let lastCodeFence = '';
   const lines = fileString.split('\n').map((line) => {
     if (line.trim().startsWith('```')) {
-      fencedBlock = !fencedBlock;
+      if (!fencedBlock) {
+        fencedBlock = true;
+        [lastCodeFence] = line.trim().match(/^`+/)!;
+        // If we are in a ````-fenced block, all ``` would be plain text instead
+        // of fences
+      } else if (line.trim().match(/^`+/)![0].length >= lastCodeFence.length) {
+        fencedBlock = false;
+      }
     }
     if (fencedBlock) {
       return line;
@@ -55,24 +63,38 @@ export function replaceMarkdownLinks<T extends ContentPaths>({
 
     let modifiedLine = line;
     // Replace inline-style links or reference-style links e.g:
-    // This is [Document 1](doc1.md) -> we replace this doc1.md with correct link
+    // This is [Document 1](doc1.md) -> we replace this doc1.md with correct
+    // ink
     // [doc1]: doc1.md -> we replace this doc1.md with correct link
-    const mdRegex = /(?:(?:\]\()|(?:\]:\s?))(?!https)([^'")\]\s>]+\.mdx?)/g;
+    const mdRegex =
+      /(?:(?:\]\()|(?:\]:\s*))(?!https?:\/\/|@site\/)(?<filename>[^'")\]\s>]+\.mdx?)/g;
     let mdMatch = mdRegex.exec(modifiedLine);
     while (mdMatch !== null) {
       // Replace it to correct html link.
-      const mdLink = mdMatch[1];
+      const mdLink = mdMatch.groups!.filename;
+
+      const sourcesToTry = [
+        path.resolve(path.dirname(filePath), decodeURIComponent(mdLink)),
+        `${contentPathLocalized}/${decodeURIComponent(mdLink)}`,
+        `${contentPath}/${decodeURIComponent(mdLink)}`,
+      ];
 
-      const aliasedSource = (source: string) =>
-        aliasedSitePath(source, siteDir);
+      const aliasedSourceMatch = sourcesToTry
+        .map((source) => aliasedSitePath(source, siteDir))
+        .find((source) => sourceToPermalink[source]);
 
-      const permalink: string | undefined =
-        sourceToPermalink[aliasedSource(resolve(filePath, mdLink))] ||
-        sourceToPermalink[aliasedSource(`${contentPathLocalized}/${mdLink}`)] ||
-        sourceToPermalink[aliasedSource(`${contentPath}/${mdLink}`)];
+      const permalink: string | undefined = 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: BrokenMarkdownLink<T> = {
           contentPaths,

package/src/markdownParser.ts

@@ -5,10 +5,26 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import chalk from 'chalk';
-import fs from 'fs-extra';
+import logger from '@docusaurus/logger';
 import matter from 'gray-matter';
 
+// Input: ## Some heading {#some-heading}
+// Output: {text: "## Some heading", id: "some-heading"}
+export function parseMarkdownHeadingId(heading: string): {
+  text: string;
+  id?: string;
+} {
+  const customHeadingIdRegex = /^(?<text>.*?)\s*\{#(?<id>[\w-]+)\}$/;
+  const matches = customHeadingIdRegex.exec(heading);
+  if (matches) {
+    return {
+      text: matches.groups!.text,
+      id: matches.groups!.id,
+    };
+  }
+  return {text: heading, id: undefined};
+}
+
 // Hacky way of stripping out import statements from the excerpt
 // TODO: Find a better way to do so, possibly by compiling the Markdown content,
 // stripping out HTML tags and obtaining the first line.
@@ -18,9 +34,10 @@ export function createExcerpt(fileString: string): string | undefined {
     // Remove Markdown alternate title
     .replace(/^[^\n]*\n[=]+/g, '')
     .split('\n');
+  let inCode = false;
+  let lastCodeFence = '';
 
   /* eslint-disable no-continue */
-  // eslint-disable-next-line no-restricted-syntax
   for (const fileLine of fileLines) {
     // Skip empty line.
     if (!fileLine.trim()) {
@@ -28,7 +45,24 @@ export function createExcerpt(fileString: string): string | undefined {
     }
 
     // Skip import/export declaration.
-    if (/^\s*?import\s.*(from.*)?;?|export\s.*{.*};?/.test(fileLine)) {
+    if (/^(?:import|export)\s.*/.test(fileLine)) {
+      continue;
+    }
+
+    // Skip code block line.
+    if (fileLine.trim().startsWith('```')) {
+      if (!inCode) {
+        inCode = true;
+        [lastCodeFence] = fileLine.trim().match(/^`+/)!;
+        // If we are in a ````-fenced block, all ``` would be plain text instead
+        // of fences
+      } else if (
+        fileLine.trim().match(/^`+/)![0].length >= lastCodeFence.length
+      ) {
+        inCode = false;
+      }
+      continue;
+    } else if (inCode) {
       continue;
     }
 
@@ -36,25 +70,27 @@ export function createExcerpt(fileString: string): string | undefined {
       // Remove HTML tags.
       .replace(/<[^>]*>/g, '')
       // Remove Title headers
-      .replace(/^#\s*([^#]*)\s*#?/gm, '')
+      .replace(/^#\s*[^#]*\s*#?/gm, '')
       // Remove Markdown + ATX-style headers
-      .replace(/^#{1,6}\s*([^#]*)\s*(#{1,6})?/gm, '$1')
-      // Remove emphasis and strikethroughs.
-      .replace(/([*_~]{1,3})(\S.*?\S{0,1})\1/g, '$2')
+      .replace(/^#{1,6}\s*(?<text>[^#]*)\s*(?:#{1,6})?/gm, '$1')
+      // Remove emphasis.
+      .replace(/(?<opening>[*_]{1,3})(?<text>.*?)\1/g, '$2')
+      // Remove strikethroughs.
+      .replace(/~~(?<text>\S.*\S)~~/g, '$1')
       // Remove images.
-      .replace(/!\[(.*?)\][[(].*?[\])]/g, '$1')
+      .replace(/!\[(?<alt>.*?)\][[(].*?[\])]/g, '$1')
       // Remove footnotes.
-      .replace(/\[\^.+?\](: .*?$)?/g, '')
+      .replace(/\[\^.+?\](?:: .*?$)?/g, '')
       // Remove inline links.
-      .replace(/\[(.*?)\][[(].*?[\])]/g, '$1')
+      .replace(/\[(?<alt>.*?)\][[(].*?[\])]/g, '$1')
       // Remove inline code.
-      .replace(/`(.+?)`/g, '$1')
+      .replace(/`(?<text>.+?)`/g, '$1')
       // Remove blockquotes.
       .replace(/^\s{0,3}>\s?/g, '')
       // Remove admonition definition.
-      .replace(/(:{3}.*)/, '')
+      .replace(/:::.*/, '')
       // Remove Emoji names within colons include preceding whitespace.
-      .replace(/\s?(:(::|[^:\n])+:)/g, '')
+      .replace(/\s?:(?:::|[^:\n])+:/g, '')
       // Remove custom Markdown heading id.
       .replace(/{#*[\w-]+}/, '')
       .trim();
@@ -67,22 +103,22 @@ export function createExcerpt(fileString: string): string | undefined {
   return undefined;
 }
 
-export function parseFrontMatter(
-  markdownFileContent: string,
-): {
+export function parseFrontMatter(markdownFileContent: string): {
   frontMatter: Record<string, unknown>;
   content: string;
 } {
   const {data, content} = matter(markdownFileContent);
   return {
-    frontMatter: data ?? {},
-    content: content?.trim() ?? '',
+    frontMatter: data,
+    content: content.trim(),
   };
 }
 
-// Try to convert markdown heading as text
-// Does not need to be perfect, it is only used as a fallback when frontMatter.title is not provided
-// For now, we just unwrap possible inline code blocks (# `config.js`)
+/**
+ * Try to convert markdown heading to text. Does not need to be perfect, it is
+ * only used as a fallback when frontMatter.title is not provided. For now, we
+ * just unwrap possible inline code blocks (# `config.js`)
+ */
 function toTextContentTitle(contentTitle: string): string {
   if (contentTitle.startsWith('`') && contentTitle.endsWith('`')) {
     return contentTitle.substring(1, contentTitle.length - 1);
@@ -98,10 +134,11 @@ export function parseMarkdownContentTitle(
 
   const content = contentUntrimmed.trim();
 
-  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 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;
 
   const regularTitleMatch = new RegExp(
@@ -118,15 +155,14 @@ export function parseMarkdownContentTitle(
 
   if (!pattern || !title) {
     return {content, contentTitle: undefined};
-  } else {
-    const newContent = removeContentTitleOption
-      ? content.replace(pattern, '')
-      : content;
-    return {
-      content: newContent.trim(),
-      contentTitle: toTextContentTitle(title.trim()).trim(),
-    };
   }
+  const newContent = removeContentTitleOption
+    ? content.replace(pattern, '')
+    : content;
+  return {
+    content: newContent.trim(),
+    contentTitle: toTextContentTitle(title.trim()).trim(),
+  };
 }
 
 type ParsedMarkdown = {
@@ -141,9 +177,8 @@ export function parseMarkdownString(
   options?: {removeContentTitle?: boolean},
 ): ParsedMarkdown {
   try {
-    const {frontMatter, content: contentWithoutFrontMatter} = parseFrontMatter(
-      markdownFileContent,
-    );
+    const {frontMatter, content: contentWithoutFrontMatter} =
+      parseFrontMatter(markdownFileContent);
 
     const {content, contentTitle} = parseMarkdownContentTitle(
       contentWithoutFrontMatter,
@@ -158,25 +193,9 @@ export function parseMarkdownString(
       contentTitle,
       excerpt,
     };
-  } catch (e) {
-    console.error(
-      chalk.red(`Error while parsing Markdown frontmatter.
-This can happen if you use special characters in frontmatter values (try using double quotes around that value).`),
-    );
-    throw e;
-  }
-}
-
-export async function parseMarkdownFile(
-  source: string,
-  options?: {removeContentTitle?: boolean},
-): Promise<ParsedMarkdown> {
-  const markdownString = await fs.readFile(source, 'utf-8');
-  try {
-    return parseMarkdownString(markdownString, options);
-  } catch (e) {
-    throw new Error(
-      `Error while parsing Markdown file ${source}: "${e.message}".`,
-    );
+  } catch (err) {
+    logger.error(`Error while parsing Markdown front matter.
+This can happen if you use special characters in front matter values (try using double quotes around that value).`);
+    throw err;
   }
 }

package/src/pathUtils.ts

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

package/src/slugger.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.
+ */
+
+import GithubSlugger from 'github-slugger';
+
+// We create our own abstraction on top of the lib:
+// - unify usage everywhere in the codebase
+// - ability to add extra options
+export type SluggerOptions = {maintainCase?: boolean};
+
+export type Slugger = {
+  slug: (value: string, options?: SluggerOptions) => string;
+};
+
+export function createSlugger(): Slugger {
+  const githubSlugger = new GithubSlugger();
+  return {
+    slug: (value, options) => githubSlugger.slug(value, options?.maintainCase),
+  };
+}

package/src/tags.ts

@@ -0,0 +1,105 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import _ from 'lodash';
+import {normalizeUrl} from './urlUtils';
+
+export type Tag = {
+  label: string;
+  permalink: string;
+};
+
+export type FrontMatterTag = string | Tag;
+
+export function normalizeFrontMatterTag(
+  tagsPath: string,
+  frontMatterTag: FrontMatterTag,
+): Tag {
+  function toTagObject(tagString: string): Tag {
+    return {
+      label: tagString,
+      permalink: _.kebabCase(tagString),
+    };
+  }
+
+  // TODO maybe make ensure the permalink is valid url path?
+  function normalizeTagPermalink(permalink: string): string {
+    // 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 normalizeUrl([tagsPath, permalink]);
+  }
+
+  const tag: Tag =
+    typeof frontMatterTag === 'string'
+      ? toTagObject(frontMatterTag)
+      : frontMatterTag;
+
+  return {
+    label: tag.label,
+    permalink: normalizeTagPermalink(tag.permalink),
+  };
+}
+
+export function normalizeFrontMatterTags(
+  tagsPath: string,
+  frontMatterTags: FrontMatterTag[] | undefined = [],
+): Tag[] {
+  const tags = frontMatterTags.map((tag) =>
+    normalizeFrontMatterTag(tagsPath, tag),
+  );
+
+  return _.uniqBy(tags, (tag) => tag.permalink);
+}
+
+export type TaggedItemGroup<Item> = {
+  tag: Tag;
+  items: Item[];
+};
+
+/**
+ * Permits to group docs/blogPosts by tag (provided by front matter)
+ * 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
+ */
+export function groupTaggedItems<Item>(
+  items: Item[],
+  getItemTags: (item: Item) => Tag[],
+): Record<string, TaggedItemGroup<Item>> {
+  const result: Record<string, TaggedItemGroup<Item>> = {};
+
+  function handleItemTag(item: Item, tag: Tag) {
+    // 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] = result[tag.permalink] ?? {
+      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 = _.uniq(group.items);
+  });
+
+  return result;
+}

package/src/urlUtils.ts

@@ -0,0 +1,149 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import {removeSuffix} from './jsUtils';
+import resolvePathnameUnsafe from 'resolve-pathname';
+
+export function normalizeUrl(rawUrls: string[]): string {
+  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();
+    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('/');
+      }
+      // eslint-disable-next-line no-continue
+      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(/\/(?<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;
+}
+
+export function getEditUrl(
+  fileRelativePath: string,
+  editUrl?: string,
+): string | undefined {
+  return editUrl
+    ? // Don't use posixPath for this: we need to force a forward slash path
+      normalizeUrl([editUrl, fileRelativePath.replace(/\\/g, '/')])
+    : undefined;
+}
+
+/**
+ * Convert filepath to url path.
+ * Example: 'index.md' -> '/', 'foo/bar.js' -> '/foo/bar',
+ */
+export function fileToPath(file: string): string {
+  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, '/')}`;
+}
+
+export function encodePath(userPath: string): string {
+  return userPath
+    .split('/')
+    .map((item) => encodeURIComponent(item))
+    .join('/');
+}
+
+export function isValidPathname(str: string): boolean {
+  if (!str.startsWith('/')) {
+    return false;
+  }
+  try {
+    // weird, but is there a better way?
+    const parsedPathname = new URL(str, 'https://domain.com').pathname;
+    return parsedPathname === str || parsedPathname === encodeURI(str);
+  } catch {
+    return false;
+  }
+}
+
+// resolve pathname and fail fast if resolution fails
+export function resolvePathname(to: string, from?: string): string {
+  return resolvePathnameUnsafe(to, from);
+}
+export function addLeadingSlash(str: string): string {
+  return str.startsWith('/') ? str : `/${str}`;
+}
+
+// TODO deduplicate: also present in @docusaurus/utils-common
+export function addTrailingSlash(str: string): string {
+  return str.endsWith('/') ? str : `${str}/`;
+}
+export function removeTrailingSlash(str: string): string {
+  return removeSuffix(str, '/');
+}