Skip to content
体验新版
项目
组织
正在加载...
登录
切换导航
打开侧边栏
计算机应用开发
前端
Vuepress
提交
a5624602
V
Vuepress
项目概览
计算机应用开发
/
前端
/
Vuepress
通知
2
Star
0
Fork
0
代码
文件
提交
分支
Tags
贡献者
分支图
Diff
Issue
0
列表
看板
标记
里程碑
合并请求
0
Wiki
0
Wiki
分析
仓库
DevOps
项目成员
Pages
V
Vuepress
项目概览
项目概览
详情
发布
仓库
仓库
文件
提交
分支
标签
贡献者
分支图
比较
Issue
0
Issue
0
列表
看板
标记
里程碑
合并请求
0
合并请求
0
Pages
分析
分析
仓库分析
DevOps
Wiki
0
Wiki
成员
成员
收起侧边栏
关闭侧边栏
动态
分支图
创建新Issue
提交
Issue看板
体验新版 GitCode,发现更多精彩内容 >>
提交
a5624602
编写于
4月 18, 2018
作者:
E
Evan You
浏览文件
操作
浏览文件
下载
电子邮件补丁
差异文件
docs: refine Chinese translation
上级
fefef906
变更
10
隐藏空白更改
内联
并排
Showing
10 changed file
with
53 addition
and
42 deletion
+53
-42
docs/README.md
docs/README.md
+2
-2
docs/guide/README.md
docs/guide/README.md
+3
-2
docs/guide/getting-started.md
docs/guide/getting-started.md
+4
-0
docs/zh/README.md
docs/zh/README.md
+2
-2
docs/zh/guide/README.md
docs/zh/guide/README.md
+15
-14
docs/zh/guide/basic-config.md
docs/zh/guide/basic-config.md
+4
-4
docs/zh/guide/custom-themes.md
docs/zh/guide/custom-themes.md
+4
-4
docs/zh/guide/deploy.md
docs/zh/guide/deploy.md
+1
-0
docs/zh/guide/getting-started.md
docs/zh/guide/getting-started.md
+10
-6
docs/zh/guide/using-vue.md
docs/zh/guide/using-vue.md
+8
-8
未找到文件。
docs/README.md
浏览文件 @
a5624602
...
...
@@ -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.
:::
docs/guide/README.md
浏览文件 @
a5624602
...
...
@@ -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:
...
...
docs/guide/getting-started.md
浏览文件 @
a5624602
# 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:
...
...
docs/zh/README.md
浏览文件 @
a5624602
...
...
@@ -29,6 +29,6 @@ vuepress dev .
vuepress build .
```
::: warning
NODE VERSION
请确保你
Node.js 的版本大于
8。
::: warning
注意
请确保你
的 Node.js 版本 >=
8。
:::
docs/zh/guide/README.md
浏览文件 @
a5624602
# 介绍
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 渲染的配置也不是最灵活的。
docs/zh/guide/basic-config.md
浏览文件 @
a5624602
...
...
@@ -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
// 当前应用的路由实例
})
=>
{
// ...做一些其他的应用级别的优化
}
...
...
docs/zh/guide/custom-themes.md
浏览文件 @
a5624602
# 自定义主题
::: 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`
的主题组件。
docs/zh/guide/deploy.md
浏览文件 @
a5624602
...
...
@@ -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
...
...
docs/zh/guide/getting-started.md
浏览文件 @
a5624602
# 快速上手
::: 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
...
...
docs/zh/guide/using-vue.md
浏览文件 @
a5624602
...
...
@@ -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 不怎么友好的组件(比如包含了自定义指令),你可以将他们包裹在内置的
`<ClientOnly>`
指令
中:
如果你正在使用,或者
需要展示一个对于 SSR 不怎么友好的组件(比如包含了自定义指令),你可以将它们包裹在内置的
`<ClientOnly>`
组件
中:
```
md
<ClientOnly>
...
...
@@ -12,7 +12,7 @@
</ClientOnly>
```
请注意,这并不能解决
在
**导入**
时,这些组件或者库不能访问浏览器 API 的问题 —— 为了使用上述假定的仅能运行在浏览器环境下的代码
,你需要在合适的生命周期钩子中
**动态导入**
它们:
请注意,这并不能解决
一些组件或库在
**导入**
时就试图访问浏览器 API 的问题 —— 如果需要使用这样的组件或库
,你需要在合适的生命周期钩子中
**动态导入**
它们:
```
vue
<
script
>
...
...
@@ -58,7 +58,7 @@ export default {
### 访问网站以及页面的数据
编译后的组件没有
任何的私有数据,也
可以访问
[
网站的元数据
](
./custom-themes.md#site-and-page-metadata
)
,举例来说:
编译后的组件没有
私有数据,但
可以访问
[
网站的元数据
](
./custom-themes.md#site-and-page-metadata
)
,举例来说:
**Input**
...
...
@@ -78,7 +78,7 @@ export default {
## Escaping
默认情况下,
代码块将会默认地包裹在
`v-pre`
中,如果你想要在代码块或者
文本中显示原始的大括号,或者一些 Vue 特定的语法,你需要使用自定义容器
`v-pre`
来包裹:
默认情况下,
块级 (block) 的代码块将会被自动包裹在
`v-pre`
中。如果你想要在内联 (inline) 的代码块或者普通
文本中显示原始的大括号,或者一些 Vue 特定的语法,你需要使用自定义容器
`v-pre`
来包裹:
**Input**
...
...
@@ -117,13 +117,13 @@ export default {
<OtherComponent/>
::: warning
IMPORTANT
请确保一个自定义组件的名字包含连接符或者是PascalCase,否则,它将会被视为一个内联元素,并被包裹在一个
`<p>`
标签中,这将会导致 HTML 渲染紊乱,因为 HTML 标准规定,
`<p>`
标签中不允许放置任何块级元素。
::: warning
重要!
请确保一个自定义组件的名字包含连接符或者是
PascalCase,否则,它将会被视为一个内联元素,并被包裹在一个
`<p>`
标签中,这将会导致 HTML 渲染紊乱,因为 HTML 标准规定,
`<p>`
标签中不允许放置任何块级元素。
:::
## 脚本和样式提升
有时,你可以只想在当前页面应用一些 JavaScript 或者 CSS,在这种情况下,你可以直接在 Markdown 文件中使用原生的
`<script>`
或者
`<style>`
标签,它们将会从编译后的 HTML 文件中提取出来,并
以
`<script>`
和
`<style>`
块的形式注入到生成的 Vue 单文件组件中:
有时,你可以只想在当前页面应用一些 JavaScript 或者 CSS,在这种情况下,你可以直接在 Markdown 文件中使用原生的
`<script>`
或者
`<style>`
标签,它们将会从编译后的 HTML 文件中提取出来,并
作为生成的 Vue 单文件组件的
`<script>`
和
`<style>`
标签。
<p
class=
"demo"
:class=
"$style.example"
></p>
...
...
编辑
预览
Markdown
is supported
0%
请重试
或
添加新附件
.
添加附件
取消
You are about to add
0
people
to the discussion. Proceed with caution.
先完成此消息的编辑!
取消
想要评论请
注册
或
登录