@docusaurus/core 4.0.0-canary-6975 → 4.0.0-canary-6977

package/lib/server/configValidation.js

@@ -199,6 +199,44 @@ const VCS_CONFIG_SCHEMA = utils_validation_1.Joi.custom((input) => {
     }
     return value;
 }).default(() => exports.DEFAULT_CONFIG.vcs);
+// TODO Docusaurus v5: remove this migration error for legacy template variables
+const LegacySSGTemplateVariables = {
+    appHtml: logger_1.default.code('it.body.appHtml'),
+    htmlAttributes: logger_1.default.code('it.html.attributes'),
+    bodyAttributes: logger_1.default.code('it.body.attributes'),
+    metaAttributes: `${logger_1.default.code('it.head.pageTags')} (a string)`,
+    headTags: logger_1.default.code('it.head.pluginTags'),
+    preBodyTags: logger_1.default.code('it.body.preTags'),
+    postBodyTags: logger_1.default.code('it.body.postTags'),
+    stylesheets: `${logger_1.default.code('it.assets.stylesheets')} (URLs including the baseUrl)`,
+    scripts: `${logger_1.default.code('it.assets.scripts')} (URLs including the baseUrl)`,
+    noIndex: `removed: the ${logger_1.default.code('<meta name="robots">')} tag is part of ${logger_1.default.code('it.head.pageTags')}`,
+};
+function getLegacySSGTemplateVariablesMessage(template) {
+    const usedLegacyVariables = Object.keys(LegacySSGTemplateVariables).filter((name) => new RegExp(String.raw `\bit\.${name}\b`).test(template));
+    if (usedLegacyVariables.length === 0) {
+        return undefined;
+    }
+    return usedLegacyVariables
+        .map((name) => `- ${logger_1.default.code(`it.${name}`)} => ${LegacySSGTemplateVariables[name]}`)
+        .join('\n');
+}
+const SSG_TEMPLATE_SCHEMA = utils_validation_1.Joi.string()
+    // TODO Docusaurus v5: remove this migration error
+    .custom((template, helpers) => {
+    const legacyVariablesMessage = getLegacySSGTemplateVariablesMessage(template);
+    if (legacyVariablesMessage) {
+        return helpers.error('docusaurus.legacyVariables', {
+            legacyVariablesMessage,
+        });
+    }
+    return template;
+})
+    .messages({
+    'docusaurus.legacyVariables': `The Docusaurus config ${logger_1.default.code('siteConfig.ssgTemplate')} uses template variables that have been renamed or removed:
+{#legacyVariablesMessage}
+Please update your template.`,
+});
 // TODO Docusaurus v5: remove these never types for removed/renamed options
 const FUTURE_CONFIG_SCHEMA = utils_validation_1.Joi.object({
     // TODO Docusaurus v5: remove this migration error
@@ -278,7 +316,7 @@ exports.ConfigSchema = utils_validation_1.Joi.object({
         'array.includes': '{#label} is invalid. A script must be a plain string (the src), or an object with at least a "src" property.',
     })
         .default(exports.DEFAULT_CONFIG.scripts),
-    ssgTemplate: utils_validation_1.Joi.string(),
+    ssgTemplate: SSG_TEMPLATE_SCHEMA,
     // TODO Docusaurus v5: remove this migration error
     ssrTemplate: utils_validation_1.Joi.any()
         .forbidden()

package/lib/ssg/ssgParams.d.ts

@@ -14,7 +14,6 @@ export type SSGParams = {
     postBodyTags: string;
     outDir: string;
     baseUrl: string;
-    noIndex: boolean;
     DOCUSAURUS_VERSION: string;
     serverBundlePath: string;
     ssgTemplateContent: string;

package/lib/ssg/ssgParams.js

@@ -23,7 +23,6 @@ async function createSSGParams({ props, serverBundlePath, clientManifestPath, })
         preBodyTags: props.preBodyTags,
         postBodyTags: props.postBodyTags,
         ssgTemplateContent: props.siteConfig.ssgTemplate ?? ssgTemplate_html_1.default,
-        noIndex: props.siteConfig.noIndex,
         DOCUSAURUS_VERSION: utils_1.DOCUSAURUS_VERSION,
         serverBundlePath,
     };

package/lib/ssg/ssgTemplate.d.ts

@@ -6,19 +6,42 @@
  */
 import type { SSGParams } from './ssgParams';
 import type { AppRenderResult } from '../common';
+/**
+ * The data that the `siteConfig.ssgTemplate` receives as the `it` variable.
+ * Changing it is a breaking change because the template is configurable.
+ * Attributes and tags are pre-rendered HTML strings.
+ */
 type SSGTemplateData = {
-    appHtml: string;
-    baseUrl: string;
-    htmlAttributes: string;
-    bodyAttributes: string;
-    headTags: string;
-    preBodyTags: string;
-    postBodyTags: string;
-    metaAttributes: string[];
-    scripts: string[];
-    stylesheets: string[];
-    noIndex: boolean;
+    /** The Docusaurus version */
     version: string;
+    /** The site base URL, or `./` with the hash router */
+    baseUrl: string;
+    html: {
+        /** The `<html>` attributes, set by the page with `<Head>` */
+        attributes: string;
+    };
+    head: {
+        /** The `<head>` tags set by the page with `<Head>` */
+        pageTags: string;
+        /** The `headTags` of the plugins `injectHtmlTags()` lifecycle */
+        pluginTags: string;
+    };
+    body: {
+        /** The `<body>` attributes, set by the page with `<Head>` */
+        attributes: string;
+        /** The `preBodyTags` of the plugins `injectHtmlTags()` lifecycle */
+        preTags: string;
+        /** The server-side rendered React app */
+        appHtml: string;
+        /** The `postBodyTags` of the plugins `injectHtmlTags()` lifecycle */
+        postTags: string;
+    };
+    assets: {
+        /** The URLs of the CSS files the page needs */
+        stylesheets: string[];
+        /** The URLs of the JS files the page needs */
+        scripts: string[];
+    };
 };
 export type SSGTemplateCompiled = (data: SSGTemplateData) => string;
 export declare function compileSSGTemplate(template: string): Promise<SSGTemplateCompiled>;

package/lib/ssg/ssgTemplate.html.d.ts

@@ -4,5 +4,5 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-declare const _default = "\n<!DOCTYPE html>\n<html <%~ it.htmlAttributes %>>\n  <head>\n    <meta charset=\"UTF-8\">\n    <meta name=\"generator\" content=\"Docusaurus v<%= it.version %>\">\n    <% it.metaAttributes.forEach((metaAttribute) => { %>\n      <%~ metaAttribute %>\n    <% }); %>\n    <%~ it.headTags %>\n    <% it.stylesheets.forEach((stylesheet) => { %>\n      <link rel=\"stylesheet\" href=\"<%= it.baseUrl %><%= stylesheet %>\" />\n    <% }); %>\n    <% it.scripts.forEach((script) => { %>\n      <script src=\"<%= it.baseUrl %><%= script %>\" defer></script>\n    <% }); %>\n  </head>\n  <body <%~ it.bodyAttributes %>>\n    <%~ it.preBodyTags %>\n    <div id=\"__docusaurus\"><%~ it.appHtml %></div>\n    <%~ it.postBodyTags %>\n  </body>\n</html>\n";
+declare const _default = "\n<!DOCTYPE html>\n<html <%~ it.html.attributes %>>\n  <head>\n    <meta charset=\"UTF-8\">\n    <meta name=\"generator\" content=\"Docusaurus v<%= it.version %>\">\n    <%~ it.head.pageTags %>\n    <%~ it.head.pluginTags %>\n    <% it.assets.stylesheets.forEach((stylesheet) => { %>\n      <link rel=\"stylesheet\" href=\"<%= stylesheet %>\" />\n    <% }); %>\n    <% it.assets.scripts.forEach((script) => { %>\n      <script src=\"<%= script %>\" defer></script>\n    <% }); %>\n  </head>\n  <body <%~ it.body.attributes %>>\n    <%~ it.body.preTags %>\n    <div id=\"__docusaurus\"><%~ it.body.appHtml %></div>\n    <%~ it.body.postTags %>\n  </body>\n</html>\n";
 export default _default;

package/lib/ssg/ssgTemplate.html.js

@@ -8,25 +8,23 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.default = `
 <!DOCTYPE html>
-<html <%~ it.htmlAttributes %>>
+<html <%~ it.html.attributes %>>
   <head>
     <meta charset="UTF-8">
     <meta name="generator" content="Docusaurus v<%= it.version %>">
-    <% it.metaAttributes.forEach((metaAttribute) => { %>
-      <%~ metaAttribute %>
+    <%~ it.head.pageTags %>
+    <%~ it.head.pluginTags %>
+    <% it.assets.stylesheets.forEach((stylesheet) => { %>
+      <link rel="stylesheet" href="<%= stylesheet %>" />
     <% }); %>
-    <%~ it.headTags %>
-    <% it.stylesheets.forEach((stylesheet) => { %>
-      <link rel="stylesheet" href="<%= it.baseUrl %><%= stylesheet %>" />
-    <% }); %>
-    <% it.scripts.forEach((script) => { %>
-      <script src="<%= it.baseUrl %><%= script %>" defer></script>
+    <% it.assets.scripts.forEach((script) => { %>
+      <script src="<%= script %>" defer></script>
     <% }); %>
   </head>
-  <body <%~ it.bodyAttributes %>>
-    <%~ it.preBodyTags %>
-    <div id="__docusaurus"><%~ it.appHtml %></div>
-    <%~ it.postBodyTags %>
+  <body <%~ it.body.attributes %>>
+    <%~ it.body.preTags %>
+    <div id="__docusaurus"><%~ it.body.appHtml %></div>
+    <%~ it.body.postTags %>
   </body>
 </html>
 `;

package/lib/ssg/ssgTemplate.js

@@ -18,69 +18,57 @@ async function compileSSGTemplate(template) {
     return (data) => eta.render(compiledTemplate, data);
 }
 /**
- * Given a list of modules that were SSR an d
- * @param modules
- * @param manifest
+ * Returns the URLs of the JS/CSS assets required to render a page, based on
+ * the modules that were server-side rendered and the client manifest.
  */
-function getScriptsAndStylesheets({ modules, manifest, }) {
-    // Get all required assets for this particular page
-    // based on client manifest information.
-    const modulesToBeLoaded = [...manifest.entrypoints, ...Array.from(modules)];
+function getAssets({ baseUrl, modules, manifest, }) {
+    const modulesToBeLoaded = [...manifest.entrypoints, ...modules];
     const bundles = (0, react_loadable_ssr_addon_v5_slorber_1.getBundles)(manifest, modulesToBeLoaded);
-    const stylesheets = (bundles.css ?? []).map((b) => b.file);
-    const scripts = (bundles.js ?? []).map((b) => b.file);
-    return { scripts, stylesheets };
+    const toUrl = (bundle) => `${baseUrl}${bundle.file}`;
+    return {
+        stylesheets: (bundles.css ?? []).map(toUrl),
+        scripts: (bundles.js ?? []).map(toUrl),
+    };
 }
 function renderSSGTemplate({ params, result, ssgTemplate, }) {
-    const { baseUrl, headTags, preBodyTags, postBodyTags, manifest, noIndex, DOCUSAURUS_VERSION, } = params;
+    const { baseUrl, headTags, preBodyTags, postBodyTags, manifest, DOCUSAURUS_VERSION, } = params;
     const { html: appHtml, collectedData: { modules, metadata }, } = result;
-    const { scripts, stylesheets } = getScriptsAndStylesheets({ manifest, modules });
-    const { htmlAttributes, bodyAttributes } = metadata.internal;
-    const metaStrings = [
-        metadata.internal.title,
-        metadata.internal.meta,
-        metadata.internal.link,
-        metadata.internal.script,
-    ];
-    const metaAttributes = metaStrings.filter(Boolean);
+    const { htmlAttributes, bodyAttributes, title, meta, link, script } = metadata.internal;
     const data = {
-        appHtml,
-        baseUrl,
-        htmlAttributes,
-        bodyAttributes,
-        headTags,
-        preBodyTags,
-        postBodyTags,
-        metaAttributes,
-        scripts,
-        stylesheets,
-        noIndex,
         version: DOCUSAURUS_VERSION,
+        baseUrl,
+        html: { attributes: htmlAttributes },
+        head: {
+            pageTags: [title, meta, link, script].join(''),
+            pluginTags: headTags,
+        },
+        body: {
+            attributes: bodyAttributes,
+            preTags: preBodyTags,
+            appHtml,
+            postTags: postBodyTags,
+        },
+        assets: getAssets({ baseUrl, manifest, modules }),
     };
     return ssgTemplate(data);
 }
 async function renderHashRouterTemplate({ params, }) {
-    const { 
-    // baseUrl,
-    headTags, preBodyTags, postBodyTags, manifest, DOCUSAURUS_VERSION, ssgTemplateContent, } = params;
+    const { headTags, preBodyTags, postBodyTags, manifest, DOCUSAURUS_VERSION, ssgTemplateContent, } = params;
     const ssgTemplate = await logger_1.PerfLogger.async('Compile SSG template', () => compileSSGTemplate(ssgTemplateContent));
-    const { scripts, stylesheets } = getScriptsAndStylesheets({
-        manifest,
-        modules: [],
-    });
+    // The hash router site can be opened from the file system: use relative URLs
+    const baseUrl = './';
     const data = {
-        appHtml: '',
-        baseUrl: './',
-        htmlAttributes: '',
-        bodyAttributes: '',
-        headTags,
-        preBodyTags,
-        postBodyTags,
-        metaAttributes: [],
-        scripts,
-        stylesheets,
-        noIndex: false,
         version: DOCUSAURUS_VERSION,
+        baseUrl,
+        html: { attributes: '' },
+        head: { pageTags: '', pluginTags: headTags },
+        body: {
+            attributes: '',
+            preTags: preBodyTags,
+            appHtml: '',
+            postTags: postBodyTags,
+        },
+        assets: getAssets({ baseUrl, manifest, modules: [] }),
     };
     return ssgTemplate(data);
 }

package/lib/webpack/base.js

@@ -70,9 +70,12 @@ async function createBaseConfig({ props, isServer, minify, configureWebpackUtils
         // Because Webpack does not evict the cache on alias/swizzle changes,
         // See https://github.com/webpack/webpack/issues/13627
         const themeAliasesHash = (0, utils_1.md5Hash)(JSON.stringify(themeAliases));
+        // Loader and minimizer options are not part of the cache key
+        // Changing the Browserslist config must evict the cache
+        const browserslistHash = (0, utils_1.md5Hash)(JSON.stringify((0, bundler_1.getBrowserslistQueries)()));
         // Asset module parser options are not part of the cache key
         // Changing the asset inline max size must evict the cache
-        return `${siteMetadata.docusaurusVersion}-${themeAliasesHash}-${utils_1.ASSET_INLINE_MAX_SIZE}`;
+        return `${siteMetadata.docusaurusVersion}-${themeAliasesHash}-${browserslistHash}-${utils_1.ASSET_INLINE_MAX_SIZE}`;
     }
     // When one of those modules/dependencies change (including transitive
     // deps), cache is invalidated

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@docusaurus/core",
   "description": "Easy to Maintain Open Source Documentation Websites",
-  "version": "4.0.0-canary-6975",
+  "version": "4.0.0-canary-6977",
   "license": "MIT",
   "publishConfig": {
     "access": "public"
@@ -27,15 +27,15 @@
     "url": "https://github.com/facebook/docusaurus/issues"
   },
   "dependencies": {
-    "@docusaurus/babel": "4.0.0-canary-6975",
-    "@docusaurus/bundler": "4.0.0-canary-6975",
-    "@docusaurus/fs": "4.0.0-canary-6975",
-    "@docusaurus/glob": "4.0.0-canary-6975",
-    "@docusaurus/logger": "4.0.0-canary-6975",
-    "@docusaurus/mdx-loader": "4.0.0-canary-6975",
-    "@docusaurus/utils": "4.0.0-canary-6975",
-    "@docusaurus/utils-common": "4.0.0-canary-6975",
-    "@docusaurus/utils-validation": "4.0.0-canary-6975",
+    "@docusaurus/babel": "4.0.0-canary-6977",
+    "@docusaurus/bundler": "4.0.0-canary-6977",
+    "@docusaurus/fs": "4.0.0-canary-6977",
+    "@docusaurus/glob": "4.0.0-canary-6977",
+    "@docusaurus/logger": "4.0.0-canary-6977",
+    "@docusaurus/mdx-loader": "4.0.0-canary-6977",
+    "@docusaurus/utils": "4.0.0-canary-6977",
+    "@docusaurus/utils-common": "4.0.0-canary-6977",
+    "@docusaurus/utils-validation": "4.0.0-canary-6977",
     "@rspack/core": "^2.2.3",
     "@rspack/dev-server": "^2.2.1",
     "boxen": "^9.0.0",
@@ -68,8 +68,8 @@
     "webpack-merge": "^6.0.1"
   },
   "devDependencies": {
-    "@docusaurus/module-type-aliases": "4.0.0-canary-6975",
-    "@docusaurus/types": "4.0.0-canary-6975",
+    "@docusaurus/module-type-aliases": "4.0.0-canary-6977",
+    "@docusaurus/types": "4.0.0-canary-6977",
     "@total-typescript/shoehorn": "^0.1.2",
     "@types/escape-html": "^1.0.4",
     "@types/history": "^4.7.11",