From 67ad2885445e1ef01be6a23a14bb4fe806d1b121 Mon Sep 17 00:00:00 2001 From: Xavi Lee Date: Sun, 31 Dec 2023 18:22:10 +0800 Subject: [PATCH] update --- docs/zh/guide/asset-handling.md | 8 +++--- docs/zh/guide/cms.md | 6 ++--- docs/zh/guide/custom-theme.md | 6 ++--- docs/zh/guide/data-loading.md | 31 ++++++++++++------------ docs/zh/guide/deploy.md | 8 +++--- docs/zh/guide/extending-default-theme.md | 2 +- docs/zh/guide/frontmatter.md | 4 +-- docs/zh/guide/ssr-compat.md | 7 +++--- docs/zh/guide/what-is-vitepress.md | 2 +- docs/zh/index.md | 4 +-- 10 files changed, 40 insertions(+), 38 deletions(-) diff --git a/docs/zh/guide/asset-handling.md b/docs/zh/guide/asset-handling.md index eb7ad1cb..adf50cb6 100644 --- a/docs/zh/guide/asset-handling.md +++ b/docs/zh/guide/asset-handling.md @@ -10,15 +10,15 @@ 你可以在 Markdown 文件、主题中的 `*.vue` 组件、样式和普通的 `.css` 文件中引用静态资源，通过使用绝对路径 (基于项目根目录) 或者相对路径 (基于文件系统)。后者类似于 Vite，Vue CLI，或者 webpack 的 `file-loader` 的行为。 -常见的图像，媒体和字体文件会被自动检测并包含为资源。 +常见的图像，媒体和字体文件会被自动检测并视作资源。 -所有引用的资源，包括那些使用绝对路径的，都会在生产构建过程中被复制到输出目录，并具有哈希文件名。从未使用过的资源将不会被复制。小于 4kb 的图像资源将会被使用 base64 内联 - 这可以通过 [`vite`](../reference/site-config#vite) 配置选项进行配置。 +所有引用的资源，包括那些使用绝对路径的，都会在生产构建过程中被复制到输出目录，并使用哈希文件名。从未使用过的资源将不会被复制。小于 4kb 的图像资源将会采用 base64 内联——这可以通过 [`vite`](../reference/site-config#vite) 配置选项进行配置。 所有**静态**路径引用，包括绝对路径，都应基于你的工作目录结构。 ## public 目录 {#the-public-directory} -有时你可能需要提供一些静态资源，但这些资源没有直接被 Markdown 或主题组件直接引用，或者你可能想以原始文件名提供提供某些文件。此类文件的例子包括 `robots.txt`，favicons 和 PWA 图标。 +有时你可能需要提供一些静态资源，但这些资源没有直接被 Markdown 或主题组件直接引用，或者你可能想以原始文件名提供某些文件，像 `robots.txt`，favicons 和 PWA 图标这样的文件。 你可以将这些文件放置在[源目录](./routing#source-directory)的 `public` 目录中。例如，如果你的项目根目录是 `./docs`，并且使用默认源目录位置，那么你的 public 目录将是 `./docs/public`。 @@ -28,7 +28,7 @@ ## 根 URL {#base-url} -如果你的网站部署在非根 URL 上，则需要在 `.vitepress/config.js` 中设置 `base` 选项。例如，如果你计划将网站部署到 `https://foo.github.io/bar/`，则 `base` 应设置为 `'/bar/'`(它应始终以斜杠开头和结尾)。 +如果你的网站没有部署在根 URL 上，则需要在 `.vitepress/config.js` 中设置 `base` 选项。例如，如果你计划将网站部署到 `https://foo.github.io/bar/`，则 `base` 应设置为 `'/bar/'`(它应始终以斜杠开头和结尾)。 所有静态资源路径都会被自动处理，来适应不同的 `base` 配置值。例如，如果你的 markdown 中有一个对 `public` 中的资源的绝对引用： diff --git a/docs/zh/guide/cms.md b/docs/zh/guide/cms.md index 5d19b071..c6d8bc0b 100644 --- a/docs/zh/guide/cms.md +++ b/docs/zh/guide/cms.md @@ -6,11 +6,11 @@ outline: deep ## 一般的工作流 {#general-workflow} -将 VitePress 连接到 CMS 主要围绕 [动态路由](./routing#dynamic-routes) 而展开。在继续之前，请确保了解它的工作原理。 +将 VitePress 连接到 CMS 主要围绕 [动态路由](./routing#dynamic-routes) 而展开。在继续阅读之前，请确保了解它的工作原理。 由于每个 CMS 的工作方式都不同，因此我们只能提供一个通用的工作流，你需要根据具体情况进行调整。 -1. 如果你的 CMS 需要身份验证，请创建一个 `.env` 文件来存储你的 API 令牌并加载它： +1. 如果你的 CMS 需要身份验证，请创建一个 `.env` 文件来存储你的 API 令牌： ```js // posts/[id].paths.js @@ -53,4 +53,4 @@ outline: deep ## 整合指南 {#integration-guides} -如果你已经写了一篇关于如何将 VitePress 与特定 CMS 集成的指南，请点击下面的 “在 GitHub 上编辑此页面” 链接将它提交到这里！ +如果你已经写了一篇关于如何将 VitePress 与特定 CMS 集成的指南，请点击下面的“在 GitHub 上编辑此页面”链接将它提交到这里！ diff --git a/docs/zh/guide/custom-theme.md b/docs/zh/guide/custom-theme.md index 424ca612..e62844aa 100644 --- a/docs/zh/guide/custom-theme.md +++ b/docs/zh/guide/custom-theme.md @@ -15,7 +15,7 @@ └─ package.json ``` -当检测到存在主题入口文件时，VitePress 总会使用自定义主题而不是默认主题。但你可以[拓展默认主题](./extending-default-theme)来在其基础上实现更高级的定制。 +当检测到存在主题入口文件时，VitePress 总会使用自定义主题而不是默认主题。但你可以[拓展默认主题](./extending-default-theme)来在其基础上实现更高级的自定义。 ## 主题接口 {#theme-interface} @@ -150,11 +150,11 @@ const { page, frontmatter } = useData() ``` -请查看[运行时 API 参考](../reference/runtime-api)获取主题组件中所有可用内容。此外，你可以利用[构建时数据加载](./data-loading) 来生成数据驱动布局 - 例如，一个列出当前项目中所有博客文章的页面。 +请查看[运行时 API 参考](../reference/runtime-api)获取主题组件中所有可用内容。此外，你可以利用[构建时数据加载](./data-loading)来生成数据驱动布局——例如，一个列出当前项目中所有博客文章的页面。 ## 分发自定义主题 {#distributing-a-custom-theme} -分发自定义主题最简单的方式是通过将其作为 [GitHub 模版仓库](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-template-repository) 来提供。 +分发自定义主题最简单的方式是通过将其作为 [GitHub 模版仓库](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-template-repository)。 如果你希望将主题作为 npm 包来分发，请按照下面的步骤操作： diff --git a/docs/zh/guide/data-loading.md b/docs/zh/guide/data-loading.md index 71aa922a..41ae29c9 100644 --- a/docs/zh/guide/data-loading.md +++ b/docs/zh/guide/data-loading.md @@ -1,12 +1,12 @@ # 构建时数据加载 {#build-time-data-loading} -VitePress 提供了一个叫做**数据加载器**的功能，它允许你加载任意数据并从页面或组件中导入它。数据加载**只在构建时**执行：最终的数据将被序列化为 JavaScript 包中的 JSON。 +VitePress 提供了**数据加载**的功能，它允许你加载任意数据并从页面或组件中导入它。数据加载**只在构建时**执行：最终的数据将被序列化为 JavaScript 包中的 JSON。 -数据加载器可以被用于获取远程数据，也可以基于本地文件生成元数据。例如，你可以使用数据加载器来解析所有本地 API 页面并自动生成所有 API 入口的索引。 +数据加载可以被用于获取远程数据，也可以基于本地文件生成元数据。例如，你可以使用数据加载器来解析所有本地 API 页面并自动生成所有 API 入口的索引。 ## 基本用法 {#basic-usage} -一个数据加载器文件必须以 `.data.js` 或 `.data.ts` 结尾。该文件应该提供一个默认导出的对象，该对象具有 `load()` 方法： +一个用于数据加载的文件必须以 `.data.js` 或 `.data.ts` 结尾。该文件应该提供一个默认导出的对象，该对象具有 `load()` 方法： ```js // example.data.js @@ -19,7 +19,7 @@ export default { } ``` -数据加载器模块只在 Node.js 中执行，因此你可以按需导入 Node API 和 npm 依赖。 +数据加载模块只在 Node.js 中执行，因此你可以按需导入 Node API 和 npm 依赖。 然后，你可以在 `.md` 页面和 `.vue` 组件中使用 `data` 命名导出从该文件中导入数据： @@ -39,9 +39,9 @@ import { data } from './example.data.js' } ``` -你会注意到数据加载器本身并没有导出 `data`。这是因为 VitePress 在后台调用了 `load()` 方法，并通过名为 `data` 的命名导出隐式地暴露了结果。 +你会注意到数据加载本身并没有导出 `data`。这是因为 VitePress 在后台调用了 `load()` 方法，并通过名为 `data` 的命名导出隐式地暴露了结果。 -即使 loader 是异步的，这也是有效的： +即使它是异步的，这也是有效的： ```js export default { @@ -54,7 +54,7 @@ export default { ## 使用本地文件生成数据 {#data-from-local-files} -当你需要基于本地文件生成数据时，你应该在数据加载器中使用 `watch` 选项，以便这些文件改动时可以触发热更新。 +当你需要基于本地文件生成数据时，你应该在数据加载中使用 `watch` 选项，以便这些文件改动时可以触发热更新。 `watch` 选项也很方便，因为你可以使用 [glob 模式](https://github.com/mrmlnc/fast-glob#pattern-syntax) 匹配多个文件。模式可以相对于加载器文件本身，`load()` 函数将接收匹配文件的绝对路径。 @@ -91,9 +91,9 @@ import { createContentLoader } from 'vitepress' export default createContentLoader('posts/*.md', /* options */) ``` -该辅助函数接受一个相对于 [项目根目录](./routing#project-root) 的 glob 模式，并返回一个 `{ watch, load }` 数据加载器对象，该对象可以用作数据加载器文件中的默认导出。它还基于文件修改时间戳实现了缓存以提高开发性能。 +该辅助函数接受一个相对于[项目根目录](./routing#project-root)的 glob 模式，并返回一个 `{ watch, load }` 数据加载对象，该对象可以用作数据加载文件中的默认导出。它还基于文件修改时间戳实现了缓存以提高开发性能。 -请注意，加载器仅适用于 Markdown 文件 - 匹配的非 Markdown 文件将被跳过。 +请注意，数据加载仅适用于 Markdown 文件——匹配的非 Markdown 文件将被跳过。 加载的数据将是一个类型为 `ContentData[]` 数组： @@ -131,9 +131,9 @@ import { data as posts } from './posts.data.js' ``` -### Options {#options} +### 选项 {#options} -默认数据可能不适合所有需求 - 你可以选择使用选项转换数据： +默认数据可能不适合所有需求——你可以选择使用选项转换数据： ```js // posts.data.js @@ -158,9 +158,9 @@ export default createContentLoader('posts/*.md', { }) ``` -查看它在 [Vue.js 博客](https://github.com/vuejs/blog/blob/main/.vitepress/theme/posts.data.ts) 中是如何使用的。 +查看它在 [Vue.js 博客](https://github.com/vuejs/blog/blob/main/.vitepress/theme/posts.data.ts)中是如何使用的。 -`createContentLoader` API 也可以在 [构建钩子](/reference/site-config#build-hooks) 中使用： +`createContentLoader` API 也可以在[构建钩子](/reference/site-config#build-hooks)中使用： ```js // .vitepress/config.js @@ -207,7 +207,8 @@ interface ContentOptions { | string /** - * 转换数据。请注意，如果从组件或 Markdown 文件导入，数据将以 JSON 形式内联到客户端包中。 + * Transform the data. Note the data will be inlined as JSON in the client + * bundle if imported from components or markdown files. */ transform?: (data: ContentData[]) => T | Promise } @@ -238,7 +239,7 @@ export default defineLoader({ ## 配置 {#configuration} -要获取加载器中的配置信息，可以使用如下代码： +要获取数据加载中的配置信息，可以使用如下代码： ```ts import type { SiteConfig } from 'vitepress' diff --git a/docs/zh/guide/deploy.md b/docs/zh/guide/deploy.md index da1194b6..e3958571 100644 --- a/docs/zh/guide/deploy.md +++ b/docs/zh/guide/deploy.md @@ -221,11 +221,11 @@ Cache-Control: max-age=31536000,immutable - main ``` -### Azure Static Web Apps {#azure-static-web-apps} +### Azure 静态 web 应用 {#azure-static-web-apps} -1. 遵循[官方文档](https://docs.microsoft.com/en-us/azure/static-web-apps/build-configuration)。 +1. 参考[官方文档](https://docs.microsoft.com/en-us/azure/static-web-apps/build-configuration)。 -2. 在配置文件中设置这些值（并删除不需要的值，如 `api_location`）： +2. 在配置文件中设置这些值 (并删除不需要的值，如 `api_location`)： - **`app_location`**: `/` - **`output_location`**: `docs/.vitepress/dist` @@ -272,7 +272,7 @@ Cache-Control: max-age=31536000,immutable ### Heroku -1. 遵循 [`heroku-buildpack-static`](https://elements.heroku.com/buildpacks/heroku/heroku-buildpack-static) 中给出的文档和指南。 +1. 参考 [`heroku-buildpack-static`](https://elements.heroku.com/buildpacks/heroku/heroku-buildpack-static) 中给出的文档和指南。 2. 使用以下内容在项目的根目录中创建一个名为 `static.json` 的文件： diff --git a/docs/zh/guide/extending-default-theme.md b/docs/zh/guide/extending-default-theme.md index 7e1e0258..4cffd6ba 100644 --- a/docs/zh/guide/extending-default-theme.md +++ b/docs/zh/guide/extending-default-theme.md @@ -4,7 +4,7 @@ outline: deep # 扩展默认主题 {#extending-the-default-theme} -VitePress 默认的主题已经针对文档进行了优化，并且可以进行定制。请参考[默认主题配置概览](../reference/default-theme-config)获取完整的选项列表。 +VitePress 默认的主题已经针对文档进行了优化，并且可以进行自定义。请参考[默认主题配置概览](../reference/default-theme-config)获取完整的选项列表。 但是有一些情况仅靠配置是不够的。例如： diff --git a/docs/zh/guide/frontmatter.md b/docs/zh/guide/frontmatter.md index a18ce6ba..6eb98ca5 100644 --- a/docs/zh/guide/frontmatter.md +++ b/docs/zh/guide/frontmatter.md @@ -1,4 +1,4 @@ -# frontmatter {#frontmatter} +# frontmatter ## 用法 {#usage} @@ -11,7 +11,7 @@ editLink: true --- ``` -许多站点或默认主题配置选项在 frontmatter 中都有相应的选项。你可以使用 frontmatter 来覆盖当前页面的特定行为。详细信息请参见 [frontmatter Config Reference](../reference/frontmatter-config)。 +许多站点或默认主题配置选项在 frontmatter 中都有相应的选项。你可以使用 frontmatter 来覆盖当前页面的特定行为。详细信息请参见 [frontmatter 配置参考](../reference/frontmatter-config)。 你还可以定义自己的 frontmatter 数据，以在页面上的动态 Vue 表达式中使用。 diff --git a/docs/zh/guide/ssr-compat.md b/docs/zh/guide/ssr-compat.md index 904c71e3..f91b943c 100644 --- a/docs/zh/guide/ssr-compat.md +++ b/docs/zh/guide/ssr-compat.md @@ -6,7 +6,7 @@ outline: deep 通过使用 Vue 的服务器端渲染 (SSR) 功能，VitePress 能够在生产构建期间在 Node.js 中预渲染应用程序。这意味着主题组件中的所有自定义代码都需要考虑 SSR 兼容性。 -[Vue 官方文档的 SSR 部分](https://cn.vuejs.org/guide/scaling-up/ssr.html)提供了更多有关 SSR 是什么，SSR / SSG 之间的关系以及编写 SSR 友好代码的常见注意事项等信息。原则上只在 Vue 组件的 `beforeMount` 或 `mounted` 钩子中访问 browser / DOM API。 +[Vue 官方文档的 SSR 部分](https://cn.vuejs.org/guide/scaling-up/ssr.html)提供了更多有关 SSR 是什么，SSR / SSG 之间的关系以及编写 SSR 友好代码的常见注意事项等信息。原则上只在 Vue 组件的 `beforeMount` 或 `mounted` 钩子中访问 browser / DOM API。 ## `` @@ -65,6 +65,7 @@ export default { ``` 如果你使用 TypeScript: + ```ts // .vitepress/theme/index.ts import type { Theme } from 'vitepress' @@ -80,7 +81,7 @@ export default { } satisfies Theme ``` -### `defineClientComponent` {#`defineclientcomponent`} +### `defineClientComponent` VitePress 为导入 Vue 组件提供了一个方便的辅助函数，该组件可以在导入时访问浏览器 API。 @@ -133,4 +134,4 @@ const ClientComp = defineClientComponent( ``` -The target component will only be imported in the mounted hook of the wrapper component. +目标组件将仅在 wrapper 组件的 mounted 钩子中导入。 diff --git a/docs/zh/guide/what-is-vitepress.md b/docs/zh/guide/what-is-vitepress.md index def78872..6abe1915 100644 --- a/docs/zh/guide/what-is-vitepress.md +++ b/docs/zh/guide/what-is-vitepress.md @@ -52,6 +52,6 @@ VitePress 旨在使用 Markdown 生成内容时提供出色的开发体验。 VitePress 灵感来源于 VuePress。最初的 VuePress 基于 Vue 2 和 webpack。借助 Vue 3 和 Vite，VitePress 提供了更好的开发体验、更好的生产性能、更精美的默认主题和更灵活的自定义 API。 -VitePress 和 VuePress 之间的 API 区别主要在于主题和定制。如果你使用的是带有默认主题的 VuePress 1，迁移到 VitePress 应该相对简单。 +VitePress 和 VuePress 之间的 API 区别主要在于主题和自定义。如果你使用的是带有默认主题的 VuePress 1，迁移到 VitePress 应该相对简单。 VuePress 2 也投入了精力，它也支持 Vue 3 和 Vite，与 VuePress 1 的兼容性更好。但是，并行维护两个 SSG 是难以持续的，因此 Vue 团队决定将重点放在 VitePress，作为长期的主要 SSG 选择推荐。 diff --git a/docs/zh/index.md b/docs/zh/index.md index 83c203fe..3f7c2207 100644 --- a/docs/zh/index.md +++ b/docs/zh/index.md @@ -10,8 +10,8 @@ hero: tagline: 简单、强大、快速。就是你想要的现代 SSG 框架！ actions: - theme: brand - text: 认识 VitePress - link: /zh/guide/what-is-vitepress + text: 快速开始 + link: /zh/guide/getting-started - theme: alt text: GitHub link: https://github.com/vuejs/vitepress