Merge branch 'main' into dev

Author: ShenQingchuan

.vitepress/rewrite-title/index.js

@@ -1,5 +1,5 @@
 const path = require('path')
-const fs = require('fs')
+const fsp = require('fs').promises
 const matterService = require('../utils/frontmatter-service')
 const workspacePath = path.resolve(__dirname, '..', '..')
 
@@ -17,33 +17,28 @@ const rewriteMarkdownTitle = (filePath) => {
   matter.set('title', title).save()
 }
 
-const ergodicDirectory = (dirPath) => {
-  fs.readdir(dirPath, (err, files) => {
-    if (err) {
-      console.warn('Directory reading failed !')
-      return
-    }
-
-    files.forEach((file) => {
-      const filePath = path.join(dirPath, file)
-      fs.stat(filePath, (err, stats) => {
-        if (err) {
-          console.warn('File status reading failed !')
-          return
+const ergodicDirectory = async (dirPath) => {
+  try {
+    const files = await fsp.readdir(dirPath)
+    for (let i = 0; i < files.length; i++) {
+      const file = files[i],
+        filePath = path.join(dirPath, file)
+      const stats = await fsp.stat(filePath)
+      if (stats.isFile()) {
+        if (filePath.split('.').pop().toLowerCase() === 'md') {
+          rewriteMarkdownTitle(filePath)
         }
-
-        if (stats.isFile()) {
-          if (filePath.split('.').pop().toLowerCase() === 'md') {
-            rewriteMarkdownTitle(filePath)
-          }
-        } else if (stats.isDirectory()) {
-          if (articleDirs.includes(filePath.split('/').pop())) {
-            ergodicDirectory(filePath)
-          }
+      } else if (stats.isDirectory()) {
+        if (articleDirs.includes(filePath.split('/').pop())) {
+          await ergodicDirectory(filePath)
         }
-      })
-    })
-  })
+      }
+    }
+  } catch (err) {
+    console.warn(
+      `vite-docs-cn: failed to rewrite frontmatter for titles.\n ${err}!`
+    )
+  }
 }
 
-ergodicDirectory(workspacePath)
+module.exports = () => ergodicDirectory(workspacePath)

.vitepress/theme/fetchReleaseTag.js

@@ -13,8 +13,9 @@ export default function fetchReleaseTag() {
         const releaseTagName = json.tag_name
         docsReleaseTag.innerText = releaseTagName
 
-
-        mainTitle.appendChild(docsReleaseTag)
+        if (releaseTagName !== undefined) {
+          mainTitle.appendChild(docsReleaseTag)
+        }
       })
   })
 }

guide/api-plugin.md

@@ -6,7 +6,7 @@ Vite 插件扩展了设计出色的 Rollup 接口，带有一些 Vite 独有的
 
 ## 约定 {#conventions}
 
-如果插件不使用 Vite 特有的钩子，可以实现为 [兼容的 Rollup 插件](#Rollup-插件兼容性)，推荐使用 [Rollup 插件名称约定](https://rollupjs.org/guide/en/#conventions)。
+如果插件不使用 Vite 特有的钩子，可以实现为 [兼容的 Rollup 插件](#rollup-plugin-compatibility)，推荐使用 [Rollup 插件名称约定](https://rollupjs.org/guide/en/#conventions)。
 
 - Rollup 插件应该有一个带 `rollup-plugin-` 前缀、语义清晰的名称。
 - 在 package.json 中包含 `rollup-plugin` 和 `vite-plugin` 关键字。

guide/assets.md

@@ -85,7 +85,7 @@ import InlineWorker from './shader.js?worker&inline'
 
 ## new URL(url, import.meta.url)
 
-[import.meta.url](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import.meta) 是一个 ESM 的原生功能。，会暴露当前模块的 URL。将它与原生的 [URL 构造器](https://developer.mozilla.org/en-US/docs/Web/API/URL) 结合，传入静态资源与本模块相对的地址，即可得到被完整解析的 URL：
+[import.meta.url](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import.meta) 是一个 ESM 的原生功能，会暴露当前模块的 URL。将它与原生的 [URL 构造器](https://developer.mozilla.org/en-US/docs/Web/API/URL) 组合使用，在一个 JavaScript 模块中，通过相对路径我们就能得到一个被完整解析的静态资源 URL：
 
 ```js
 const imgUrl = new URL('./img.png', import.meta.url)

guide/build.md

@@ -98,7 +98,7 @@ module.exports = {
 
 当你开发面向浏览器的库时，你可能会将大部分时间花在该库的测试/演示页面上。在 Vite 中你可以使用 `index.html` 获得如丝般顺滑的开发体验。
 
-当你以发布为目的构建库时，请使用 [`build.lib` 配置项](/config/#build-lib)，以确保将那些你不想打包进库的依赖进行外部化处理，例如 `vue` 或 `react`：
+当这个库要进行发布构建时，请使用 [`build.lib` 配置项](/config/#build-lib)，以确保将那些你不想打包进库的依赖进行外部化处理，例如 `vue` 或 `react`：
 
 ```js
 // vite.config.js

guide/env-and-mode.md

@@ -4,7 +4,7 @@
 
 Vite 在一个特殊的 **`import.meta.env`** 对象上暴露环境变量。这里有一些在所有情况下都可以使用的内建变量：
 
-- **`import.meta.env.MODE`**: {string} 应用运行的[模式](#模式)。
+- **`import.meta.env.MODE`**: {string} 应用运行的[模式](#modes)。
 
 - **`import.meta.env.BASE_URL`**: {string} 部署应用时的基本 URL。他由[`base` 配置项](/config/#base)决定。
 

guide/index.md

@@ -96,7 +96,7 @@ npx degit user/project#main my-project
 
 Vite 将 `index.html` 视为源码和模块图的一部分。Vite 解析 `<script type="module" src="...">` ，这个标签指向你的 JavaScript 源码。甚至内联引入 JavaScript 的 `<script type="module">` 和引用 CSS 的 `<link href>` 也能利用 Vite 特有的功能被解析。另外，`index.html` 中的 URL 将被自动转换，因此不再需要 `%PUBLIC_URL%` 占位符了。
 
-与静态 HTTP 服务器类似，Vite 也有 “根目录” 的概念，即文件被提供的位置。你会看到它在整个文档中用 `<root>` 表示。源码中的绝对 URL 路径将以项目的 “根” 作为基础来解析，因此你可以像在普通的静态文件服务器上一样编写代码（并且功能更强大！）。Vite 还能够处理依赖关系，解析处于根目录外的文件位置，这使得它即使在基于 monorepo 的方案中也十分有用。
+与静态 HTTP 服务器类似，Vite 也有 “根目录” 的概念，即服务文件的位置，在接下来的文档中你将看到它会以 `<root>` 代称。源码中的绝对 URL 路径将以项目的 “根” 作为基础来解析，因此你可以像在普通的静态文件服务器上一样编写代码（并且功能更强大！）。Vite 还能够处理依赖关系，解析处于根目录外的文件位置，这使得它即使在基于 monorepo 的方案中也十分有用。
 
 Vite 也支持多个 `.html` 作入口点的 [多页面应用模式](./build#multi-page-app)。
 

package.json

@@ -13,7 +13,7 @@
 	},
 	"scripts": {
 		"dev": "vitepress dev .",
-		"build": "node ./.vitepress/rewrite-title/ && vitepress build .",
+		"build": "node ./scripts/build.js",
 		"serve": "vitepress serve ."
 	},
 	"gitHooks": {

scripts/build.js

@@ -0,0 +1,24 @@
+const vitpress = require('vitepress')
+const path = require('path')
+const chalk = require('chalk')
+
+/** 构建说明：
+ *
+ *  所有需要的构建步骤，都应封装为返回 Promise 的函数
+ *  保证不会因为任何异步操作导致构建错误或失败
+ * （若有顺序必要，则依次调用）
+ */
+
+const rewriteTitle = require('../.vitepress/rewrite-title')
+
+rewriteTitle().then(() => {
+  vitpress
+    .build(path.resolve(__dirname, '..'))
+    .then(() => {
+      chalk.green('build success!')
+    })
+    .catch((err) => {
+      console.error(chalk.red(`build error:\n`), err)
+      process.exit(1)
+    })
+})