@docusaurus/core 0.0.0-5858 → 0.0.0-5861

package/lib/server/brokenLinks.js

@@ -12,7 +12,7 @@ const lodash_1 = tslib_1.__importDefault(require("lodash"));
 const logger_1 = tslib_1.__importDefault(require("@docusaurus/logger"));
 const react_router_config_1 = require("react-router-config");
 const utils_1 = require("@docusaurus/utils");
-const utils_2 = require("./utils");
+const routes_1 = require("./routes");
 function matchRoutes(routeConfig, pathname) {
     // @ts-expect-error: React router types RouteConfig with an actual React
     // component, but we load route components with string paths.
@@ -127,7 +127,7 @@ function getBrokenLinksForPage({ pagePath, helper, }) {
  */
 function filterIntermediateRoutes(routesInput) {
     const routesWithout404 = routesInput.filter((route) => route.path !== '*');
-    return (0, utils_2.getAllFinalRoutes)(routesWithout404);
+    return (0, routes_1.getAllFinalRoutes)(routesWithout404);
 }
 function getBrokenLinks({ collectedLinks, routes, }) {
     const filteredRoutes = filterIntermediateRoutes(routes);

package/lib/server/codegen/codegen.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 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 { CodeTranslations, DocusaurusConfig, GlobalData, I18n, RouteConfig, SiteMetadata } from '@docusaurus/types';
+type CodegenParams = {
+    generatedFilesDir: string;
+    siteConfig: DocusaurusConfig;
+    baseUrl: string;
+    clientModules: string[];
+    globalData: GlobalData;
+    i18n: I18n;
+    codeTranslations: CodeTranslations;
+    siteMetadata: SiteMetadata;
+    routes: RouteConfig[];
+};
+export declare function generateSiteFiles(params: CodegenParams): Promise<void>;
+export {};

package/lib/server/codegen/codegen.js

@@ -0,0 +1,65 @@
+"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.generateSiteFiles = void 0;
+const utils_1 = require("@docusaurus/utils");
+const codegenRoutes_1 = require("./codegenRoutes");
+function genWarning({ generatedFilesDir }) {
+    return (0, utils_1.generate)(generatedFilesDir, 
+    // cSpell:ignore DONT
+    'DONT-EDIT-THIS-FOLDER', `This folder stores temp files that Docusaurus' client bundler accesses.
+
+DO NOT hand-modify files in this folder because they will be overwritten in the
+next build. You can clear all build artifacts (including this folder) with the
+\`docusaurus clear\` command.
+`);
+}
+function genSiteConfig({ generatedFilesDir, siteConfig, }) {
+    return (0, utils_1.generate)(generatedFilesDir, `${utils_1.DEFAULT_CONFIG_FILE_NAME}.mjs`, `/*
+ * AUTOGENERATED - DON'T EDIT
+ * Your edits in this file will be overwritten in the next build!
+ * Modify the docusaurus.config.js file at your site's root instead.
+ */
+export default ${JSON.stringify(siteConfig, null, 2)};
+`);
+}
+function genClientModules({ generatedFilesDir, clientModules, }) {
+    return (0, utils_1.generate)(generatedFilesDir, 'client-modules.js', `export default [
+${clientModules
+        // Use `require()` because `import()` is async but client modules can have CSS
+        // and the order matters for loading CSS.
+        .map((clientModule) => `  require("${(0, utils_1.escapePath)(clientModule)}"),`)
+        .join('\n')}
+];
+`);
+}
+function genGlobalData({ generatedFilesDir, globalData, }) {
+    return (0, utils_1.generate)(generatedFilesDir, 'globalData.json', JSON.stringify(globalData, null, 2));
+}
+function genI18n({ generatedFilesDir, i18n, }) {
+    return (0, utils_1.generate)(generatedFilesDir, 'i18n.json', JSON.stringify(i18n, null, 2));
+}
+function genCodeTranslations({ generatedFilesDir, codeTranslations, }) {
+    return (0, utils_1.generate)(generatedFilesDir, 'codeTranslations.json', JSON.stringify(codeTranslations, null, 2));
+}
+function genSiteMetadata({ generatedFilesDir, siteMetadata, }) {
+    return (0, utils_1.generate)(generatedFilesDir, 'site-metadata.json', JSON.stringify(siteMetadata, null, 2));
+}
+async function generateSiteFiles(params) {
+    await Promise.all([
+        genWarning(params),
+        genClientModules(params),
+        genSiteConfig(params),
+        (0, codegenRoutes_1.generateRouteFiles)(params),
+        genGlobalData(params),
+        genSiteMetadata(params),
+        genI18n(params),
+        genCodeTranslations(params),
+    ]);
+}
+exports.generateSiteFiles = generateSiteFiles;

package/lib/server/codegen/codegenRoutes.d.ts

@@ -0,0 +1,49 @@
+/**
+ * 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 { RouteConfig, RouteChunkNames } from '@docusaurus/types';
+type RoutesCode = {
+    /** Serialized routes config that can be directly emitted into temp file. */
+    routesConfig: string;
+    /** @see {ChunkNames} */
+    routesChunkNames: RouteChunkNames;
+    /**
+     * A map from chunk name to module paths. Module paths would have backslash
+     * escaped already, so they can be directly printed.
+     */
+    registry: {
+        [chunkName: string]: string;
+    };
+};
+/**
+ * Generates a unique chunk name that can be used in the chunk registry.
+ *
+ * @param modulePath A path to generate chunk name from. The actual value has no
+ * semantic significance.
+ * @param prefix A prefix to append to the chunk name, to avoid name clash.
+ * @param preferredName Chunk names default to `modulePath`, and this can supply
+ * a more human-readable name.
+ * @param shortId When `true`, the chunk name would only be a hash without any
+ * other characters. Useful for bundle size. Defaults to `true` in production.
+ */
+export declare function genChunkName(modulePath: string, prefix?: string, preferredName?: string, shortId?: boolean): string;
+/**
+ * Routes are prepared into three temp files:
+ *
+ * - `routesConfig`, the route config passed to react-router. This file is kept
+ * minimal, because it can't be code-splitted.
+ * - `routesChunkNames`, a mapping from route paths (hashed) to code-splitted
+ * chunk names.
+ * - `registry`, a mapping from chunk names to options for react-loadable.
+ */
+export declare function generateRoutesCode(routeConfigs: RouteConfig[]): RoutesCode;
+type GenerateRouteFilesParams = {
+    generatedFilesDir: string;
+    routes: RouteConfig[];
+    baseUrl: string;
+};
+export declare function generateRouteFiles({ generatedFilesDir, routes, }: GenerateRouteFilesParams): Promise<void>;
+export {};

package/lib/server/codegen/codegenRoutes.js

@@ -0,0 +1,190 @@
+"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.generateRouteFiles = exports.generateRoutesCode = exports.genChunkName = void 0;
+const tslib_1 = require("tslib");
+const querystring_1 = tslib_1.__importDefault(require("querystring"));
+const lodash_1 = tslib_1.__importDefault(require("lodash"));
+const utils_1 = require("@docusaurus/utils");
+/** Indents every line of `str` by one level. */
+function indent(str) {
+    return `  ${str.replace(/\n/g, `\n  `)}`;
+}
+const chunkNameCache = new Map();
+const chunkNameCount = new Map();
+/**
+ * Generates a unique chunk name that can be used in the chunk registry.
+ *
+ * @param modulePath A path to generate chunk name from. The actual value has no
+ * semantic significance.
+ * @param prefix A prefix to append to the chunk name, to avoid name clash.
+ * @param preferredName Chunk names default to `modulePath`, and this can supply
+ * a more human-readable name.
+ * @param shortId When `true`, the chunk name would only be a hash without any
+ * other characters. Useful for bundle size. Defaults to `true` in production.
+ */
+function genChunkName(modulePath, prefix, preferredName, shortId = process.env.NODE_ENV === 'production') {
+    let chunkName = chunkNameCache.get(modulePath);
+    if (!chunkName) {
+        if (shortId) {
+            chunkName = (0, utils_1.simpleHash)(modulePath, 8);
+        }
+        else {
+            let str = modulePath;
+            if (preferredName) {
+                const shortHash = (0, utils_1.simpleHash)(modulePath, 3);
+                str = `${preferredName}${shortHash}`;
+            }
+            const name = (0, utils_1.docuHash)(str);
+            chunkName = prefix ? `${prefix}---${name}` : name;
+        }
+        const seenCount = (chunkNameCount.get(chunkName) ?? 0) + 1;
+        if (seenCount > 1) {
+            chunkName += seenCount.toString(36);
+        }
+        chunkNameCache.set(modulePath, chunkName);
+        chunkNameCount.set(chunkName, seenCount);
+    }
+    return chunkName;
+}
+exports.genChunkName = genChunkName;
+/**
+ * Takes a piece of route config, and serializes it into raw JS code. The shape
+ * is the same as react-router's `RouteConfig`. Formatting is similar to
+ * `JSON.stringify` but without all the quotes.
+ */
+function serializeRouteConfig({ routePath, routeHash, exact, subroutesCodeStrings, props, }) {
+    const parts = [
+        `path: '${routePath}'`,
+        `component: ComponentCreator('${routePath}', '${routeHash}')`,
+    ];
+    if (exact) {
+        parts.push(`exact: true`);
+    }
+    if (subroutesCodeStrings) {
+        parts.push(`routes: [
+${indent(subroutesCodeStrings.join(',\n'))}
+]`);
+    }
+    Object.entries(props).forEach(([propName, propValue]) => {
+        const isIdentifier = /^[$_\p{ID_Start}][$\u200c\u200d\p{ID_Continue}]*$/u.test(propName);
+        const key = isIdentifier ? propName : JSON.stringify(propName);
+        parts.push(`${key}: ${JSON.stringify(propValue)}`);
+    });
+    return `{
+${indent(parts.join(',\n'))}
+}`;
+}
+const isModule = (value) => typeof value === 'string' ||
+    (typeof value === 'object' &&
+        // eslint-disable-next-line no-underscore-dangle
+        !!value?.__import);
+/**
+ * Takes a {@link Module} (which is nothing more than a path plus some metadata
+ * like query) and returns the string path it represents.
+ */
+function getModulePath(target) {
+    if (typeof target === 'string') {
+        return target;
+    }
+    const queryStr = target.query ? `?${querystring_1.default.stringify(target.query)}` : '';
+    return `${target.path}${queryStr}`;
+}
+function genChunkNames(routeModule, prefix, name, res) {
+    if (isModule(routeModule)) {
+        // This is a leaf node, no need to recurse
+        const modulePath = getModulePath(routeModule);
+        const chunkName = genChunkName(modulePath, prefix, name);
+        res.registry[chunkName] = (0, utils_1.escapePath)(modulePath);
+        return chunkName;
+    }
+    if (Array.isArray(routeModule)) {
+        return routeModule.map((val, index) => genChunkNames(val, `${index}`, name, res));
+    }
+    return lodash_1.default.mapValues(routeModule, (v, key) => genChunkNames(v, key, name, res));
+}
+/**
+ * This is the higher level overview of route code generation. For each route
+ * config node, it returns the node's serialized form, and mutates `registry`,
+ * `routesPaths`, and `routesChunkNames` accordingly.
+ */
+function genRouteCode(routeConfig, res) {
+    const { path: routePath, component, modules = {}, context, routes: subroutes, priority, exact, ...props } = routeConfig;
+    if (typeof routePath !== 'string' || !component) {
+        throw new Error(`Invalid route config: path must be a string and component is required.
+${JSON.stringify(routeConfig)}`);
+    }
+    const routeHash = (0, utils_1.simpleHash)(JSON.stringify(routeConfig), 3);
+    res.routesChunkNames[`${routePath}-${routeHash}`] = {
+        // Avoid clash with a prop called "component"
+        ...genChunkNames({ __comp: component }, 'component', component, res),
+        ...(context &&
+            genChunkNames({ __context: context }, 'context', routePath, res)),
+        ...genChunkNames(modules, 'module', routePath, res),
+    };
+    return serializeRouteConfig({
+        routePath: routePath.replace(/'/g, "\\'"),
+        routeHash,
+        subroutesCodeStrings: subroutes?.map((r) => genRouteCode(r, res)),
+        exact,
+        props,
+    });
+}
+/**
+ * Routes are prepared into three temp files:
+ *
+ * - `routesConfig`, the route config passed to react-router. This file is kept
+ * minimal, because it can't be code-splitted.
+ * - `routesChunkNames`, a mapping from route paths (hashed) to code-splitted
+ * chunk names.
+ * - `registry`, a mapping from chunk names to options for react-loadable.
+ */
+function generateRoutesCode(routeConfigs) {
+    const res = {
+        // To be written by `genRouteCode`
+        routesConfig: '',
+        routesChunkNames: {},
+        registry: {},
+    };
+    // `genRouteCode` would mutate `res`
+    const routeConfigSerialized = routeConfigs
+        .map((r) => genRouteCode(r, res))
+        .join(',\n');
+    res.routesConfig = `import React from 'react';
+import ComponentCreator from '@docusaurus/ComponentCreator';
+
+export default [
+${indent(routeConfigSerialized)},
+  {
+    path: '*',
+    component: ComponentCreator('*'),
+  },
+];
+`;
+    return res;
+}
+exports.generateRoutesCode = generateRoutesCode;
+const genRegistry = ({ generatedFilesDir, registry, }) => (0, utils_1.generate)(generatedFilesDir, 'registry.js', `export default {
+${Object.entries(registry)
+    .sort((a, b) => a[0].localeCompare(b[0]))
+    .map(([chunkName, modulePath]) => 
+// modulePath is already escaped by escapePath
+`  "${chunkName}": [() => import(/* webpackChunkName: "${chunkName}" */ "${modulePath}"), "${modulePath}", require.resolveWeak("${modulePath}")],`)
+    .join('\n')}};
+`);
+const genRoutesChunkNames = ({ generatedFilesDir, routesChunkNames, }) => (0, utils_1.generate)(generatedFilesDir, 'routesChunkNames.json', JSON.stringify(routesChunkNames, null, 2));
+const genRoutes = ({ generatedFilesDir, routesConfig, }) => (0, utils_1.generate)(generatedFilesDir, 'routes.js', routesConfig);
+async function generateRouteFiles({ generatedFilesDir, routes, }) {
+    const { registry, routesChunkNames, routesConfig } = generateRoutesCode(routes);
+    await Promise.all([
+        genRegistry({ generatedFilesDir, registry }),
+        genRoutesChunkNames({ generatedFilesDir, routesChunkNames }),
+        genRoutes({ generatedFilesDir, routesConfig }),
+    ]);
+}
+exports.generateRouteFiles = generateRouteFiles;

package/lib/server/i18n.d.ts

@@ -5,6 +5,6 @@
  * LICENSE file in the root directory of this source tree.
  */
 import type { I18n, DocusaurusConfig, I18nLocaleConfig } from '@docusaurus/types';
-import type { LoadContextOptions } from './index';
+import type { LoadContextParams } from './site';
 export declare function getDefaultLocaleConfig(locale: string): I18nLocaleConfig;
-export declare function loadI18n(config: DocusaurusConfig, options: Pick<LoadContextOptions, 'locale'>): Promise<I18n>;
+export declare function loadI18n(config: DocusaurusConfig, options: Pick<LoadContextParams, 'locale'>): Promise<I18n>;

package/lib/server/plugins/actions.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 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 { LoadedPlugin, PluginContentLoadedActions, RouteConfig } from '@docusaurus/types';
+type PluginActionUtils = {
+    getRoutes: () => RouteConfig[];
+    getGlobalData: () => unknown;
+    getActions: () => PluginContentLoadedActions;
+};
+export declare function createPluginActionsUtils({ plugin, generatedFilesDir, baseUrl, trailingSlash, }: {
+    plugin: LoadedPlugin;
+    generatedFilesDir: string;
+    baseUrl: string;
+    trailingSlash: boolean | undefined;
+}): Promise<PluginActionUtils>;
+export {};

package/lib/server/plugins/actions.js

@@ -0,0 +1,61 @@
+"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.createPluginActionsUtils = void 0;
+const tslib_1 = require("tslib");
+const path_1 = tslib_1.__importDefault(require("path"));
+const utils_1 = require("@docusaurus/utils");
+const routeConfig_1 = require("./routeConfig");
+// TODO refactor historical action system and make this side-effect-free
+//  If the function were pure, we could more easily compare previous/next values
+//  on site reloads, and bail-out of the reload process earlier
+//  Particularly, createData() modules should rather be declarative
+async function createPluginActionsUtils({ plugin, generatedFilesDir, baseUrl, trailingSlash, }) {
+    const pluginId = plugin.options.id;
+    // Plugins data files are namespaced by pluginName/pluginId
+    const dataDir = path_1.default.join(generatedFilesDir, plugin.name, pluginId);
+    const pluginRouteContext = {
+        name: plugin.name,
+        id: pluginId,
+    };
+    const pluginRouteContextModulePath = path_1.default.join(dataDir, `${(0, utils_1.docuHash)('pluginRouteContextModule')}.json`);
+    await (0, utils_1.generate)('/', pluginRouteContextModulePath, JSON.stringify(pluginRouteContext, null, 2));
+    const routes = [];
+    let globalData;
+    const actions = {
+        addRoute(initialRouteConfig) {
+            // Trailing slash behavior is handled generically for all plugins
+            const finalRouteConfig = (0, routeConfig_1.applyRouteTrailingSlash)(initialRouteConfig, {
+                baseUrl,
+                trailingSlash,
+            });
+            routes.push({
+                ...finalRouteConfig,
+                context: {
+                    ...(finalRouteConfig.context && { data: finalRouteConfig.context }),
+                    plugin: pluginRouteContextModulePath,
+                },
+            });
+        },
+        async createData(name, data) {
+            const modulePath = path_1.default.join(dataDir, name);
+            await (0, utils_1.generate)(dataDir, name, data);
+            return modulePath;
+        },
+        setGlobalData(data) {
+            globalData = data;
+        },
+    };
+    return {
+        // Some variables are mutable, so we expose a getter instead of the value
+        getRoutes: () => routes,
+        getGlobalData: () => globalData,
+        getActions: () => actions,
+    };
+}
+exports.createPluginActionsUtils = createPluginActionsUtils;

package/lib/server/plugins/plugins.d.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 type { LoadContext, RouteConfig, GlobalData, LoadedPlugin } from '@docusaurus/types';
+import type { PluginIdentifier } from '@docusaurus/types/src/plugin';
+export type LoadPluginsResult = {
+    plugins: LoadedPlugin[];
+    routes: RouteConfig[];
+    globalData: GlobalData;
+};
+export declare function mergeGlobalData(...globalDataList: GlobalData[]): GlobalData;
+/**
+ * Initializes the plugins and run their lifecycle functions.
+ */
+export declare function loadPlugins(context: LoadContext): Promise<LoadPluginsResult>;
+export declare function getPluginByIdentifier({ plugins, pluginIdentifier, }: {
+    pluginIdentifier: PluginIdentifier;
+    plugins: LoadedPlugin[];
+}): LoadedPlugin;
+export declare function reloadPlugin({ pluginIdentifier, plugins: previousPlugins, context, }: {
+    pluginIdentifier: PluginIdentifier;
+    plugins: LoadedPlugin[];
+    context: LoadContext;
+}): Promise<LoadPluginsResult>;