@docusaurus/utils 2.0.0-beta.1 → 2.0.0-beta.10

package/src/webpackUtils.ts

@@ -0,0 +1,144 @@
+/**
+ * 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 type {RuleSetRule} from 'webpack';
+import path from 'path';
+import {posixPath} from './posixPath';
+import {
+  WEBPACK_URL_LOADER_LIMIT,
+  OUTPUT_STATIC_ASSETS_DIR_NAME,
+} from './constants';
+
+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;
+  };
+};
+
+// 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;
+
+  // defines the path/pattern of the assets handled by webpack
+  const fileLoaderFileName = (folder: AssetFolder) =>
+    `${OUTPUT_STATIC_ASSETS_DIR_NAME}/${folder}/[name]-[hash].[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 find a better solution to 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: `!${posixPath(
+      require.resolve('url-loader'),
+    )}?limit=${urlLoaderLimit}&name=${fileLoaderFileName(
+      'images',
+    )}&fallback=${posixPath(require.resolve('file-loader'))}!`,
+    inlineMarkdownLinkFileLoader: `!${posixPath(
+      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|jpg|jpeg|png|gif|webp)(\?.*)?$/,
+    }),
+
+    fonts: () => ({
+      use: [loaders.url({folder: 'fonts'})],
+      test: /\.(woff|woff2|eot|ttf|otf)$/,
+    }),
+
+    /**
+     * 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)$/,
+    }),
+
+    svg: () => ({
+      test: /\.svg?$/,
+      oneOf: [
+        {
+          use: [
+            {
+              loader: require.resolve('@svgr/webpack'),
+              options: {
+                prettier: false,
+                svgo: true,
+                svgoConfig: {
+                  plugins: [
+                    {
+                      name: 'preset-default',
+                      params: {
+                        overrides: {
+                          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: [/\.(ts|tsx|js|jsx|md|mdx)$/],
+          },
+        },
+        {
+          use: [loaders.url({folder: 'images'})],
+        },
+      ],
+    }),
+
+    otherAssets: () => ({
+      use: [loaders.file({folder: 'files'})],
+      test: /\.(pdf|doc|docx|xls|xlsx|zip|rar)$/,
+    }),
+  };
+
+  return {loaders, rules};
+}

package/lib/codeTranslationsUtils.d.ts

@@ -1,11 +0,0 @@
-/**
- * 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 codeTranslationLocalesToTry(locale: string): string[];
-export declare function readDefaultCodeTranslationMessages({ dirPath, locale, }: {
-    dirPath: string;
-    locale: string;
-}): Promise<Record<string, string>>;

package/lib/codeTranslationsUtils.js

@@ -1,50 +0,0 @@
-"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.readDefaultCodeTranslationMessages = exports.codeTranslationLocalesToTry = void 0;
-const tslib_1 = require("tslib");
-const path_1 = tslib_1.__importDefault(require("path"));
-const fs_extra_1 = tslib_1.__importDefault(require("fs-extra"));
-// Return an ordered list of locales we should try
-function codeTranslationLocalesToTry(locale) {
-    // @ts-expect-error: TODO until available in TS, see https://github.com/microsoft/TypeScript/issues/37326
-    const intlLocale = Intl.Locale ? new Intl.Locale(locale) : undefined;
-    if (!intlLocale) {
-        return [locale];
-    }
-    // if locale is just a simple language like "pt", we want to fallback to pt-BR (not pt-PT!)
-    // see https://github.com/facebook/docusaurus/pull/4536#issuecomment-810088783
-    if (intlLocale.language === locale) {
-        const maximizedLocale = intlLocale.maximize(); // pt-Latn-BR`
-        // ["pt","pt-BR"]
-        return [locale, `${maximizedLocale.language}-${maximizedLocale.region}`];
-    }
-    // if locale is like "pt-BR", we want to fallback to "pt"
-    else {
-        return [locale, intlLocale.language];
-    }
-}
-exports.codeTranslationLocalesToTry = codeTranslationLocalesToTry;
-// Useful to implement getDefaultCodeTranslationMessages() in themes
-async function readDefaultCodeTranslationMessages({ dirPath, locale, }) {
-    const localesToTry = codeTranslationLocalesToTry(locale);
-    // Return the content of the first file that match
-    // fr_FR.json => fr.json => nothing
-    // eslint-disable-next-line no-restricted-syntax
-    for (const fileName of localesToTry) {
-        const filePath = path_1.default.resolve(dirPath, `${fileName}.json`);
-        // eslint-disable-next-line no-await-in-loop
-        if (await fs_extra_1.default.pathExists(filePath)) {
-            // eslint-disable-next-line no-await-in-loop
-            const fileContent = await fs_extra_1.default.readFile(filePath, 'utf8');
-            return JSON.parse(fileContent);
-        }
-    }
-    return {};
-}
-exports.readDefaultCodeTranslationMessages = readDefaultCodeTranslationMessages;

package/lib/getFilePathForRoutePath.js

@@ -1,40 +0,0 @@
-"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.getFilePathForRoutePath = void 0;
-const tslib_1 = require("tslib");
-const path_1 = tslib_1.__importDefault(require("path"));
-/*
-export function getFilePathForRoutePath(routePath: string): string {
-  const fileName = path.basename(routePath);
-  const filePath = path.dirname(routePath);
-  return path.join(filePath, `${fileName}/index.html`);
-}
- */
-// Almost exact copy of the behavior we implemented in our Docusaurus fork of the webpack static gen plugin
-// See https://github.com/slorber/static-site-generator-webpack-plugin/blob/master/index.js#L167
-function getFilePathForRoutePath(routePath, trailingSlash) {
-    // const outputFileName = routePath.replace(/^(\/|\\)/, ''); // Remove leading slashes for webpack-dev-server
-    // Paths ending with .html are left untouched
-    if (/\.(html?)$/i.test(routePath)) {
-        return routePath;
-    }
-    // Legacy retro-compatible behavior
-    if (typeof trailingSlash === 'undefined') {
-        return path_1.default.join(routePath, 'index.html');
-    }
-    // New behavior: we can say if we prefer file/folder output
-    // Useful resource: https://github.com/slorber/trailing-slash-guide
-    if (routePath === '' || routePath.endsWith('/') || trailingSlash) {
-        return path_1.default.join(routePath, 'index.html');
-    }
-    else {
-        return `${routePath}.html`;
-    }
-}
-exports.getFilePathForRoutePath = getFilePathForRoutePath;

package/src/__tests__/__fixtures__/defaultCodeTranslations/en.json

@@ -1,4 +0,0 @@
-{
-  "id1": "message 1 en",
-  "id2": "message 2 en"
-}

package/src/__tests__/__fixtures__/defaultCodeTranslations/fr-FR.json

@@ -1,5 +0,0 @@
-{
-  "id1": "message 1 fr_FR",
-  "id2": "message 2 fr_FR",
-  "id3": "message 3 fr_FR"
-}

package/src/__tests__/__fixtures__/defaultCodeTranslations/fr.json

@@ -1,4 +0,0 @@
-{
-  "id1": "message 1 fr",
-  "id2": "message 2 fr"
-}

package/src/__tests__/codeTranslationsUtils.test.ts

@@ -1,112 +0,0 @@
-/**
- * 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 fs from 'fs-extra';
-import {
-  codeTranslationLocalesToTry,
-  readDefaultCodeTranslationMessages,
-} from '../codeTranslationsUtils';
-
-describe('codeTranslationLocalesToTry', () => {
-  test('should return appropriate locale lists', () => {
-    expect(codeTranslationLocalesToTry('fr')).toEqual(['fr', 'fr-FR']);
-    expect(codeTranslationLocalesToTry('fr-FR')).toEqual(['fr-FR', 'fr']);
-    // Note: "pt" is expanded into "pt-BR", not "pt-PT", as "pt-BR" is more widely used!
-    // See https://github.com/facebook/docusaurus/pull/4536#issuecomment-810088783
-    expect(codeTranslationLocalesToTry('pt')).toEqual(['pt', 'pt-BR']);
-    expect(codeTranslationLocalesToTry('pt-BR')).toEqual(['pt-BR', 'pt']);
-    expect(codeTranslationLocalesToTry('pt-PT')).toEqual(['pt-PT', 'pt']);
-  });
-});
-
-describe('readDefaultCodeTranslationMessages', () => {
-  const dirPath = path.resolve(
-    __dirname,
-    '__fixtures__',
-    'defaultCodeTranslations',
-  );
-
-  async function readAsJSON(filename: string) {
-    return JSON.parse(
-      await fs.readFile(path.resolve(dirPath, filename), 'utf8'),
-    );
-  }
-
-  test('for empty locale', async () => {
-    await expect(
-      readDefaultCodeTranslationMessages({
-        locale: '',
-        dirPath,
-      }),
-    ).rejects.toThrowErrorMatchingInlineSnapshot(
-      `"First argument to Intl.Locale constructor can't be empty or missing"`,
-    );
-  });
-
-  test('for unexisting locale', async () => {
-    await expect(
-      readDefaultCodeTranslationMessages({
-        locale: 'es',
-        dirPath,
-      }),
-    ).resolves.toEqual({});
-  });
-
-  test('for fr but bad folder', async () => {
-    await expect(
-      readDefaultCodeTranslationMessages({
-        locale: 'fr',
-        dirPath: __dirname,
-      }),
-    ).resolves.toEqual({});
-  });
-
-  test('for fr', async () => {
-    await expect(
-      readDefaultCodeTranslationMessages({
-        locale: 'fr',
-        dirPath,
-      }),
-    ).resolves.toEqual(await readAsJSON('fr.json'));
-  });
-
-  test('for fr-FR', async () => {
-    await expect(
-      readDefaultCodeTranslationMessages({
-        locale: 'fr-FR',
-        dirPath,
-      }),
-    ).resolves.toEqual(await readAsJSON('fr-FR.json'));
-  });
-
-  test('for en', async () => {
-    await expect(
-      readDefaultCodeTranslationMessages({
-        locale: 'en',
-        dirPath,
-      }),
-    ).resolves.toEqual(await readAsJSON('en.json'));
-  });
-
-  test('for en-US', async () => {
-    await expect(
-      readDefaultCodeTranslationMessages({
-        locale: 'en-US',
-        dirPath,
-      }),
-    ).resolves.toEqual(await readAsJSON('en.json'));
-  });
-
-  test('for en-WHATEVER', async () => {
-    await expect(
-      readDefaultCodeTranslationMessages({
-        locale: 'en-WHATEVER',
-        dirPath,
-      }),
-    ).resolves.toEqual(await readAsJSON('en.json'));
-  });
-});

package/src/__tests__/getFilePathForRoutePath.test.ts

@@ -1,87 +0,0 @@
-/**
- * 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 {getFilePathForRoutePath} from '../getFilePathForRoutePath';
-import {posixPath} from '../posixPath';
-
-describe('getFilePathForRoutePath trailingSlash=undefined', () => {
-  test('works for /', () => {
-    expect(posixPath(getFilePathForRoutePath('/', undefined))).toEqual(
-      '/index.html',
-    );
-  });
-
-  test('works for /somePath', () => {
-    expect(posixPath(getFilePathForRoutePath('/somePath', undefined))).toEqual(
-      '/somePath/index.html',
-    );
-  });
-
-  test('works for /somePath/', () => {
-    expect(posixPath(getFilePathForRoutePath('/somePath/', undefined))).toEqual(
-      '/somePath/index.html',
-    );
-  });
-
-  test('works for /somePath/xyz.html', () => {
-    expect(
-      posixPath(getFilePathForRoutePath('/somePath/xyz.html', undefined)),
-    ).toEqual('/somePath/xyz.html');
-  });
-});
-
-describe('getFilePathForRoutePath trailingSlash=true', () => {
-  test('works for /', () => {
-    expect(posixPath(getFilePathForRoutePath('/', true))).toEqual(
-      '/index.html',
-    );
-  });
-
-  test('works for /somePath', () => {
-    expect(posixPath(getFilePathForRoutePath('/somePath', true))).toEqual(
-      '/somePath/index.html',
-    );
-  });
-
-  test('works for /somePath/', () => {
-    expect(posixPath(getFilePathForRoutePath('/somePath/', true))).toEqual(
-      '/somePath/index.html',
-    );
-  });
-
-  test('works for /somePath/xyz.html', () => {
-    expect(
-      posixPath(getFilePathForRoutePath('/somePath/xyz.html', true)),
-    ).toEqual('/somePath/xyz.html');
-  });
-});
-
-describe('getFilePathForRoutePath trailingSlash=false', () => {
-  test('works for /', () => {
-    expect(posixPath(getFilePathForRoutePath('/', false))).toEqual(
-      '/index.html',
-    );
-  });
-
-  test('works for /somePath', () => {
-    expect(posixPath(getFilePathForRoutePath('/somePath', false))).toEqual(
-      '/somePath.html',
-    );
-  });
-
-  test('works for /somePath/', () => {
-    expect(posixPath(getFilePathForRoutePath('/somePath/', false))).toEqual(
-      '/somePath/index.html',
-    );
-  });
-
-  test('works for /somePath/xyz.html', () => {
-    expect(
-      posixPath(getFilePathForRoutePath('/somePath/xyz.html', false)),
-    ).toEqual('/somePath/xyz.html');
-  });
-});

package/src/codeTranslationsUtils.ts

@@ -1,56 +0,0 @@
-/**
- * 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 fs from 'fs-extra';
-
-// Return an ordered list of locales we should try
-export function codeTranslationLocalesToTry(locale: string): string[] {
-  // @ts-expect-error: TODO until available in TS, see https://github.com/microsoft/TypeScript/issues/37326
-  const intlLocale = Intl.Locale ? new Intl.Locale(locale) : undefined;
-  if (!intlLocale) {
-    return [locale];
-  }
-  // if locale is just a simple language like "pt", we want to fallback to pt-BR (not pt-PT!)
-  // see https://github.com/facebook/docusaurus/pull/4536#issuecomment-810088783
-  if (intlLocale.language === locale) {
-    const maximizedLocale = intlLocale.maximize(); // pt-Latn-BR`
-    // ["pt","pt-BR"]
-    return [locale, `${maximizedLocale.language}-${maximizedLocale.region}`];
-  }
-  // if locale is like "pt-BR", we want to fallback to "pt"
-  else {
-    return [locale, intlLocale.language];
-  }
-}
-
-// Useful to implement getDefaultCodeTranslationMessages() in themes
-export async function readDefaultCodeTranslationMessages({
-  dirPath,
-  locale,
-}: {
-  dirPath: string;
-  locale: string;
-}): Promise<Record<string, string>> {
-  const localesToTry = codeTranslationLocalesToTry(locale);
-
-  // Return the content of the first file that match
-  // fr_FR.json => fr.json => nothing
-  // eslint-disable-next-line no-restricted-syntax
-  for (const fileName of localesToTry) {
-    const filePath = path.resolve(dirPath, `${fileName}.json`);
-
-    // eslint-disable-next-line no-await-in-loop
-    if (await fs.pathExists(filePath)) {
-      // eslint-disable-next-line no-await-in-loop
-      const fileContent = await fs.readFile(filePath, 'utf8');
-      return JSON.parse(fileContent);
-    }
-  }
-
-  return {};
-}

package/src/getFilePathForRoutePath.ts

@@ -1,43 +0,0 @@
-/**
- * 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';
-
-/*
-export function getFilePathForRoutePath(routePath: string): string {
-  const fileName = path.basename(routePath);
-  const filePath = path.dirname(routePath);
-  return path.join(filePath, `${fileName}/index.html`);
-}
- */
-
-// Almost exact copy of the behavior we implemented in our Docusaurus fork of the webpack static gen plugin
-// See https://github.com/slorber/static-site-generator-webpack-plugin/blob/master/index.js#L167
-export function getFilePathForRoutePath(
-  routePath: string,
-  trailingSlash: boolean | undefined,
-): string {
-  // const outputFileName = routePath.replace(/^(\/|\\)/, ''); // Remove leading slashes for webpack-dev-server
-
-  // Paths ending with .html are left untouched
-  if (/\.(html?)$/i.test(routePath)) {
-    return routePath;
-  }
-
-  // Legacy retro-compatible behavior
-  if (typeof trailingSlash === 'undefined') {
-    return path.join(routePath, 'index.html');
-  }
-
-  // New behavior: we can say if we prefer file/folder output
-  // Useful resource: https://github.com/slorber/trailing-slash-guide
-  if (routePath === '' || routePath.endsWith('/') || trailingSlash) {
-    return path.join(routePath, 'index.html');
-  } else {
-    return `${routePath}.html`;
-  }
-}