@docusaurus/utils 2.0.0-beta.0f144213d → 2.0.0-beta.11

package/src/__tests__/normalizeUrl.test.ts

@@ -0,0 +1,117 @@
+/**
+ * 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 {normalizeUrl} from '../normalizeUrl';
+
+describe('normalizeUrl', () => {
+  test('should normalize urls correctly', () => {
+    const asserts = [
+      {
+        input: ['/', ''],
+        output: '/',
+      },
+      {
+        input: ['', '/'],
+        output: '/',
+      },
+      {
+        input: ['/'],
+        output: '/',
+      },
+      {
+        input: [''],
+        output: '',
+      },
+      {
+        input: ['/', '/'],
+        output: '/',
+      },
+      {
+        input: ['/', 'docs'],
+        output: '/docs',
+      },
+      {
+        input: ['/', 'docs', 'en', 'next', 'blog'],
+        output: '/docs/en/next/blog',
+      },
+      {
+        input: ['/test/', '/docs', 'ro', 'doc1'],
+        output: '/test/docs/ro/doc1',
+      },
+      {
+        input: ['/test/', '/', 'ro', 'doc1'],
+        output: '/test/ro/doc1',
+      },
+      {
+        input: ['/', '/', '2020/02/29/leap-day'],
+        output: '/2020/02/29/leap-day',
+      },
+      {
+        input: ['', '/', 'ko', 'hello'],
+        output: '/ko/hello',
+      },
+      {
+        input: ['hello', 'world'],
+        output: 'hello/world',
+      },
+      {
+        input: ['http://www.google.com/', 'foo/bar', '?test=123'],
+        output: 'http://www.google.com/foo/bar?test=123',
+      },
+      {
+        input: ['http:', 'www.google.com///', 'foo/bar', '?test=123'],
+        output: 'http://www.google.com/foo/bar?test=123',
+      },
+      {
+        input: ['http://foobar.com', '', 'test'],
+        output: 'http://foobar.com/test',
+      },
+      {
+        input: ['http://foobar.com', '', 'test', '/'],
+        output: 'http://foobar.com/test/',
+      },
+      {
+        input: ['/', '', 'hello', '', '/', '/', '', '/', '/world'],
+        output: '/hello/world',
+      },
+      {
+        input: ['', '', '/tt', 'ko', 'hello'],
+        output: '/tt/ko/hello',
+      },
+      {
+        input: ['', '///hello///', '', '///world'],
+        output: '/hello/world',
+      },
+      {
+        input: ['', '/hello/', ''],
+        output: '/hello/',
+      },
+      {
+        input: ['', '/', ''],
+        output: '/',
+      },
+      {
+        input: ['///', '///'],
+        output: '/',
+      },
+      {
+        input: ['/', '/hello/world/', '///'],
+        output: '/hello/world/',
+      },
+    ];
+    asserts.forEach((testCase) => {
+      expect(normalizeUrl(testCase.input)).toBe(testCase.output);
+    });
+
+    expect(() =>
+      // @ts-expect-error undefined for test
+      normalizeUrl(['http:example.com', undefined]),
+    ).toThrowErrorMatchingInlineSnapshot(
+      `"Url must be a string. Received undefined"`,
+    );
+  });
+});

package/src/__tests__/pathUtils.test.ts

@@ -17,8 +17,10 @@ describe('pathUtils', () => {
       'endi-lie-fd3': false,
       'yangshun-tay-48d': false,
       'yangshun-tay-f3b': false,
-      'foo-bar-foo-bar-foo-bar-foo-bar-foo-bar-foo-bar-foo-bar-foo-bar-foo-bar-foo-bar-foo-bar-foo-bar-foo-bar-foo-bar-foo-bar-foo-bar-foo-bar-foo-bar-foo-bar-foo-bar-foo-bar-foo-bar-foo-bar-foo-bar-foo-bar-foo-bar-foo-bar-foo-bar-foo-bar-foo-bar-foo-bar-foo-bar-d46': true,
-      'foo-bar-foo-bar-foo-bar-foo-bar-foo-bar-foo-bar-foo-bar-foo-bar-foo-bar-foo-bar-foo-bar-foo-bar-foo-bar-foo-bar-foo-bar-foo-bar-foo-bar-foo-bar-foo-bar-foo-bar-foo-bar-foo-bar-foo-bar-foo-bar-foo-bar-foo-bar-foo-bar-foo-bar-foo-bar-test-1-test-2-787': true,
+      'foo-bar-foo-bar-foo-bar-foo-bar-foo-bar-foo-bar-foo-bar-foo-bar-foo-bar-foo-bar-foo-bar-foo-bar-foo-bar-foo-bar-foo-bar-foo-bar-foo-bar-foo-bar-foo-bar-foo-bar-foo-bar-foo-bar-foo-bar-foo-bar-foo-bar-foo-bar-foo-bar-foo-bar-foo-bar-foo-bar-foo-bar-foo-bar-d46':
+        true,
+      'foo-bar-foo-bar-foo-bar-foo-bar-foo-bar-foo-bar-foo-bar-foo-bar-foo-bar-foo-bar-foo-bar-foo-bar-foo-bar-foo-bar-foo-bar-foo-bar-foo-bar-foo-bar-foo-bar-foo-bar-foo-bar-foo-bar-foo-bar-foo-bar-foo-bar-foo-bar-foo-bar-foo-bar-foo-bar-test-1-test-2-787':
+        true,
     };
     Object.keys(asserts).forEach((path) => {
       expect(isNameTooLong(path)).toBe(asserts[path]);

package/src/__tests__/slugger.test.ts

@@ -0,0 +1,27 @@
+/**
+ * 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 {createSlugger} from '../slugger';
+
+describe('createSlugger', () => {
+  test('can create unique slugs', () => {
+    const slugger = createSlugger();
+    expect(slugger.slug('Some$/vaLue$!^')).toEqual('somevalue');
+    expect(slugger.slug('Some$/vaLue$!^')).toEqual('somevalue-1');
+    expect(slugger.slug('Some$/vaLue$!^')).toEqual('somevalue-2');
+    expect(slugger.slug('Some$/vaLue$!^-1')).toEqual('somevalue-1-1');
+  });
+
+  test('can create unique slugs respecting case', () => {
+    const slugger = createSlugger();
+    const opt = {maintainCase: true};
+    expect(slugger.slug('Some$/vaLue$!^', opt)).toEqual('SomevaLue');
+    expect(slugger.slug('Some$/vaLue$!^', opt)).toEqual('SomevaLue-1');
+    expect(slugger.slug('Some$/vaLue$!^', opt)).toEqual('SomevaLue-2');
+    expect(slugger.slug('Some$/vaLue$!^-1', opt)).toEqual('SomevaLue-1-1');
+  });
+});

package/src/__tests__/tags.test.ts

@@ -0,0 +1,183 @@
+/**
+ * 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 {
+  normalizeFrontMatterTag,
+  normalizeFrontMatterTags,
+  groupTaggedItems,
+  Tag,
+} from '../tags';
+
+describe('normalizeFrontMatterTag', () => {
+  type Input = Parameters<typeof normalizeFrontMatterTag>[1];
+  type Output = ReturnType<typeof normalizeFrontMatterTag>;
+
+  test('should normalize simple string tag', () => {
+    const tagsPath = '/all/tags';
+    const input: Input = 'tag';
+    const expectedOutput: Output = {
+      label: 'tag',
+      permalink: `${tagsPath}/tag`,
+    };
+    expect(normalizeFrontMatterTag(tagsPath, input)).toEqual(expectedOutput);
+  });
+
+  test('should normalize complex string tag', () => {
+    const tagsPath = '/all/tags';
+    const input: Input = 'some more Complex_tag';
+    const expectedOutput: Output = {
+      label: 'some more Complex_tag',
+      permalink: `${tagsPath}/some-more-complex-tag`,
+    };
+    expect(normalizeFrontMatterTag(tagsPath, input)).toEqual(expectedOutput);
+  });
+
+  test('should normalize simple object tag', () => {
+    const tagsPath = '/all/tags';
+    const input: Input = {label: 'tag', permalink: 'tagPermalink'};
+    const expectedOutput: Output = {
+      label: 'tag',
+      permalink: `${tagsPath}/tagPermalink`,
+    };
+    expect(normalizeFrontMatterTag(tagsPath, input)).toEqual(expectedOutput);
+  });
+
+  test('should normalize complex string tag', () => {
+    const tagsPath = '/all/tags';
+    const input: Input = {
+      label: 'tag complex Label',
+      permalink: '/MoreComplex/Permalink',
+    };
+    const expectedOutput: Output = {
+      label: 'tag complex Label',
+      permalink: `${tagsPath}/MoreComplex/Permalink`,
+    };
+    expect(normalizeFrontMatterTag(tagsPath, input)).toEqual(expectedOutput);
+  });
+});
+
+describe('normalizeFrontMatterTags', () => {
+  type Input = Parameters<typeof normalizeFrontMatterTags>[1];
+  type Output = ReturnType<typeof normalizeFrontMatterTags>;
+
+  test('should normalize string list', () => {
+    const tagsPath = '/all/tags';
+    const input: Input = ['tag 1', 'tag-1', 'tag 3', 'tag1', 'tag-2'];
+    // Keep user input order but remove tags that lead to same permalink
+    const expectedOutput: Output = [
+      {
+        label: 'tag 1',
+        permalink: `${tagsPath}/tag-1`,
+      },
+      {
+        label: 'tag 3',
+        permalink: `${tagsPath}/tag-3`,
+      },
+      {
+        label: 'tag-2',
+        permalink: `${tagsPath}/tag-2`,
+      },
+    ];
+    expect(normalizeFrontMatterTags(tagsPath, input)).toEqual(expectedOutput);
+  });
+
+  test('should normalize complex mixed list', () => {
+    const tagsPath = '/all/tags';
+    const input: Input = [
+      'tag 1',
+      {label: 'tag-1', permalink: '/tag-1'},
+      'tag 3',
+      'tag1',
+      {label: 'tag 4', permalink: '/tag4Permalink'},
+    ];
+    // Keep user input order but remove tags that lead to same permalink
+    const expectedOutput: Output = [
+      {
+        label: 'tag 1',
+        permalink: `${tagsPath}/tag-1`,
+      },
+      {
+        label: 'tag 3',
+        permalink: `${tagsPath}/tag-3`,
+      },
+      {
+        label: 'tag 4',
+        permalink: `${tagsPath}/tag4Permalink`,
+      },
+    ];
+    expect(normalizeFrontMatterTags(tagsPath, input)).toEqual(expectedOutput);
+  });
+});
+
+describe('groupTaggedItems', () => {
+  type SomeTaggedItem = {
+    id: string;
+    nested: {
+      tags: Tag[];
+    };
+  };
+  function groupItems(items: SomeTaggedItem[]) {
+    return groupTaggedItems(items, (item) => item.nested.tags);
+  }
+
+  type Input = Parameters<typeof groupItems>[0];
+  type Output = ReturnType<typeof groupItems>;
+
+  test('should group items by tag permalink', () => {
+    const tagGuide = {label: 'Guide', permalink: '/guide'};
+    const tagTutorial = {label: 'Tutorial', permalink: '/tutorial'};
+    const tagAPI = {label: 'API', permalink: '/api'};
+
+    // This one will be grouped under same permalink and label is ignored
+    const tagTutorialOtherLabel = {
+      label: 'TutorialOtherLabel',
+      permalink: '/tutorial',
+    };
+
+    const item1: SomeTaggedItem = {
+      id: '1',
+      nested: {
+        tags: [
+          tagGuide,
+          tagTutorial,
+          tagAPI,
+          // Add some duplicates on purpose: they should be filtered
+          tagGuide,
+          tagTutorialOtherLabel,
+        ],
+      },
+    };
+    const item2: SomeTaggedItem = {
+      id: '2',
+      nested: {
+        tags: [tagAPI],
+      },
+    };
+    const item3: SomeTaggedItem = {
+      id: '3',
+      nested: {
+        tags: [tagTutorial],
+      },
+    };
+    const item4: SomeTaggedItem = {
+      id: '4',
+      nested: {
+        tags: [tagTutorialOtherLabel],
+      },
+    };
+
+    const input: Input = [item1, item2, item3, item4];
+
+    const expectedOutput: Output = {
+      '/guide': {tag: tagGuide, items: [item1]},
+      '/tutorial': {tag: tagTutorial, items: [item1, item3, item4]},
+      '/api': {tag: tagAPI, items: [item1, item2]},
+    };
+
+    expect(groupItems(input)).toEqual(expectedOutput);
+  });
+});

package/src/__tests__/webpackUtils.test.ts

@@ -0,0 +1,33 @@
+/**
+ * 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 {getFileLoaderUtils} from '../webpackUtils';
+
+describe('getFileLoaderUtils()', () => {
+  test('plugin svgo/removeViewBox should be disabled', () => {
+    const {oneOf} = getFileLoaderUtils().rules.svg();
+    expect(oneOf[0].use).toContainEqual(
+      expect.objectContaining({
+        loader: require.resolve('@svgr/webpack'),
+        options: expect.objectContaining({
+          svgoConfig: {
+            plugins: [
+              {
+                name: 'preset-default',
+                params: {
+                  overrides: {
+                    removeViewBox: false,
+                  },
+                },
+              },
+            ],
+          },
+        }),
+      }),
+    );
+  });
+});

package/src/constants.ts

@@ -0,0 +1,38 @@
+/**
+ * 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 const NODE_MAJOR_VERSION = parseInt(
+  process.versions.node.split('.')[0],
+  10,
+);
+export const NODE_MINOR_VERSION = parseInt(
+  process.versions.node.split('.')[1],
+  10,
+);
+
+// Can be overridden with cli option --out-dir
+export const DEFAULT_BUILD_DIR_NAME = 'build';
+
+// Can be overridden with cli option --config
+export const DEFAULT_CONFIG_FILE_NAME = 'docusaurus.config.js';
+
+export const BABEL_CONFIG_FILE_NAME =
+  process.env.DOCUSAURUS_BABEL_CONFIG_FILE_NAME || 'babel.config.js';
+
+export const GENERATED_FILES_DIR_NAME =
+  process.env.DOCUSAURUS_GENERATED_FILES_DIR_NAME || '.docusaurus';
+
+export const SRC_DIR_NAME = 'src';
+export const STATIC_DIR_NAME = 'static';
+export const OUTPUT_STATIC_ASSETS_DIR_NAME = 'assets'; // files handled by webpack, hashed (can be cached aggressively)
+export const THEME_PATH = `${SRC_DIR_NAME}/theme`;
+export const DEFAULT_PORT = 3000;
+export const DEFAULT_PLUGIN_ID = 'default';
+
+// Temporary fix for https://github.com/facebook/docusaurus/issues/5493
+export const WEBPACK_URL_LOADER_LIMIT =
+  process.env.WEBPACK_URL_LOADER_LIMIT ?? 10000;

package/src/deps.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 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.
+ */
+
+declare module 'resolve-pathname' {
+  export default function resolvePathname(to: string, from?: string): string;
+}
+
+declare module '@mdx-js/runtime';
+declare module 'remark-mdx-remove-imports';
+declare module 'remark-mdx-remove-exports';

package/src/globUtils.ts

@@ -0,0 +1,63 @@
+/**
+ * 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.
+ */
+
+// Globby/Micromatch are the 2 libs we use in Docusaurus consistently
+
+export {default as Globby} from 'globby';
+import Micromatch from 'micromatch'; // Note: Micromatch is used by Globby
+import path from 'path';
+
+// The default patterns we ignore when globbing
+// using _ prefix for exclusion by convention
+export const GlobExcludeDefault = [
+  // Ignore files starting with _
+  '**/_*.{js,jsx,ts,tsx,md,mdx}',
+
+  // Ignore folders starting with _ (including folder content)
+  '**/_*/**',
+
+  // Ignore tests
+  '**/*.test.{js,jsx,ts,tsx}',
+  '**/__tests__/**',
+];
+
+type Matcher = (str: string) => boolean;
+
+export function createMatcher(patterns: string[]): Matcher {
+  const regexp = new RegExp(
+    patterns.map((pattern) => Micromatch.makeRe(pattern).source).join('|'),
+  );
+  return (str) => regexp.test(str);
+}
+
+// We use match patterns like '**/_*/**',
+// This function permits to help to:
+// Match /user/sebastien/website/docs/_partials/xyz.md
+// Ignore /user/_sebastien/website/docs/partials/xyz.md
+export function createAbsoluteFilePathMatcher(
+  patterns: string[],
+  rootFolders: string[],
+): Matcher {
+  const matcher = createMatcher(patterns);
+
+  function getRelativeFilePath(absoluteFilePath: string) {
+    const rootFolder = rootFolders.find((folderPath) =>
+      absoluteFilePath.startsWith(folderPath),
+    );
+    if (!rootFolder) {
+      throw new Error(
+        `createAbsoluteFilePathMatcher unexpected error, absoluteFilePath=${absoluteFilePath} was not contained in any of the root folders ${JSON.stringify(
+          rootFolders,
+        )}`,
+      );
+    }
+    return path.relative(rootFolder, absoluteFilePath);
+  }
+
+  return (absoluteFilePath: string) =>
+    matcher(getRelativeFilePath(absoluteFilePath));
+}

package/src/index.ts

@@ -18,19 +18,32 @@ import {
   TranslationFile,
 } from '@docusaurus/types';
 
-// @ts-expect-error: no typedefs :s
 import resolvePathnameUnsafe from 'resolve-pathname';
 
 import {posixPath as posixPathImport} from './posixPath';
 import {simpleHash, docuHash} from './hashUtils';
+import {normalizeUrl} from './normalizeUrl';
+import {DEFAULT_PLUGIN_ID} from './constants';
+
+export * from './constants';
+export * from './mdxUtils';
+export * from './normalizeUrl';
+export * from './tags';
 
 export const posixPath = posixPathImport;
 
-export * from './codeTranslationsUtils';
 export * from './markdownParser';
 export * from './markdownLinks';
 export * from './escapePath';
+export * from './slugger';
 export {md5Hash, simpleHash, docuHash} from './hashUtils';
+export {
+  Globby,
+  GlobExcludeDefault,
+  createMatcher,
+  createAbsoluteFilePathMatcher,
+} from './globUtils';
+export * from './webpackUtils';
 
 const fileHash = new Map();
 export async function generate(
@@ -184,80 +197,6 @@ export function getSubFolder(file: string, refDir: string): string | null {
   return match && match[1];
 }
 
-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();
-    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;
-}
-
 /**
  * Alias filepath relative to site directory, very useful so that we
  * don't expose user's site structure.
@@ -323,7 +262,7 @@ export function removePrefix(str: string, prefix: string): string {
   return str.startsWith(prefix) ? str.slice(prefix.length) : str;
 }
 
-export function getElementsAround<T extends unknown>(
+export function getElementsAround<T>(
   array: T[],
   aroundIndex: number,
 ): {
@@ -346,7 +285,7 @@ export function getPluginI18nPath({
   siteDir,
   locale,
   pluginName,
-  pluginId = 'default', // TODO duplicated constant
+  pluginId = DEFAULT_PLUGIN_ID,
   subPaths = [],
 }: {
   siteDir: string;
@@ -362,22 +301,18 @@ export function getPluginI18nPath({
     locale,
     // Make it convenient to use for single-instance
     // ie: return "docs", not "docs-default" nor "docs/default"
-    `${pluginName}${
-      // TODO duplicate constant :(
-      pluginId === 'default' ? '' : `-${pluginId}`
-    }`,
+    `${pluginName}${pluginId === DEFAULT_PLUGIN_ID ? '' : `-${pluginId}`}`,
     ...subPaths,
   );
 }
 
-export async function mapAsyncSequencial<T extends unknown, R extends unknown>(
+export async function mapAsyncSequencial<T, R>(
   array: T[],
   action: (t: T) => Promise<R>,
 ): Promise<R[]> {
   const results: R[] = [];
   // eslint-disable-next-line no-restricted-syntax
   for (const t of array) {
-    // eslint-disable-next-line no-await-in-loop
     const result = await action(t);
     results.push(result);
   }
@@ -390,7 +325,6 @@ export async function findAsyncSequential<T>(
 ): Promise<T | undefined> {
   // eslint-disable-next-line no-restricted-syntax
   for (const t of array) {
-    // eslint-disable-next-line no-await-in-loop
     if (await predicate(t)) {
       return t;
     }
@@ -455,9 +389,7 @@ export function reportMessage(
 export function mergeTranslations(
   contents: TranslationFileContent[],
 ): TranslationFileContent {
-  return contents.reduce((acc, content) => {
-    return {...acc, ...content};
-  }, {});
+  return contents.reduce((acc, content) => ({...acc, ...content}), {});
 }
 
 export function getSwizzledComponent(
@@ -491,9 +423,7 @@ export function updateTranslationFileMessages(
 
 // Input: ## Some heading {#some-heading}
 // Output: {text: "## Some heading", id: "some-heading"}
-export function parseMarkdownHeadingId(
-  heading: string,
-): {
+export function parseMarkdownHeadingId(heading: string): {
   text: string;
   id?: string;
 } {