@docusaurus/utils 2.0.0-beta.fc64c12e4 → 2.0.0

package/src/slugger.ts

@@ -0,0 +1,36 @@
+/**
+ * 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 = {
+  /** Keep the headings' casing, otherwise make all lowercase. */
+  maintainCase?: boolean;
+};
+
+export 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 function createSlugger(): Slugger {
+  const githubSlugger = new GithubSlugger();
+  return {
+    slug: (value, options) => githubSlugger.slug(value, options?.maintainCase),
+  };
+}

package/src/tags.ts

@@ -0,0 +1,130 @@
+/**
+ * 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';
+
+/** What the user configures. */
+export 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 type TagsListItem = Tag & {
+  /** Number of posts/docs with this tag. */
+  count: number;
+};
+
+/** What the tag's own page should know about the tag. */
+export type TagModule = TagsListItem & {
+  /** The tags list page's permalink. */
+  allTagsPath: string;
+};
+
+export type FrontMatterTag = string | Tag;
+
+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),
+  };
+}
+
+/**
+ * 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 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[] {
+  const tags = frontMatterTags.map((tag) =>
+    normalizeFrontMatterTag(tagsPath, tag),
+  );
+
+  return _.uniqBy(tags, (tag) => tag.permalink);
+}
+
+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 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>} {
+  const result: {[permalink: string]: TaggedItemGroup<Item>} = {};
+
+  items.forEach((item) => {
+    getItemTags(item).forEach((tag) => {
+      // 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[tag.permalink] ??= {
+        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 = _.uniq(group.items);
+  });
+
+  return result;
+}

package/src/urlUtils.ts

@@ -0,0 +1,234 @@
+/**
+ * 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 resolvePathnameUnsafe from 'resolve-pathname';
+import {removeSuffix} from './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.
+ */
+export function normalizeUrl(rawUrls: string[]): string {
+  const urls = [...rawUrls];
+  const resultArray = [];
+
+  let hasStartingSlash = false;
+  let hasEndingSlash = false;
+
+  const isNonEmptyArray = (arr: string[]): arr is [string, ...string[]] =>
+    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;
+}
+
+/**
+ * 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 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;
+}
+
+/**
+ * Converts file path to a reasonable URL path, e.g. `'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, '/')}`;
+}
+
+/**
+ * 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 function encodePath(userPath: string): string {
+  return userPath
+    .split('/')
+    .map((item) => encodeURIComponent(item))
+    .join('/');
+}
+
+/**
+ * Whether `str` is a valid pathname. It must be absolute, and not contain
+ * special characters.
+ */
+export function isValidPathname(str: string): boolean {
+  if (!str.startsWith('/')) {
+    return false;
+  }
+  try {
+    const parsedPathname = new URL(str, 'https://domain.com').pathname;
+    return parsedPathname === str || parsedPathname === encodeURI(str);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Resolve pathnames and fail-fast if resolution fails. Uses standard URL
+ * semantics (provided by `resolve-pathname` which is used internally by React
+ * router)
+ */
+export function resolvePathname(to: string, from?: string): string {
+  return resolvePathnameUnsafe(to, from);
+}
+/** Appends a leading slash to `str`, if one doesn't exist. */
+export function addLeadingSlash(str: string): string {
+  return str.startsWith('/') ? str : `/${str}`;
+}
+
+// TODO deduplicate: also present in @docusaurus/utils-common
+/** Appends a trailing slash to `str`, if one doesn't exist. */
+export function addTrailingSlash(str: string): string {
+  return str.endsWith('/') ? str : `${str}/`;
+}
+
+/** Removes the trailing slash from `str`. */
+export function removeTrailingSlash(str: string): string {
+  return removeSuffix(str, '/');
+}
+
+/** Constructs an SSH URL that can be used to push to GitHub. */
+export function buildSshUrl(
+  githubHost: string,
+  organizationName: string,
+  projectName: string,
+  githubPort?: string,
+): string {
+  if (githubPort) {
+    return `ssh://git@${githubHost}:${githubPort}/${organizationName}/${projectName}.git`;
+  }
+  return `git@${githubHost}:${organizationName}/${projectName}.git`;
+}
+
+/** Constructs an HTTP URL that can be used to push to GitHub. */
+export function buildHttpsUrl(
+  gitCredentials: string,
+  githubHost: string,
+  organizationName: string,
+  projectName: string,
+  githubPort?: string,
+): string {
+  if (githubPort) {
+    return `https://${gitCredentials}@${githubHost}:${githubPort}/${organizationName}/${projectName}.git`;
+  }
+  return `https://${gitCredentials}@${githubHost}/${organizationName}/${projectName}.git`;
+}
+
+/**
+ * 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 function hasSSHProtocol(sourceRepoUrl: string): boolean {
+  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);
+  }
+}

package/src/webpackUtils.ts

@@ -0,0 +1,153 @@
+/**
+ * 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 path from 'path';
+import {escapePath} from './pathUtils';
+import {
+  WEBPACK_URL_LOADER_LIMIT,
+  OUTPUT_STATIC_ASSETS_DIR_NAME,
+} from './constants';
+import type {RuleSetRule} from 'webpack';
+
+type AssetFolder = 'images' | 'files' | 'fonts' | 'medias';
+
+type FileLoaderUtils = {
+  loaders: {
+    file: (options: {folder: AssetFolder}) => RuleSetRule;
+    url: (options: {folder: AssetFolder}) => RuleSetRule;
+    inlineMarkdownImageFileLoader: string;
+    inlineMarkdownLinkFileLoader: string;
+  };
+  rules: {
+    images: () => RuleSetRule;
+    fonts: () => RuleSetRule;
+    media: () => RuleSetRule;
+    svg: () => RuleSetRule;
+    otherAssets: () => RuleSetRule;
+  };
+};
+
+/**
+ * Returns unified loader configurations to be used for various file types.
+ *
+ * Inspired by https://github.com/gatsbyjs/gatsby/blob/8e6e021014da310b9cc7d02e58c9b3efe938c665/packages/gatsby/src/utils/webpack-utils.ts#L447
+ */
+export function getFileLoaderUtils(): FileLoaderUtils {
+  // Files/images < urlLoaderLimit will be inlined as base64 strings directly in
+  // the html
+  const urlLoaderLimit = WEBPACK_URL_LOADER_LIMIT;
+
+  const fileLoaderFileName = (folder: AssetFolder) =>
+    path.posix.join(
+      OUTPUT_STATIC_ASSETS_DIR_NAME,
+      folder,
+      '[name]-[contenthash].[ext]',
+    );
+
+  const loaders: FileLoaderUtils['loaders'] = {
+    file: (options: {folder: AssetFolder}) => ({
+      loader: require.resolve(`file-loader`),
+      options: {
+        name: fileLoaderFileName(options.folder),
+      },
+    }),
+    url: (options: {folder: AssetFolder}) => ({
+      loader: require.resolve('url-loader'),
+      options: {
+        limit: urlLoaderLimit,
+        name: fileLoaderFileName(options.folder),
+        fallback: require.resolve('file-loader'),
+      },
+    }),
+
+    // TODO avoid conflicts with the ideal-image plugin
+    // TODO this may require a little breaking change for ideal-image users?
+    // Maybe with the ideal image plugin, all md images should be "ideal"?
+    // This is used to force url-loader+file-loader on markdown images
+    // https://webpack.js.org/concepts/loaders/#inline
+    inlineMarkdownImageFileLoader: `!${escapePath(
+      require.resolve('url-loader'),
+    )}?limit=${urlLoaderLimit}&name=${fileLoaderFileName(
+      'images',
+    )}&fallback=${escapePath(require.resolve('file-loader'))}!`,
+    inlineMarkdownLinkFileLoader: `!${escapePath(
+      require.resolve('file-loader'),
+    )}?name=${fileLoaderFileName('files')}!`,
+  };
+
+  const rules: FileLoaderUtils['rules'] = {
+    /**
+     * Loads image assets, inlines images via a data URI if they are below
+     * the size threshold
+     */
+    images: () => ({
+      use: [loaders.url({folder: 'images'})],
+      test: /\.(?:ico|jpe?g|png|gif|webp)(?:\?.*)?$/i,
+    }),
+
+    fonts: () => ({
+      use: [loaders.url({folder: 'fonts'})],
+      test: /\.(?:woff2?|eot|ttf|otf)$/i,
+    }),
+
+    /**
+     * Loads audio and video and inlines them via a data URI if they are below
+     * the size threshold
+     */
+    media: () => ({
+      use: [loaders.url({folder: 'medias'})],
+      test: /\.(?:mp4|webm|ogv|wav|mp3|m4a|aac|oga|flac)$/i,
+    }),
+
+    svg: () => ({
+      test: /\.svg$/i,
+      oneOf: [
+        {
+          use: [
+            {
+              loader: require.resolve('@svgr/webpack'),
+              options: {
+                prettier: false,
+                svgo: true,
+                svgoConfig: {
+                  plugins: [
+                    {
+                      name: 'preset-default',
+                      params: {
+                        overrides: {
+                          removeTitle: false,
+                          removeViewBox: false,
+                        },
+                      },
+                    },
+                  ],
+                },
+                titleProp: true,
+                ref: ![path],
+              },
+            },
+          ],
+          // We don't want to use SVGR loader for non-React source code
+          // ie we don't want to use SVGR for CSS files...
+          issuer: {
+            and: [/\.(?:tsx?|jsx?|mdx?)$/i],
+          },
+        },
+        {
+          use: [loaders.url({folder: 'images'})],
+        },
+      ],
+    }),
+
+    otherAssets: () => ({
+      use: [loaders.file({folder: 'files'})],
+      test: /\.(?:pdf|docx?|xlsx?|zip|rar)$/i,
+    }),
+  };
+
+  return {loaders, rules};
+}