feat(doc-tools): add doc medium-zoom plugin (#3716)

Author: sanyuan0704

.changeset/tidy-eagles-cover.md

@@ -0,0 +1,7 @@
+---
+'@modern-js/doc-core': patch
+---
+
+feat: add doc medium-zoom plugin
+
+feat: 增加 medium-zoom 插件

packages/builder/builder-shared/tests/plugins/__snapshots__/AutoSetRootFontSizePlugin.test.ts.snap

@@ -57,7 +57,7 @@ exports[`test getRootPixelCode > should getRootPixelCode with custom options 1`]
 typeof window !== 'undefined' && setRootPixel();"
 `;
 
-exports[`test getRootPixelCode > should getRootPixelCode with custom options 2`] = `"function setRootPixel(){function n(n){return(new RegExp(\\"[?&]\\"+n+\\"=([^&#\\\\b]+)\\").exec(location.search||\\"\\")||[])[1]}function e(){var e,i=\\"widthKey\\",t=document.documentElement;if(i&&+n(i))e=+n(i);else if(e=window.innerWidth&&t.clientWidth?Math.min(window.innerWidth,t.clientWidth):window.innerWidth||t.clientWidth||document.body&&document.body.clientWidth||750,(screen.orientation&&screen.orientation.angle||window.orientation)/90%2){var o=window.innerHeight&&t.clientHeight?Math.min(window.innerHeight,t.clientHeight):window.innerHeight||t.clientHeight||document.body&&document.body.clientHeight||750;e=Math.max(o,350)}var d=5*e/750;d=d<64?d:5,window.ROOT_FONT_SIZE=d,t.style.fontSize=d+\\"px\\"}function i(n){n?e():setTimeout(e,30)}i(!0),window.addEventListener(\\"resize\\",i,!1),\\"onorientationchange\\"in window&&window.addEventListener(\\"orientationchange\\",i,!1)}\\"undefined\\"!=typeof window&&setRootPixel();"`;
+exports[`test getRootPixelCode > should getRootPixelCode with custom options 2`] = `"function setRootPixel(){function n(n){return(new RegExp(\\"[?&]\\"+n+\\"=([^&#\\\\b]+)\\").exec(location.search||\\"\\")||[])[1]}function e(){var e,i=\\"widthKey\\",t=document.documentElement;if(+n(i))e=+n(i);else if(e=window.innerWidth&&t.clientWidth?Math.min(window.innerWidth,t.clientWidth):window.innerWidth||t.clientWidth||document.body&&document.body.clientWidth||750,(screen.orientation&&screen.orientation.angle||window.orientation)/90%2){var o=window.innerHeight&&t.clientHeight?Math.min(window.innerHeight,t.clientHeight):window.innerHeight||t.clientHeight||document.body&&document.body.clientHeight||750;e=Math.max(o,350)}var d=5*e/750;d=d<64?d:5,window.ROOT_FONT_SIZE=d,t.style.fontSize=d+\\"px\\"}function i(n){n?e():setTimeout(e,30)}i(!0),window.addEventListener(\\"resize\\",i,!1),\\"onorientationchange\\"in window&&window.addEventListener(\\"orientationchange\\",i,!1)}\\"undefined\\"!=typeof window&&setRootPixel();"`;
 
 exports[`test getRootPixelCode > should getRootPixelCode with default options 1`] = `
 "function setRootPixel() {

packages/cli/doc-core/package.json

@@ -61,6 +61,7 @@
     "@modern-js/builder-rspack-provider": "workspace:*",
     "@modern-js/mdx-rs-binding": "^0.1.8",
     "@modern-js/remark-container": "workspace:*",
+    "@modern-js/doc-plugin-medium-zoom": "workspace:*",
     "@modern-js/utils": "workspace:*",
     "@types/compression": "^1.7.2",
     "@types/polka": "^0.5.4",
@@ -79,7 +80,6 @@
     "html-to-text": "^9.0.3",
     "lodash-es": "^4.17.21",
     "mdast-util-mdxjs-esm": "^1.3.0",
-    "medium-zoom": "1.0.8",
     "node-fetch": "3.3.0",
     "nprogress": "^0.2.0",
     "ora": "5.4.1",

packages/cli/doc-core/src/node/build.ts

@@ -12,7 +12,7 @@ import {
 } from './constants';
 import { createModernBuilder } from './createBuilder';
 import { writeSearchIndex } from './searchIndex';
-import { modifyConfig, beforeBuild, afterBuild } from './hooks';
+import { modifyConfig, beforeBuild, afterBuild, loadPlugins } from './hooks';
 import { logger } from './utils';
 import { APPEARANCE_KEY, normalizeSlash } from '@/shared/utils';
 import type { Route } from '@/node/route/RouteService';
@@ -137,6 +137,8 @@ export async function renderPages(config: UserConfig) {
 
 export async function build(rootDir: string, config: UserConfig) {
   const isProd = true;
+  await loadPlugins(config);
+
   const modifiedConfig = await modifyConfig({
     config,
   });

packages/cli/doc-core/src/node/dev.ts

@@ -2,7 +2,7 @@ import { UserConfig } from 'shared/types';
 import { removeLeadingSlash } from '../shared/utils';
 import { createModernBuilder } from './createBuilder';
 import { writeSearchIndex } from './searchIndex';
-import { modifyConfig, beforeBuild, afterBuild } from './hooks';
+import { modifyConfig, beforeBuild, afterBuild, loadPlugins } from './hooks';
 
 interface ServerInstance {
   close: () => Promise<void>;
@@ -14,7 +14,7 @@ export async function dev(
 ): Promise<ServerInstance> {
   const base = config.doc?.base ?? '';
   const isProd = false;
-
+  await loadPlugins(config);
   try {
     const modifiedConfig = await modifyConfig({
       config,

packages/cli/doc-core/src/node/hooks.ts

@@ -1,5 +1,4 @@
 import { UserConfig, PageIndexInfo, DocPlugin } from 'shared/types';
-import { pluginLastUpdated } from './plugins/lastUpdated';
 import { AdditionalPage } from '@/shared/types/Plugin';
 
 type HookOptions = {
@@ -8,20 +7,35 @@ type HookOptions = {
   pageData?: PageIndexInfo;
 };
 
-function getPlugins(config: UserConfig) {
-  const plugins: DocPlugin[] = config.doc?.plugins || [];
+let docPlugins: DocPlugin[] = [];
+
+// The init function is used to initialize the doc plugins and will execute before the build process.
+export async function loadPlugins(config: UserConfig) {
+  // Clear docPlugins first, for the watch mode
+  docPlugins = [];
   const enableLastUpdated =
     config.doc.themeConfig?.lastUpdated ||
     config.doc.themeConfig?.locales?.some(locale => locale.lastUpdated);
+  const mediumZoomConfig = config.doc.mediumZoom ?? true;
   if (enableLastUpdated) {
-    plugins.push(pluginLastUpdated());
+    const { pluginLastUpdated } = await import('./plugins/lastUpdated');
+    docPlugins.push(pluginLastUpdated());
+  }
+  if (mediumZoomConfig) {
+    const { pluginMediumZoom } = await import(
+      '@modern-js/doc-plugin-medium-zoom'
+    );
+    docPlugins.push(
+      pluginMediumZoom(
+        typeof mediumZoomConfig === 'object' ? mediumZoomConfig : undefined,
+      ),
+    );
   }
-  return plugins;
+  docPlugins.push(...(config.doc.plugins || []));
 }
 
 export async function modifyConfig(hookOptions: HookOptions) {
   const { config } = hookOptions;
-  const docPlugins = getPlugins(config);
 
   // config hooks
   for (const plugin of docPlugins) {
@@ -35,7 +49,6 @@ export async function modifyConfig(hookOptions: HookOptions) {
 
 export async function beforeBuild(hookOptions: HookOptions) {
   const { config, isProd = true } = hookOptions;
-  const docPlugins = getPlugins(config);
 
   // beforeBuild hooks
   return await Promise.all(
@@ -49,7 +62,6 @@ export async function beforeBuild(hookOptions: HookOptions) {
 
 export async function afterBuild(hookOptions: HookOptions) {
   const { config, isProd = true } = hookOptions;
-  const docPlugins = getPlugins(config);
 
   // afterBuild hooks
   return await Promise.all(
@@ -63,7 +75,6 @@ export async function afterBuild(hookOptions: HookOptions) {
 
 export async function extendPageData(hookOptions: HookOptions): Promise<void> {
   const { pageData } = hookOptions;
-  const docPlugins = getPlugins(hookOptions.config);
   // extendPageData hooks
   await Promise.all(
     docPlugins
@@ -78,7 +89,6 @@ export async function addPages(
   hookOptions: HookOptions,
 ): Promise<AdditionalPage[]> {
   const { config } = hookOptions;
-  const docPlugins = getPlugins(config);
 
   // addPages hooks
   const result = await Promise.all(
@@ -91,3 +101,23 @@ export async function addPages(
 
   return result.flat();
 }
+
+export async function globalUIComponents(): Promise<string[]> {
+  // globalUIComponents hooks
+  const result = docPlugins.map(plugin => {
+    return plugin.globalUIComponents || [];
+  });
+
+  return result.flat();
+}
+
+export async function globalStyles(): Promise<string[]> {
+  // globalStyles hooks
+  const result = docPlugins
+    .filter(plugin => typeof plugin.globalStyles === 'string')
+    .map(plugin => {
+      return plugin.globalStyles;
+    });
+
+  return result;
+}

packages/cli/doc-core/src/node/runtimeModule/globalStyles.ts

@@ -1,18 +1,20 @@
 import { join } from 'path';
+import { globalStyles } from '../hooks';
 import RuntimeModulesPlugin from './RuntimeModulePlugin';
 import { RuntimeModuleID } from '.';
 import { UserConfig } from '@/shared/types';
 
-export function globalStylesVMPlugin(
+export async function globalStylesVMPlugin(
   _scanDir: string,
   config: UserConfig,
   _isSSR: boolean,
   runtimeTempDir: string,
 ) {
   const modulePath = join(runtimeTempDir, `${RuntimeModuleID.GlobalStyles}.js`);
+  const globalStylesByPlugins = await globalStyles();
   const moduleContent = [
     config.doc?.globalStyles || '',
-    ...(config.doc?.plugins || []).map(plugin => plugin.globalStyles || ''),
+    ...globalStylesByPlugins,
   ]
     .filter(source => source.length > 0)
     .map(source => `import '${source}';`)

packages/cli/doc-core/src/node/runtimeModule/globalUIComponents.ts

@@ -1,9 +1,10 @@
 import { join } from 'path';
+import { globalUIComponents } from '../hooks';
 import RuntimeModulesPlugin from './RuntimeModulePlugin';
 import { RuntimeModuleID } from '.';
 import { UserConfig } from '@/shared/types';
 
-export function globalUIComponentsVMPlugin(
+export async function globalUIComponentsVMPlugin(
   _scanDir: string,
   config: UserConfig,
   _isSSR: boolean,
@@ -14,11 +15,10 @@ export function globalUIComponentsVMPlugin(
     runtimeTempDir,
     `${RuntimeModuleID.GlobalComponents}.js`,
   );
+  const globalUIComponentsByPlugins = await globalUIComponents();
   const moduleContent = [
     ...(config.doc?.globalUIComponents || []),
-    ...(config.doc?.plugins || [])
-      .map(plugin => plugin.globalUIComponents || [])
-      .flat(),
+    ...globalUIComponentsByPlugins,
   ]
     .map(source => `import Comp_${index++} from '${source}';`)
     .concat(

packages/cli/doc-core/src/shared/types/index.ts

@@ -119,6 +119,14 @@ export interface DocConfig<ThemeConfig = DefaultThemeConfig> {
    * Search options
    */
   search?: SearchOptions;
+  /**
+   * Whether to enable medium-zoom, default is true
+   */
+  mediumZoom?:
+    | boolean
+    | {
+        selector?: string;
+      };
 }
 
 export type BaseRuntimePageInfo = Omit<

packages/cli/doc-core/src/theme-default/layout/DocLayout/index.tsx

@@ -1,7 +1,6 @@
 import { useLocation } from 'react-router-dom';
 import { useEffect, useState } from 'react';
 import { MDXProvider } from '@mdx-js/react';
-import mediumZoom from 'medium-zoom';
 import { Aside } from '../../components/Aside';
 import { DocFooter } from '../../components/DocFooter';
 import { useLocaleSiteData, useSidebarData } from '../../logic';
@@ -20,15 +19,6 @@ export interface DocLayoutProps {
   afterOutline?: React.ReactNode;
 }
 
-function DocContent() {
-  const { pathname } = useLocation();
-  useEffect(() => {
-    const images = document.querySelectorAll('.modern-doc img');
-    mediumZoom(images);
-  }, [pathname]);
-  return <Content />;
-}
-
 export function DocLayout(props: DocLayoutProps) {
   const { beforeDocFooter, beforeDoc, afterDoc, beforeOutline, afterOutline } =
     props;
@@ -86,7 +76,7 @@ export function DocLayout(props: DocLayoutProps) {
             <div className="modern-doc">
               <TabDataContext.Provider value={{ tabData, setTabData }}>
                 <MDXProvider components={getCustomMDXComponent()}>
-                  <DocContent />
+                  <Content />
                 </MDXProvider>
               </TabDataContext.Provider>
               <div>