@modern-js/module-tools-docs 2.29.0 → 2.31.0

package/docs/zh/api/config/testing.md

@@ -17,7 +17,7 @@ sidebar_position: 5
 
 对应 [Jest](https://jestjs.io/docs/configuration) 的配置，当为 `object` 类型时，可以配置 Jest 所支持的所有底层配置 。
 
-```js modern.config.ts
+```js title="modern.config.ts"
 import { defineConfig } from '@modern-js/module-tools';
 
 export default defineConfig({
@@ -31,7 +31,7 @@ export default defineConfig({
 
 值为 `Function` 类型时，默认配置作为第一个参数传入，需要返回新的 Jest 配置对象。
 
-```js modern.config.ts
+```js title="modern.config.ts"
 import { defineConfig } from '@modern-js/module-tools';
 
 export default defineConfig({

package/docs/zh/components/register-esbuild-plugin.mdx

@@ -1,11 +1,11 @@
-```js modern.config.ts
+```js title="modern.config.ts"
 import { myEsbuildPlugin } from './myEsbuildPlugin';
 
 export default defineConfig({
   buildConfig: {
     esbuildOptions: options => {
       options.plugins = [myEsbuildPlugin, ...options.plugins];
-      return option;
+      return options;
     },
   },
 });

package/docs/zh/guide/advance/asset.mdx

@@ -19,44 +19,30 @@ sidebar_position: 7
 - 设置静态资源路径为 `./assets`。
 - 对于不超过 **10kb** 的文件会内联到代码中。
 
+### 示例
+
 让我们看下面的例子：
 
-<CH.Spotlight>
+- 项目源代码：
 
-```ts ./src/asset.ts
+```ts title="./src/asset.ts"
 import img from './bg.png';
 console.log(img);
 ```
 
----
-
-项目源代码。
-
----
-
-如果 `bg.png` 的大小小于 10 kb，则此时产物目录结构和产物内容为。
-
-<CH.Code>
+- 如果 `bg.png` 的大小小于 10 kb，则此时产物目录结构和产物内容为：
 
 ```bash
 ./dist
 └── asset.js
 ```
 
----
-
-```js ./dist/asset.js
+```js title="./dist/asset.js"
 var img_default = 'data:image/png;base64,';
 console.info(img_default);
 ```
 
-</CH.Code>
-
----
-
-如果 `bg.png` 的大小大于 10 kb，则此时产物目录结构和产物内容为。
-
-<CH.Code>
+- 如果 `bg.png` 的大小大于 10 kb，则此时产物目录结构和产物内容为：
 
 ```bash
 ./dist
@@ -65,19 +51,12 @@ console.info(img_default);
     └── bg.13e2aba2.png
 ```
 
----
-
-```js ./dist/asset.js
+```js title="./dist/asset.js"
 import img from './assets/bg.13e2aba2.png';
 console.info(img);
 ```
 
-</CH.Code>
-
-</CH.Spotlight>
-
-当想要修改默认行为的时候，可以使用以下 API：
+当你想要修改默认行为的时候，可以使用以下 API：
 
 - `asset.path`：修改静态资源文件输出路径。
 - `asset.limit`：修改内联静态资源文件的阈值。
-

package/docs/zh/guide/advance/build-umd.mdx

@@ -25,35 +25,21 @@ export default defineConfig({
 在 [「如何处理第三方依赖」](/guide/advance/external-dependency) 章节中，我们知道可以通过 [`autoExternals`](/api/config/build-config#autoexternal) 和 [`externals`](/api/config/build-config#externals) API 来控制项目是否对第三方依赖打包。
 因此在构建 umd 产物的过程中，我们也可以这样使用：
 
-<CH.Spotlight>
+### 示例
 
-```json package.json
-{
-  "dependencies": {
-    "react": "^17"
-    //...other dependencies
-  }
-}
-```
+- 如果项目依赖了 `react`：
 
----
-
-如果项目依赖了 `react`。
-
-```json package.json
+```json title="package.json"
 {
   "dependencies": {
     "react": "^17"
-    //...other dependencies
   }
 }
 ```
 
----
-
-`modern.config.ts` 配置。
+- `modern.config.ts` 配置：
 
-```ts
+```ts title="modern.config.ts"
 export default defineConfig({
   buildConfig: {
     format: 'umd',
@@ -63,20 +49,16 @@ export default defineConfig({
 });
 ```
 
----
-
-当源码中使用了 `react` 依赖。
+- 当源码中使用了 `react` 依赖：
 
-```tsx src/index.ts
+```tsx title="src/index.ts"
 import React from 'react';
 console.info(React);
 ```
 
----
-
-此时产物中不会将 `react` 代码打包到产物中。
+- 此时产物中不会将 `react` 代码打包到产物中：
 
-```js dist/index.js focus=1:7
+```js title="dist/index.js"
 (function (global, factory) {
   if (typeof module === 'object' && typeof module.exports === 'object')
     factory(exports, require('react'));
@@ -103,42 +85,18 @@ console.info(React);
 });
 ```
 
-</CH.Spotlight>
-
 通过上面的例子我们知道，当使用 `autoExternal` 和 `externals` API 后：
 
 - 在 Node.js 环境下，可以通过 `require('react')` 获取 react 依赖。
 - 在 浏览器环境下，可以通过 `global.react` 获取 react 依赖。
 
+### 三方依赖的全局变量名称
+
 然而在浏览器环境下，获取第三方依赖的时候，**全局变量名称不一定与依赖名称完全相同**，此时就要使用 [`buildConfig.umdGlobals`](/api/config/build-config#umdglobals) API。
 
 还是使用之前的例子，当 `react` 依赖以 `windows.React` 或者 `global.React` 全局变量的形式存在于浏览器环境下，那么此时：
 
-<CH.Spotlight>
-
-```json package.json
-{
-  "devDependencies": {
-    "react": "^17"
-  }
-}
-```
-
----
-
-如果项目依赖了 `react`。
-
-```json package.json
-{
-  "devDependencies": {
-    "react": "^17"
-  }
-}
-```
-
----
-
-`modern.config.ts` 配置。
+- `modern.config.ts` 配置：
 
 ```ts
 export default defineConfig({
@@ -151,20 +109,16 @@ export default defineConfig({
 });
 ```
 
----
-
-当源码中使用了 `react` 依赖。
+- 当源码中使用了 `react` 依赖：
 
-```tsx src/index.ts
+```tsx title="src/index.ts"
 import React from 'react';
 console.info(React);
 ```
 
----
+- 此时我们会看到这样的产物代码：
 
-此时我们会看到这样的产物代码。
-
-```js dist/index.js focus=12:18
+```js title="dist/index.js"
 (function (global, factory) {
   if (typeof module === 'object' && typeof module.exports === 'object')
     factory();
@@ -187,15 +141,13 @@ console.info(React);
 });
 ```
 
-</CH.Spotlight>
-
 此时项目就可以运行在浏览器中，并使用存在于全局对象上的 `React` 变量了。
 
 ## 更改项目的全局变量名称
 
 当我们将下面的代码打包成 umd 产物并运行在浏览器的时候，我们可以通过 `window.index` 来使用该模块。
 
-```ts ./src/index.ts
+```ts title="./src/index.ts"
 export default () => {
   console.info('hello world');
 };
@@ -203,7 +155,7 @@ export default () => {
 
 **默认情况下，以源码文件名称作为该模块在浏览器里全局变量的名称**。对于上面的例子，其产物内容如下：
 
-```js ./dist/index.js focus=9:9
+```js title="./dist/index.js"
 (function (global, factory) {
   if (typeof module === 'object' && typeof module.exports === 'object')
     factory(exports);
@@ -233,7 +185,7 @@ export default defineConfig({
 
 此时构建产物的内容为：
 
-```js ./dist/index.js focus=9:9
+```js title="./dist/index.js"
 (function (global, factory) {
   if (typeof module === 'object' && typeof module.exports === 'object')
     factory(exports);

package/docs/zh/guide/advance/external-dependency.mdx

@@ -6,7 +6,7 @@ sidebar_position: 4
 
 一般来说，项目所需要的第三方依赖可以通过包管理器的 `install` 命令安装，在安装第三方依赖成功后，这些第三方依赖一般会出现在项目 `package.json` 的 `dependencies` 和 `devDependencies` 下。
 
-```json pacakge.json
+```json title="pacakge.json"
 {
   "dependencies": {},
   "devDependencies": {}
@@ -25,25 +25,11 @@ sidebar_position: 4
 
 如果需要打包某些依赖，建议将它们从 `"dependencies"` 挪到 `"devDependencies"` ，这相当于对依赖进行 **prebundle** ，可以减小依赖安装的体积。
 
-<CH.Spotlight>
+### 示例
 
-```json ./v1/package.json
-{
-  "dependencies": {
-    "react": "^17"
-  },
-  // or
-  "peerDependencies": {
-    "react": "^17"
-  }
-}
-```
-
----
+如果项目依赖了 `react`:
 
-如果项目依赖了 `react`。
-
-```json ./v1/package.json
+```json title="package.json"
 {
   "dependencies": {
     "react": "^17"
@@ -55,26 +41,20 @@ sidebar_position: 4
 }
 ```
 
----
+当源码中使用了 `react` 依赖:
 
-当源码中使用了 `react` 依赖。
-
-```tsx src/index.ts
+```tsx title="src/index.ts"
 import React from 'react';
 console.info(React);
 ```
 
----
-
-此时产物中不会将 `react` 代码打包到产物中。
+此时产物中不会包含 `react` 的代码:
 
-```js dist/index.js
+```js title="dist/index.js"
 import React from 'react';
 console.info(React);
 ```
 
-</CH.Spotlight>
-
 如果想要修改默认的处理方式，可以通过下面的 API 进行修改：
 
 - [`buildConfig.autoExternal`](/api/config/build-config#autoexternal)

package/docs/zh/guide/advance/in-depth-about-build.md

@@ -50,7 +50,7 @@ Bundleless 是单文件编译模式，因此对于类型的引用和导出你需
 
 在 Bundle 构建过程中，除了将 `input` 设置为一个数组，也可以将它设置为一个对象。**通过使用对象的形式，我们可以修改构建产物输出的文件名称**。那么对于下面的例子，`./src/index.ts` 对应的构建产物文件路径为 `./dist/main.js`。
 
-```js modern.config.ts
+```js title="modern.config.ts"
 import { defineConfig } from '@modern-js/module-tools';
 
 export default defineConfig({
@@ -85,7 +85,7 @@ export default defineConfig({
 
 默认情况下类型生成功能是开启的，如果需要关闭的话，可以按照如下配置：
 
-```js modern.config.ts
+```js title="modern.config.ts"
 import { defineConfig } from '@modern-js/module-tools';
 
 export default defineConfig({
@@ -112,7 +112,7 @@ export default defineConfig({
 
 在 Bundleless 构建过程中，如果源代码中出现了别名，例如：
 
-```js ./src/index.ts
+```js title="./src/index.ts"
 import utils from '@common/utils';
 ```
 
@@ -231,7 +231,7 @@ console.log('1.0.0');
 
 > 如果不存在 `d.ts` 文件，则可以手动创建。
 
-```ts env.d.ts
+```ts title="env.d.ts"
 declare const YOUR_ADD_GLOBAL_VAR;
 ```
 

package/docs/zh/guide/advance/in-depth-about-dev-command.md

@@ -24,7 +24,7 @@ sidebar_position: 2
 
 一般来说，实现一个什么都不做的调试工具，其实现代码以及相关配置如下：
 
-``` ts do-nothing.ts
+```ts do-nothing.ts
 export const myPlugin = (): CliPlugin<ModuleTools> => ({
   name: 'do-nothing',
   setup() {
@@ -53,7 +53,7 @@ export const myPlugin = (): CliPlugin<ModuleTools> => ({
 
 如果需要使用该调试工具插件，则需要在配置文件中增加它：
 
-``` ts
+```ts
 import doNothingPlugin from './plugins/do-nothing';
 
 export default defineConfig({

package/docs/zh/guide/advance/theme-config.mdx

@@ -31,7 +31,7 @@ sidebar_position: 6
 
 例如在下面的配置中扩展了原有的颜色配置:
 
-```ts ./modern.config.ts
+```ts title="modern.config.ts"
 export default {
   designSystem: {
     extend: {
@@ -47,7 +47,7 @@ export default {
 
 #### HTML 类名
 
-```tsx ./src/index.tsx
+```tsx title="./src/index.tsx"
 import 'tailwindcss/utilities.css';
 
 export default () => {
@@ -59,9 +59,7 @@ export default () => {
 
 关于 [`@apply`](https://tailwindcss.com/docs/functions-and-directives#apply)。
 
-<CH.Code>
-
-```tsx ./src/index.tsx
+```tsx title="./src/index.tsx"
 import './index.css';
 
 export default () => {
@@ -69,10 +67,8 @@ export default () => {
 };
 ```
 
-```css ./src/index.css
+```css title="./src/index.css"
 .btn-primary {
   @apply bg-primary;
 }
 ```
-
-</CH.Code>

package/docs/zh/guide/basic/publish-your-project.md

@@ -41,7 +41,7 @@ $ npx modern change
 
 当执行成功后，生成的包含变更记录的 Markdown 文件会保存在项目的 `.changeset` 目录下面。其内容类似下面这样：
 
-```markdown .changeset/brave-dryers-agree.md
+```markdown title=".changeset/brave-dryers-agree.md"
 ---
 'module-example': patch
 ---
@@ -57,7 +57,7 @@ publish test
 
 执行 `modern bump` 将会基于 `.changeset/` 目录下记录了变更的 Markdown 文件内容来修改 `package.json` 中的版本号，同时生成 `CHANGELOG.md` 文件。**而当版本更新完成后，这些记录变更的 Markdown 文件也会被删除，也可说这些 Markdown 文件被“消耗”掉了**。
 
-```markdown CHANGELOG.md
+```markdown title="CHANGELOG.md"
 # module
 
 ## 0.1.1

package/docs/zh/guide/basic/test-your-project.mdx

@@ -10,7 +10,7 @@ sidebar_position: 6
 
 想要使用项目的测试功能，需要确保项目中包含依赖：`"@modern-js/plugin-testing"`，以及按照类似下面的内容进行配置：
 
-``` ts
+```ts
 import { moduleTools, defineConfig } from '@modern-js/module-tools';
 import { testingPlugin } from '@modern-js/plugin-testing';
 
@@ -59,31 +59,17 @@ modern test --updateSnapshot
 
 对于普通的模块，我们可以按照如下方式使用测试功能：
 
-<CH.Spotlight>
+- 首先是模块的代码：
 
-```ts ./src/index.ts
+```ts title="./src/index.ts"
 export default function () {
   return 'hello world';
 }
 ```
 
----
-
-首先是模块的代码。
-
-```ts ./src/index.ts
-export default function () {
-  return 'hello world';
-}
-```
+- 然后在测试文件中，我们可以按以下方式引用，其中 `@` 指向了源码目录，在初始化项目的 `tests/tsconfig.json` 的 `paths` 中定义了。
 
----
-
-然后在测试文件中，我们可以这样。
-
-其中 `@` 指向了源码目录，在初始化项目的 `tests/tsconfig.json` 的 `paths` 中定义了。
-
-```ts ./tests/index.test.ts
+```ts title="./tests/index.test.ts"
 import main from '@/index';
 
 describe('默认值 cases', () => {
@@ -95,9 +81,7 @@ describe('默认值 cases', () => {
 });
 ```
 
----
-
-最后我们可以执行 `modern test`。
+- 最后我们可以执行 `modern test`：
 
 ```bash
 pnpm test
@@ -107,8 +91,6 @@ yarn test
 npm run test
 ```
 
-</CH.Spotlight>
-
 ### 组件
 
 {/* 链接待补充 */}
@@ -119,21 +101,9 @@ npm run test
 如果需要使用 Runtime API，那么可以通过 [微生成器](/guide/basic/command-preview) 开启。
 :::
 
-<CH.Spotlight>
-
-```tsx ./src/index.tsx
-export const default () {
-  return (
-    <div>This is a UI Component</div>
-  );
-}
-```
-
----
+- 首先是组件的代码：
 
-首先是组件的代码。
-
-```tsx ./src/index.tsx
+```tsx title="./src/index.tsx"
 export const default () {
   return (
     <div>This is a UI Component</div>
@@ -141,13 +111,9 @@ export const default () {
 }
 ```
 
----
-
-然后在测试文件中，我们可以这样。
-
-其中 `@` 指向了源码目录，在初始化项目的 `tests/tsconfig.json` 的 `paths` 中定义了。
+- 然后在测试文件中，我们可以按以下方式引用，其中 `@` 指向了源码目录，在初始化项目的 `tests/tsconfig.json` 的 `paths` 中定义了。
 
-```tsx ./tests/index.test.tsx
+```tsx title="./tests/index.test.tsx"
 import { render, screen } from '@modern-js/runtime/testing';
 
 import Component from '@/index';
@@ -160,9 +126,7 @@ describe('默认值 cases', () => {
 });
 ```
 
----
-
-最后我们可以执行 `modern test`。
+- 最后我们可以执行 `modern test`。
 
 ```bash
 pnpm test
@@ -171,5 +135,3 @@ yarn test
 ## or
 npm run test
 ```
-
-</CH.Spotlight>

package/docs/zh/guide/basic/use-micro-generator.md

@@ -20,7 +20,7 @@ sidebar_position: 4
 
 :::tip
 在成功开启后，会提示需要手动在配置中增加如下类似的代码。
-``` ts
+```ts
 import { moduleTools, defineConfig } from '@modern-js/module-tools';
 import { testingPlugin } from '@modern-js/plugin-testing';
 
@@ -39,7 +39,7 @@ export default defineConfig({
 
 :::tip
 在成功开启后，会提示需要手动在配置中增加如下类似的代码。
-``` ts
+```ts
 import { moduleTools, defineConfig } from '@modern-js/module-tools';
 import { storybookPlugin } from '@modern-js/plugin-storybook';
 
@@ -67,7 +67,7 @@ export default defineConfig({
 
 :::tip
 在成功开启后，会提示需要手动在配置中增加如下类似的代码。
-``` ts
+```ts
 import { moduleTools, defineConfig } from '@modern-js/module-tools';
 import { tailwindcssPlugin } from '@modern-js/plugin-tailwindcss';
 
@@ -88,7 +88,7 @@ export default defineConfig({
 
 :::tip
 在成功开启后，会提示需要手动在配置中增加如下类似的代码。
-``` ts
+```ts
 import { moduleTools, defineConfig } from '@modern-js/module-tools';
 import runtime from '@modern-js/runtime/cli';