From a5624602abb930ad63d64075603cb03e35729ffd Mon Sep 17 00:00:00 2001 From: Evan You Date: Wed, 18 Apr 2018 01:01:17 -0400 Subject: [PATCH] docs: refine Chinese translation --- docs/README.md | 4 ++-- docs/guide/README.md | 5 +++-- docs/guide/getting-started.md | 4 ++++ docs/zh/README.md | 4 ++-- docs/zh/guide/README.md | 29 +++++++++++++++-------------- docs/zh/guide/basic-config.md | 8 ++++---- docs/zh/guide/custom-themes.md | 8 ++++---- docs/zh/guide/deploy.md | 1 + docs/zh/guide/getting-started.md | 16 ++++++++++------ docs/zh/guide/using-vue.md | 16 ++++++++-------- 10 files changed, 53 insertions(+), 42 deletions(-) diff --git a/docs/README.md b/docs/README.md index 016a4e8c..3cd3d750 100644 --- a/docs/README.md +++ b/docs/README.md @@ -29,6 +29,6 @@ vuepress dev vuepress build ``` -::: warning NODE VERSION -Please make sure your version of Node.js is greater than 8. +::: warning COMPATIBILITY NOTE +VuePress requires Node.js >= 8. ::: diff --git a/docs/guide/README.md b/docs/guide/README.md index 8efd2550..91a1a778 100644 --- a/docs/guide/README.md +++ b/docs/guide/README.md @@ -17,8 +17,9 @@ Each markdown file is compiled into HTML with [markdown-it](https://github.com/m - [Built-in markdown extensions](./markdown.md) optimized for technical documentation - [Ability to leverage Vue inside markdown files](./using-vue.md) - [Vue-powered custom theme system](./custom-themes.md) -- PWA Support +- Automatic Service Worker generation - Google Analytics Integration +- Multi-language support - A default theme with: - Responsive layout - Optional Homepage @@ -26,7 +27,7 @@ Each markdown file is compiled into HTML with [markdown-it](https://github.com/m - Customizable navbar and sidebar - Auto-generated GitHub link and page edit links -## Todo Features +## Todo VuePress is still a work in progress. There are a few things that it currently does not support but are planned: diff --git a/docs/guide/getting-started.md b/docs/guide/getting-started.md index 1009330e..ab48f0ad 100644 --- a/docs/guide/getting-started.md +++ b/docs/guide/getting-started.md @@ -1,5 +1,9 @@ # Getting Started +::: warning COMPATIBILITY NOTE +VuePress requires Node.js >= 8. +::: + ## Global Installation If you just want to play around with VuePress, you can install it globally: diff --git a/docs/zh/README.md b/docs/zh/README.md index f5169ad9..ac13b6ab 100644 --- a/docs/zh/README.md +++ b/docs/zh/README.md @@ -29,6 +29,6 @@ vuepress dev . vuepress build . ``` -::: warning NODE VERSION -请确保你 Node.js 的版本大于 8。 +::: warning 注意 +请确保你的 Node.js 版本 >= 8。 ::: diff --git a/docs/zh/guide/README.md b/docs/zh/guide/README.md index 404f4ca9..dbd901df 100644 --- a/docs/zh/guide/README.md +++ b/docs/zh/guide/README.md @@ -1,23 +1,24 @@ # 介绍 -VuePress 由两部分组成：一个是由 Vue 驱动的极简主题系统带来的静态网站生成器，一个是为书写技术文档而优化的默认主题，它的诞生初衷是为了助力 Vue 及其子项目书写文档的需求。 - -每一个由 VuePress 生成的页面都有自己预渲染好的 HTML，也因此带来了非常好的加载性能和搜索引擎优化（SEO）。同时，一旦页面被加载，Vue 将接管这些静态内容，并将其转换成一个完整的单页应用（SPA），其他的页面都将在用户浏览到的时候按需加载。 +VuePress 由两部分组成：一部分是支持用 Vue 开发主题的极简静态网站生成器，另一个部分是为书写技术文档而优化的默认主题。它的诞生初衷是为了支持 Vue 及其子项目的文档需求。 + +每一个由 VuePress 生成的页面都带有预渲染好的 HTML，也因此具有非常好的加载性能和搜索引擎优化（SEO）。同时，一旦页面被加载，Vue 将接管这些静态内容，并将其转换成一个完整的单页应用（SPA），其他的页面则会只在用户浏览到的时候才按需加载。 ## 它是如何工作的？ -事实上，一个 VuePress 网站是一个由 [Vue](http://vuejs.org/)、[Vue Router](https://github.com/vuejs/vue-router) 和 [Webpack](http://webpack.js.org/) 驱动的单页应用。如果你以前使用过 Vue 的话，当你在开发一个自定义主题的时候，你将会回到曾经那非常熟悉的开发体验，你甚至可以使用 Vue DevTools 去调试你的自定义主题。 +事实上，一个 VuePress 网站是一个由 [Vue](http://vuejs.org/)、[Vue Router](https://github.com/vuejs/vue-router) 和 [webpack](http://webpack.js.org/) 驱动的单页应用。如果你以前使用过 Vue 的话，当你在开发一个自定义主题的时候，你会感受到非常熟悉的开发体验，你甚至可以使用 Vue DevTools 去调试你的自定义主题。 -在构建过程中，我们创建了一个服务端渲染（SSR）版本的应用，同时在访问每一个路由的时候会渲染对应的HTML，这种做法的灵感来源于 [Nuxt](https://nuxtjs.org/) 的 `nuxt generate` 命令，以及其他的一些项目，如 [Gatsby](https://www.gatsbyjs.org/)。 +在构建时，我们会为应用创建一个服务端渲染（SSR）的版本，然后通过虚拟访问每一条路径来渲染对应的HTML。这种做法的灵感来源于 [Nuxt](https://nuxtjs.org/) 的 `nuxt generate` 命令，以及其他的一些项目，比如 [Gatsby](https://www.gatsbyjs.org/)。 ## 特性 -- [内置的 Markdown 拓展](./markdown.md)，为技术文档而生 -- [在 Markdown 文件使用 Vue 组件的能力](./using-vue.md) +- 为技术文档而优化的 [内置 Markdown 拓展](./markdown.md) +- [在 Markdown 文件中使用 Vue 组件的能力](./using-vue.md) - [Vue 驱动的自定义主题系统](./custom-themes.md) -- 支持 PWA -- 集成了 Google Analytics -- 一个默认的主题包含： +- 自动生成 Service Worker +- Google Analytics 集成 +- 多语言支持 +- 默认主题包含： - 响应式布局 - 可选的主页 - 简洁的开箱即用的标题搜索 @@ -31,19 +32,19 @@ VuePress 仍然处于开发中，这里有一些目前还不支持、但已经 - Algolia DocSearch 的集成 - 博客系统 -欢迎你的 Contribution！ +我们欢迎你为 VuePress 的开发作出贡献。 ## 为什么不是...? ### Nuxt -VuePress 能做的事情，Nuxt 同样能胜任，但 Nuxt 是为构建应用程序而生的，而 VuePress 则专注在以内容为中心的静态网站上，同时提供了一些为技术文档定制的开箱即用的特性。 +VuePress 能做的事情，Nuxt 理论上确实能够胜任，但 Nuxt 是为构建应用程序而生的，而 VuePress 则专注在以内容为中心的静态网站上，同时提供了一些为技术文档定制的开箱即用的特性。 ### Docsify / Docute -这两个项目同样都是 Vue 驱动的，然而它们都是完全的运行时驱动，因此对 SEO 不够友好。如果你并不关注 SEO，同时也不想因为安装依赖而弄糊涂，它们仍然是非常好的选择！ +这两个项目同样都是基于 Vue，然而它们都是完全的运行时驱动，因此对 SEO 不够友好。如果你并不关注 SEO，同时也不想安装大量依赖，它们仍然是非常好的选择！ ### Hexo -Hexo 一直驱动着 Vue 的文档 —— 事实上，在决定开始从 Hexo 迁移到 VuePress 之前，我们还有很长的路要走。Hexo 最大的问题在于他的主题系统太过于静态以及过度地依赖纯字符串，而我们十分希望能够好好地利用 Vue 来处理我们的布局和交互，同时，Hexo 的 Markdown 渲染的配置也不是最灵活的。 +Hexo 一直驱动着 Vue 的文档 —— 事实上，在把我们的主站从 Hexo 迁移到 VuePress 之前，我们可能还有很长的路要走。Hexo 最大的问题在于他的主题系统太过于静态以及过度地依赖纯字符串，而我们十分希望能够好好地利用 Vue 来处理我们的布局和交互，同时，Hexo 的 Markdown 渲染的配置也不是最灵活的。 diff --git a/docs/zh/guide/basic-config.md b/docs/zh/guide/basic-config.md index c9247f56..fde161b9 100644 --- a/docs/zh/guide/basic-config.md +++ b/docs/zh/guide/basic-config.md @@ -15,7 +15,7 @@ module.exports = { 对于上述的配置，如果你运行起 dev server，你应该能看到一个页面，它包含一个页头，里面包含一个标题和一个搜索框。VuePress 内置了基于 headers 的搜索 —— 它会自动为所有页面的标题、`h2` 和 `h3` 构建起一个简单的搜索索引。 -参见 [配置](../config/) 来查看所有可配置的选项。 +参见 [配置](../config/) 来查看所有可配置的选项。 ## 主题配置 @@ -25,15 +25,15 @@ module.exports = { 如果你想开发一个自定义主题，可以参考 [自定义主题](./custom-themes.md)。 -## 应用级别的优化 +## 应用级别的配置 -由于 VuePress 是一个标准的 Vue 应用，你可以通过创建一个 `.vuepress/enhanceApp.js` 文件来做一些应用级别的优化，当该文件存在的时候，会被导入到应用内部。`enhanceApp.js` 应该 `export default` 一个钩子函数，并接受一个包含了一些应用级别属性的对象作为参数。你可以使用这个钩子来安装一些附加的 Vue 插件、注册全局组件，或者增加额外的路由钩子等： +由于 VuePress 是一个标准的 Vue 应用，你可以通过创建一个 `.vuepress/enhanceApp.js` 文件来做一些应用级别的配置，当该文件存在的时候，会被导入到应用内部。`enhanceApp.js` 应该 `export default` 一个钩子函数，并接受一个包含了一些应用级别属性的对象作为参数。你可以使用这个钩子来安装一些附加的 Vue 插件、注册全局组件，或者增加额外的路由钩子等： ```js export default ({ Vue, // VuePress 正在使用的 Vue 构造函数 options, // 附加到根实例的一些选项 - router // 当前应用的路由实例 + router // 当前应用的路由实例 }) => { // ...做一些其他的应用级别的优化 } diff --git a/docs/zh/guide/custom-themes.md b/docs/zh/guide/custom-themes.md index 4939e78b..d74ea394 100644 --- a/docs/zh/guide/custom-themes.md +++ b/docs/zh/guide/custom-themes.md @@ -1,6 +1,6 @@ # 自定义主题 -::: tip +::: tip 提示 主题组件受到同样的 [浏览器的 API 访问限制](./using-vue.md#browser-api-access-restrictions)。 ::: @@ -13,7 +13,7 @@ VuePress 使用单文件组件来构建自定义主题。想要开发一个自    └─ Layout.vue ``` -从这里开始，就和开发一个平时的 Vue 应用一样了，这完全取决于你如何组织你的主题。 +从这里开始，就和开发一个平时的 Vue 应用一样了，如何组织你的主题完全取决于你。 ## 网站和页面的元数据 @@ -44,7 +44,7 @@ VuePress 使用单文件组件来构建自定义主题。想要开发一个自 ``` json { "path": "/custom-themes.html", - "title": "Custom Themes", + "title": "自定义主题", "headers": [/* ... */], "frontmatter": {} } @@ -79,4 +79,4 @@ module.exports = { ``` VuePress 将会尝试去加载并使用位于 `node_modules/vuepress-theme-awesome/Layout.vue` 的主题组件。 - + diff --git a/docs/zh/guide/deploy.md b/docs/zh/guide/deploy.md index bca25abb..f481d3c8 100644 --- a/docs/zh/guide/deploy.md +++ b/docs/zh/guide/deploy.md @@ -5,6 +5,7 @@ ## GitHub Pages 1. 将 `.vuepress/config.js` 的 `base` 设置成你仓库的名字，举个例子，如果你的仓库是 `https://github.com/foo/bar`, 部署的页面将会通过 `https://foo.github.io/bar` 来访问，此时，你应该将 `base` 设置为 `"/bar/"`。 + 2. 在你的项目中运行: ``` bash diff --git a/docs/zh/guide/getting-started.md b/docs/zh/guide/getting-started.md index 32425530..bbbf2b70 100644 --- a/docs/zh/guide/getting-started.md +++ b/docs/zh/guide/getting-started.md @@ -1,8 +1,12 @@ # 快速上手 +::: warning 注意 +请确保你的 Node.js 版本 >= 8。 +::: + ## 全局安装 -如果你只是想玩一玩 VuePress，你可以全局安装它： +如果你只是想尝试一下 VuePress，你可以全局安装它： ``` bash # 安装 @@ -20,7 +24,7 @@ vuepress build . ## 现有项目 -如果你想在一个现有项目中使用 VuePress，同时想要在该项目中保存文档，此时你应该将 VuePress 作为本地依赖。下述的安装流程，你同样可以使用持续集成工具，或者一些开源服务，如 Netlify，来帮助你在每次更新代码时自动部署。 +如果你想在一个现有项目中使用 VuePress，同时想要在该项目中管理文档，则应该将 VuePress 安装为本地依赖。作为本地依赖安装让你可以使用持续集成工具，或者一些其他服务（比如 Netlify）来帮助你在每次提交代码时自动部署。 ``` bash # 将 VuePress 作为一个本地依赖安装 @@ -37,10 +41,10 @@ npx vuepress dev docs ``` ::: warning -当你想要将 VuePress 安装到一个现存的项目中，并且这个项目已经有了 webpack 3.x 作为依赖时，推荐使用 [Yarn](https://yarnpkg.com/en/) 而不是 npm，因为在这种情形下，npm 会生成错误的依赖树。 +如果你的现有项目依赖了 webpack 3.x，推荐使用 [Yarn](https://yarnpkg.com/en/) 而不是 npm 来安装 VuePress。因为在这种情形下，npm 会生成错误的依赖树。 ::: -接着，你可以在 `package.json` 加一些脚本: +接着，在 `package.json` 里加一些脚本: ``` json { @@ -51,13 +55,13 @@ npx vuepress dev docs } ``` -于是，你就可以这样开始你的写作了: +然后就可以开始写作了: ``` bash yarn docs:dev # 或者：npm run docs:dev ``` -要生成静态资源时，运行： +要生成静态的 HTML 文件，运行： ``` bash yarn docs:build # 或者：npm run docs:build diff --git a/docs/zh/guide/using-vue.md b/docs/zh/guide/using-vue.md index d2a8facd..107213c6 100644 --- a/docs/zh/guide/using-vue.md +++ b/docs/zh/guide/using-vue.md @@ -2,9 +2,9 @@ ## 浏览器的 API 访问限制 -当你在开发一个 VuePress 应用时，由于所有的页面都是通过 Node.js 服务端渲染的，因此任意的 Vue 使用都应当遵循 [编写通用代码](https://ssr.vuejs.org/zh/universal.html) 的要求。简而言之，请确保只在 `beforeMounted` 或者 `mounted` 访问浏览器 / DOM 的 API。 +当你在开发一个 VuePress 应用时，由于所有的页面在生成静态 HTML 时都需要通过 Node.js 服务端渲染，因此所有的 Vue 相关代码都应当遵循 [编写通用代码](https://ssr.vuejs.org/zh/universal.html) 的要求。简而言之，请确保只在 `beforeMounted` 或者 `mounted` 访问浏览器 / DOM 的 API。 -如果你正在使用，或者测试一个对于 SSR 不怎么友好的组件（比如包含了自定义指令），你可以将他们包裹在内置的 `` 指令中： +如果你正在使用，或者需要展示一个对于 SSR 不怎么友好的组件（比如包含了自定义指令），你可以将它们包裹在内置的 `` 组件中： ``` md @@ -12,7 +12,7 @@ ``` -请注意，这并不能解决在**导入**时，这些组件或者库不能访问浏览器 API 的问题 —— 为了使用上述假定的仅能运行在浏览器环境下的代码，你需要在合适的生命周期钩子中**动态导入**它们： +请注意，这并不能解决一些组件或库在**导入**时就试图访问浏览器 API 的问题 —— 如果需要使用这样的组件或库，你需要在合适的生命周期钩子中**动态导入**它们： ``` vue