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

package/docs/zh/api/config/build-preset.mdx

@@ -13,7 +13,7 @@ sidebar_position: 2
 
 字符串的形式可以让你直接使用内置的预设。
 
-```js modern.config.ts
+```js title="modern.config.ts"
 import { defineConfig } from '@modern-js/module-tools';
 
 export default defineConfig({
@@ -34,7 +34,7 @@ export default defineConfig({
 
 :::
 
-```json package.json
+```json title="package.json"
 {
   "main": "./dist/lib/index.js",
   "module": "./dist/es/index.js",
@@ -72,7 +72,7 @@ export const buildConfig = [
 
 在类 [NPM](https://www.npmjs.com/) 包管理器下使用，并且 Library 支持类似 [unpkg](https://unpkg.com/) 的模式。在预设 `'npm-library'` 的基础上，额外提供 `umd` 产物。
 
-```json package.json
+```json title="package.json"
 {
     "main": "./dist/lib/index.js",
     "module": "./dist/es/index.js",
@@ -120,7 +120,7 @@ export const buildConfig = [
 
 对于源码中包含的样式文件，产物中提供样式的编译产物和样式的源文件。
 
-```json package.json
+```json title="package.json"
 {
     "main": "./dist/lib/index.js", // bundleless type
     "module": "./dist/es/index.js", // bundleless type
@@ -158,7 +158,7 @@ export const buildConfig = [
 
 在类 [NPM](https://www.npmjs.com/) 包管理器下使用的组件（库），同时支持类 [unpkg](https://unpkg.com/) 的模式。 在预设 `'npm-component'` 的基础上，额外提供 `umd` 产物。
 
-```json package.json
+```json title="package.json"
 {
     "main": "./dist/lib/index.js", // bundleless type
     "module": "./dist/es/index.js", // bundleless type
@@ -204,7 +204,7 @@ export const buildConfig = [
 
 例如希望 `'npm-library'` 预设支持 `'es2017'`，则可以按照如下方式配置：
 
-```js modern.config.ts
+```js title="modern.config.ts"
 import { defineConfig } from '@modern-js/module-tools';
 
 export default defineConfig({
@@ -217,7 +217,7 @@ export default defineConfig({
 函数的配置方式，可以通过 `preset` 参数获取到预设值，然后对里面的构建配置进行修改来自定义你的构建配置。
 以下是一个函数的配置方式的例子，它配置了压缩构建产物的功能：
 
-```js modern.config.ts
+```js title="modern.config.ts"
 import { defineConfig } from '@modern-js/module-tools';
 
 export default defineConfig({
@@ -248,10 +248,9 @@ export default defineConfig({
 
 包含了所有可用的构建预设对应的构建配置。可以通过 `buildPreset` 所支持的字符串来使用构建配置，也可以使用这些字符串的下划线命令的方式。下面是两种方式的使用示例：
 
+- 使用 `buildPreset` 所支持的字符串。
 
-<CH.Spotlight>
-
-```ts modern.config.ts
+```ts title="modern.config.ts"
 import { defineConfig } from '@modern-js/module-tools';
 
 export default defineConfig({
@@ -260,25 +259,10 @@ export default defineConfig({
   },
 });
 ```
----
 
-使用 `buildPreset` 所支持的字符串。
+- 使用 `buildPreset` 所支持的字符串的下划线命名方式。
 
-```ts modern.config.ts
-import { defineConfig } from '@modern-js/module-tools';
-
-export default defineConfig({
-  buildPreset({ preset }) {
-    return preset['npm-library'];
-  },
-});
-```
-
----
-
-使用 `buildPreset` 所支持的字符串的下划线命名方式。
-
-```ts modern.config.ts
+```ts title="modern.config.ts"
 import { defineConfig } from '@modern-js/module-tools';
 
 export default defineConfig({
@@ -288,8 +272,6 @@ export default defineConfig({
 });
 ```
 
-</CH.Spotlight>
-
 #### `extendPreset`
 
 类型：`Function`
@@ -300,7 +282,7 @@ export default defineConfig({
 
 例如在 `'npm-library'` 构建预设的基础上增加 `define` 配置：
 
-```ts modern.config.ts
+```ts title="modern.config.ts"
 import { defineConfig } from '@modern-js/module-tools';
 
 export default defineConfig({

package/docs/zh/api/config/design-system.md

@@ -969,7 +969,7 @@ const designSystem = {
 
 要覆盖默认配置中的选项，请在 `designSystem` 中添加要覆盖的属性：
 
-```js modern.config.ts
+```js title="modern.config.ts"
 import { defineConfig } from '@modern-js/module-tools';
 
 const designSystem = {
@@ -999,7 +999,7 @@ export default defineConfig({
 
 例如，如果您想添加一个额外的断点但保留现有的断点，则可以扩展 `screens` 属性：
 
-```js modern.config.ts
+```js title="modern.config.ts"
 import { defineConfig } from '@modern-js/module-tools';
 
 const designSystem = {
@@ -1018,7 +1018,7 @@ export default defineConfig({
 
 您当然可以覆盖默认主题的某些部分，并在同一配置中扩展默认主题的其他部分：
 
-```js modern.config.ts
+```js title="modern.config.ts"
 import { defineConfig } from '@modern-js/module-tools';
 
 const designSystem = {
@@ -1048,7 +1048,7 @@ export default defineConfig({
 
 例如，您可以在 `fill` 配置上通过引用 `theme('colors')` 为调色板中的每种颜色生成 `fill` utilities。
 
-```js modern.config.ts
+```js title="modern.config.ts"
 import { defineConfig } from '@modern-js/module-tools';
 
 const designSystem = {
@@ -1069,7 +1069,7 @@ export default defineConfig({
 
 如果出于任何原因想要引用默认配置中的值，则可以从 `tailwindcss/defaultTheme` 导入它。一个有用的示例是，如果要将添加默认配置提供的字体中某一个字体：
 
-```js modern.config.ts
+```js title="modern.config.ts"
 import { defineConfig } from '@modern-js/module-tools';
 
 const defaultTheme = require('tailwindcss/defaultTheme');
@@ -1134,7 +1134,7 @@ const designSystem = {
 
 另一个示例是在自定义插件中添加新的属性以进行引用。例如，如果您为项目编写了渐变插件，则可以向该插件引用的主题对象添加渐变属性：
 
-```js modern.config.ts
+```js title="modern.config.ts"
 import { defineConfig } from '@modern-js/module-tools';
 
 const designSystem = {

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

@@ -25,7 +25,7 @@ sidebar_position: 4
 
 使用 npm 上的插件，需要通过包管理器安装插件，并通过 import 引入。
 
-```js modern.config.ts
+```js title="modern.config.ts"
 import { myPlugin } from 'my-plugin';
 
 export default defineConfig({
@@ -37,7 +37,7 @@ export default defineConfig({
 
 使用本地代码仓库中的插件，直接通过相对路径 import 引入即可。
 
-```js modern.config.ts
+```js title="modern.config.ts"
 import { myPlugin } from './plugins/myPlugin';
 
 export default defineConfig({
@@ -49,7 +49,7 @@ export default defineConfig({
 
 如果插件提供了一些自定义的配置项，你可以通过插件函数的参数传入配置。
 
-```js modern.config.ts
+```js title="modern.config.ts"
 import { myPlugin } from 'my-plugin';
 
 export default defineConfig({

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