@docusaurus/theme-classic 0.0.0-4432 → 0.0.0-4436

package/lib/index.js

@@ -101,8 +101,7 @@ function getInfimaCSSFile(direction) {
   return `infima/dist/css/default/default${direction === 'rtl' ? '-rtl' : ''}.css`;
 }
 
-function docusaurusThemeClassic(context, // TODO: LoadContext is missing some of properties
-options) {
+function docusaurusThemeClassic(context, options) {
   const {
     siteConfig: {
       themeConfig: roughlyTypedThemeConfig
@@ -178,7 +177,10 @@ options) {
     configureWebpack() {
       const prismLanguages = additionalLanguages.map(lang => `prism-${lang}`).join('|');
       return {
-        plugins: [new ContextReplacementPlugin(/prismjs[\\/]components$/, new RegExp(`^./(${prismLanguages})$`))]
+        plugins: [// This allows better optimization by only bundling those components
+        // that the user actually needs, because the modules are dynamically
+        // required and can't be known during compile time.
+        new ContextReplacementPlugin(/prismjs[\\/]components$/, new RegExp(`^./(${prismLanguages})$`))]
       };
     },
 

package/lib-next/theme/CodeBlock/index.js

@@ -37,9 +37,9 @@ export default function CodeBlock({
 
   useEffect(() => {
     setMounted(true);
-  }, []); // TODO: the title is provided by MDX as props automatically
-  // so we probably don't need to parse the metastring
-  // (note: title="xyz" => title prop still has the quotes)
+  }, []); // We still parse the metastring in case we want to support more syntax in the
+  // future. Note that MDX doesn't strip quotes when parsing metastring:
+  // "title=\"xyz\"" => title: "\"xyz\""
 
   const codeBlockTitle = parseCodeBlockTitle(metastring) || title;
   const prismTheme = usePrismTheme(); // <pre> tags in markdown map to CodeBlocks and they may contain JSX children.

package/lib-next/theme/prism-include-languages.js

@@ -10,12 +10,19 @@ import siteConfig from '@generated/docusaurus.config';
 const prismIncludeLanguages = (PrismObject) => {
   if (ExecutionEnvironment.canUseDOM) {
     const {
-      themeConfig: {prism = {}},
+      themeConfig: {prism},
     } = siteConfig;
-    const {additionalLanguages = []} = prism;
+    const {additionalLanguages} = prism; // Prism components work on the Prism instance on the window, while
+    // prism-react-renderer uses its own Prism instance. We temporarily mount
+    // the instance onto window, import components to enhance it, then remove it
+    // to avoid polluting global namespace.
+    // You can mutate this object: registering plugins, deleting languages... As
+    // long as you don't re-assign it
+
     window.Prism = PrismObject;
     additionalLanguages.forEach((lang) => {
-      require(`prismjs/components/prism-${lang}`); // eslint-disable-line
+      // eslint-disable-next-line global-require, import/no-dynamic-require
+      require(`prismjs/components/prism-${lang}`);
     });
     delete window.Prism;
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/theme-classic",
-  "version": "0.0.0-4432",
+  "version": "0.0.0-4436",
   "description": "Classic theme for Docusaurus",
   "main": "lib/index.js",
   "types": "src/theme-classic.d.ts",
@@ -23,14 +23,14 @@
     "update-code-translations": "node -e 'require(\"./update-code-translations.js\").run()'"
   },
   "dependencies": {
-    "@docusaurus/core": "0.0.0-4432",
-    "@docusaurus/plugin-content-blog": "0.0.0-4432",
-    "@docusaurus/plugin-content-docs": "0.0.0-4432",
-    "@docusaurus/plugin-content-pages": "0.0.0-4432",
-    "@docusaurus/theme-common": "0.0.0-4432",
-    "@docusaurus/theme-translations": "0.0.0-4432",
-    "@docusaurus/utils": "0.0.0-4432",
-    "@docusaurus/utils-validation": "0.0.0-4432",
+    "@docusaurus/core": "0.0.0-4436",
+    "@docusaurus/plugin-content-blog": "0.0.0-4436",
+    "@docusaurus/plugin-content-docs": "0.0.0-4436",
+    "@docusaurus/plugin-content-pages": "0.0.0-4436",
+    "@docusaurus/theme-common": "0.0.0-4436",
+    "@docusaurus/theme-translations": "0.0.0-4436",
+    "@docusaurus/utils": "0.0.0-4436",
+    "@docusaurus/utils-validation": "0.0.0-4436",
     "@mdx-js/mdx": "^1.6.21",
     "@mdx-js/react": "^1.6.21",
     "clsx": "^1.1.1",
@@ -45,8 +45,8 @@
     "rtlcss": "^3.3.0"
   },
   "devDependencies": {
-    "@docusaurus/module-type-aliases": "0.0.0-4432",
-    "@docusaurus/types": "0.0.0-4432",
+    "@docusaurus/module-type-aliases": "0.0.0-4436",
+    "@docusaurus/types": "0.0.0-4436",
     "@types/mdx-js__react": "^1.5.4",
     "@types/parse-numeric-range": "^0.0.1",
     "@types/rtlcss": "^3.1.1",
@@ -61,5 +61,5 @@
   "engines": {
     "node": ">=14"
   },
-  "gitHead": "1221cc7c66b95d2207c935645d303be70642514b"
+  "gitHead": "3b2e15935a716c69bd530fe10942e1620b36ddc4"
 }

package/src/index.ts

@@ -5,11 +5,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import type {
-  DocusaurusContext,
-  Plugin,
-  PostCssOptions,
-} from '@docusaurus/types';
+import type {LoadContext, Plugin, PostCssOptions} from '@docusaurus/types';
 import type {ThemeConfig} from '@docusaurus/theme-common';
 import {getTranslationFiles, translateThemeConfig} from './translations';
 import path from 'path';
@@ -18,13 +14,13 @@ import type {Plugin as PostCssPlugin} from 'postcss';
 import rtlcss from 'rtlcss';
 import {readDefaultCodeTranslationMessages} from '@docusaurus/theme-translations';
 import type {Options} from '@docusaurus/theme-classic';
+import type webpack from 'webpack';
 
 const requireFromDocusaurusCore = createRequire(
   require.resolve('@docusaurus/core/package.json'),
 );
-const ContextReplacementPlugin = requireFromDocusaurusCore(
-  'webpack/lib/ContextReplacementPlugin',
-);
+const ContextReplacementPlugin: typeof webpack.ContextReplacementPlugin =
+  requireFromDocusaurusCore('webpack/lib/ContextReplacementPlugin');
 
 // Need to be inlined to prevent dark mode FOUC
 // Make sure that the 'storageKey' is the same as the one in `/theme/hooks/useTheme.js`
@@ -95,7 +91,7 @@ function getInfimaCSSFile(direction: string) {
 }
 
 export default function docusaurusThemeClassic(
-  context: DocusaurusContext, // TODO: LoadContext is missing some of properties
+  context: LoadContext,
   options: Options,
 ): Plugin<void> {
   const {
@@ -172,6 +168,9 @@ export default function docusaurusThemeClassic(
 
       return {
         plugins: [
+          // This allows better optimization by only bundling those components
+          // that the user actually needs, because the modules are dynamically
+          // required and can't be known during compile time.
           new ContextReplacementPlugin(
             /prismjs[\\/]components$/,
             new RegExp(`^./(${prismLanguages})$`),

package/src/theme/CodeBlock/index.tsx

@@ -44,9 +44,9 @@ export default function CodeBlock({
     setMounted(true);
   }, []);
 
-  // TODO: the title is provided by MDX as props automatically
-  // so we probably don't need to parse the metastring
-  // (note: title="xyz" => title prop still has the quotes)
+  // We still parse the metastring in case we want to support more syntax in the
+  // future. Note that MDX doesn't strip quotes when parsing metastring:
+  // "title=\"xyz\"" => title: "\"xyz\""
   const codeBlockTitle = parseCodeBlockTitle(metastring) || title;
   const prismTheme = usePrismTheme();
 

package/src/theme/NavbarItem/index.tsx

@@ -16,7 +16,7 @@ import type {Types, Props} from '@theme/NavbarItem';
 
 const NavbarItemComponents: Record<
   Exclude<Types, undefined>,
-  // TODO: properly type this
+  // Not really worth typing, as we pass all props down immediately
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   () => (props: any) => JSX.Element
 > = {

package/src/theme/prism-include-languages.ts

@@ -12,14 +12,21 @@ import type * as PrismNamespace from 'prismjs';
 const prismIncludeLanguages = (PrismObject: typeof PrismNamespace): void => {
   if (ExecutionEnvironment.canUseDOM) {
     const {
-      themeConfig: {prism = {}},
+      themeConfig: {prism},
     } = siteConfig;
-    const {additionalLanguages = []} = prism as {additionalLanguages: string[]};
+    const {additionalLanguages} = prism as {additionalLanguages: string[]};
 
+    // Prism components work on the Prism instance on the window, while
+    // prism-react-renderer uses its own Prism instance. We temporarily mount
+    // the instance onto window, import components to enhance it, then remove it
+    // to avoid polluting global namespace.
+    // You can mutate this object: registering plugins, deleting languages... As
+    // long as you don't re-assign it
     window.Prism = PrismObject;
 
     additionalLanguages.forEach((lang) => {
-      require(`prismjs/components/prism-${lang}`); // eslint-disable-line
+      // eslint-disable-next-line global-require, import/no-dynamic-require
+      require(`prismjs/components/prism-${lang}`);
     });
 
     delete (window as Window & {Prism?: typeof PrismNamespace}).Prism;