From cd8dd89a2b9f7b5fed25f7e8b4f227c477f65f5d Mon Sep 17 00:00:00 2001 From: Xavi Lee Date: Sun, 31 Dec 2023 21:50:37 +0800 Subject: [PATCH] complete `guide` --- docs/zh/guide/asset-handling.md | 12 +++--- docs/zh/guide/cms.md | 10 ++--- docs/zh/guide/custom-theme.md | 16 +++---- docs/zh/guide/data-loading.md | 10 ++--- docs/zh/guide/deploy.md | 40 +++++++++--------- docs/zh/guide/extending-default-theme.md | 12 +++--- docs/zh/guide/getting-started.md | 7 +-- docs/zh/guide/i18n.md | 16 +++---- docs/zh/guide/logo.svg | 21 --------- docs/zh/guide/migration-from-vitepress-0.md | 2 +- docs/zh/guide/routing.md | 14 +++--- docs/zh/guide/ssr-compat.md | 1 - docs/zh/guide/using-vue.md | 2 + docs/zh/guide/vitepress-init.png | Bin 18010 -> 0 bytes docs/zh/guide/what-is-vitepress.md | 6 +-- docs/zh/reference/default-theme-carbon-ads.md | 2 +- docs/zh/reference/default-theme-config.md | 4 +- docs/zh/reference/default-theme-home-page.md | 2 +- docs/zh/reference/default-theme-nav.md | 2 +- docs/zh/reference/default-theme-sidebar.md | 2 +- docs/zh/reference/frontmatter-config.md | 6 +-- docs/zh/reference/site-config.md | 8 ++-- 22 files changed, 89 insertions(+), 106 deletions(-) delete mode 100644 docs/zh/guide/logo.svg delete mode 100644 docs/zh/guide/vitepress-init.png diff --git a/docs/zh/guide/asset-handling.md b/docs/zh/guide/asset-handling.md index eff23ee2..019e6b0d 100644 --- a/docs/zh/guide/asset-handling.md +++ b/docs/zh/guide/asset-handling.md @@ -2,19 +2,19 @@ ## 引用静态资源 {#referencing-static-assets} -所有的 Markdown 文件都会被编译成 Vue 组件，并由 [Vite](https://vitejs.dev/guide/assets.html) 处理。可以，**并且应该**使用相对路径来引用任何资源： +所有的 Markdown 文件都会被编译成 Vue 组件，并由 [Vite](https://vitejs.dev/guide/assets.html) 处理。可以，**并且应该**使用相对路径来引用资源： ```md ![An image](./image.png) ``` -可以在 Markdown 文件、主题中的 `*.vue` 组件、样式和普通的 `.css` 文件中引用静态资源，通过使用绝对路径 (基于项目根目录) 或者相对路径 (基于文件系统)。后者类似于 Vite，Vue CLI，或者 webpack 的 `file-loader` 的行为。 +可以在 Markdown 文件、主题中的 `*.vue` 组件、样式和普通的 `.css` 文件中引用静态资源，通过使用绝对路径 (基于项目根目录) 或者相对路径 (基于文件系统)。后者类似于 Vite、Vue CLI 或者 webpack 的 `file-loader` 的行为。 常见的图像，媒体和字体文件会被自动检测并视作资源。 所有引用的资源，包括那些使用绝对路径的，都会在生产构建过程中被复制到输出目录，并使用哈希文件名。从未使用过的资源将不会被复制。小于 4kb 的图像资源将会采用 base64 内联——这可以通过 [`vite`](../reference/site-config#vite) 配置选项进行配置。 -所有**静态**路径引用，包括绝对路径，都应基于你的工作目录结构。 +所有**静态**路径引用，包括绝对路径，都应基于你的工作目录的结构。 ## public 目录 {#the-public-directory} @@ -24,11 +24,11 @@ 放置在 `public` 中的资源将按原样复制到输出目录的根目录中。 -请注意，应使用根绝对路径来引用放置在 `public` 中的文件 - 例如，`public/icon.png` 应始终在源代码中作为 `/icon.png` 引用。 +请注意，应使用根绝对路径来引用放置在 `public` 中的文件——例如，`public/icon.png` 应始终在源代码中作为 `/icon.png` 引用。 ## 根 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` 中的资源的绝对引用： @@ -38,7 +38,7 @@ 在这种情况下，更改 `base` 配置值时，**无需**更新该引用。 -但是如果你正在编写一个主题组件，它动态的链接到资源，例如一个图片，它的 `src` 基于主题配置值： +但是如果你正在编写一个主题组件，它动态地链接到资源，例如一个图片，它的 `src` 基于主题配置值： ```vue diff --git a/docs/zh/guide/cms.md b/docs/zh/guide/cms.md index c6d8bc0b..c23ef90b 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 token： ```js // posts/[id].paths.js @@ -21,13 +21,13 @@ outline: deep 2. 从 CMS 获取必要的数据并将其格式调整为合适的路径数据： - ```js + ```js export default { async paths() { - // 使用相应的 CMS 客户端库 (如果需要的话) + // use respective CMS client library if needed const data = await (await fetch('https://my-cms-api', { headers: { - // 如果需要 token 的话请在这里填写 + // token if necessary } })).json() diff --git a/docs/zh/guide/custom-theme.md b/docs/zh/guide/custom-theme.md index 78640cd5..12bb7c89 100644 --- a/docs/zh/guide/custom-theme.md +++ b/docs/zh/guide/custom-theme.md @@ -19,7 +19,7 @@ ## 主题接口 {#theme-interface} -VitePress 自定义主题被定义为一个对象，该对象具有如下接口： +VitePress 自定义主题是一个对象，该对象具有如下接口： ```ts interface Theme { @@ -64,7 +64,7 @@ export default { } ``` -默认导出是自定义主题的唯一方式，并且只有 `Layout` 属性是必须的。所以从技术上讲，一个 VitePress 主题可以只是一个单独的 Vue 组件。 +默认导出是自定义主题的唯一方式，并且只有 `Layout` 属性是必须的。所以从技术上讲，一个 VitePress 主题可以是一个单独的 Vue 组件。 在组件内部，它的工作方式就像是一个普通的 Vite + Vue 3 应用。请注意，主题还需要保证 [SSR 兼容](./ssr-compat)。 @@ -100,7 +100,7 @@ const { page } = useData() ``` -[`useData()`](../reference/runtime-api#usedata) 为我们提供了所有的运行时数据，以便我们根据不同条件渲染不同的布局。我们可以访问的另一个数据是当前页面的 frontmatter。通过利用这个数据，我们允许最终用户控制每个页面的布局。例如，用户可以指示一个页面是否使用特殊的主页布局： +[`useData()`](../reference/runtime-api#usedata) 为我们提供了所有的运行时数据，以便我们根据不同条件渲染不同的布局。我们可以访问的另一个数据是当前页面的 frontmatter。通过利用这个数据，我们允许用户控制每个页面的布局。例如，用户可以指定一个页面是否使用特殊的主页布局： ```md --- @@ -108,7 +108,7 @@ layout: home --- ``` -并且我们可以该信息调整我们的主题 +并且我们可以调整我们的主题进行处理： ```vue{3,12-14}