VuePress中文-英文文档

1 .

2 . 目 录 致谢 README 中文文档 README 介绍 快速上手 基本配置 静态资源 Markdown 拓展 在 Markdown 中 使用 Vue 自定义主题 多语言支持 部署 默认主题 配置 英文文档 README Introduction Getting Started Configuration Asset Handling Markdown Extensions Using Vue in Markdown Custom Themes Internationalization Deploying Default Theme Config Config Reference 升级日志 本文档使用 书栈(BookStack.CN) 构建 - 2 - 

3 .致谢 致谢 当前文档 《VuePress 中文&英文文档》 由 进击的皇虫 使用 书栈(BookStack.CN) 进行构建，生成于 2018-07-15。 书栈(BookStack.CN) 仅提供文档编写、整理、归类等功能，以及对文档内容的生成和导出工具。 文档内容由网友们编写和整理，书栈(BookStack.CN) 难以确认文档内容知识点是否错漏。如果您在阅读文档 获取知识的时候，发现文档内容有不恰当的地方，请向我们反馈，让我们共同携手，将知识准确、高效且有效地传递 给每一个人。 同时，如果您在日常工作、生活和学习中遇到有价值有营养的知识文档，欢迎分享到 书栈(BookStack.CN) ， 为知识的传承献上您的一份力量！ 如果当前文档生成时间太久，请到 书栈(BookStack.CN) 获取最新的文档，以跟上知识更新换代的步伐。 文档地址：http://www.bookstack.cn/books/VuePress-docs 书栈官网：http://www.bookstack.cn 书栈开源：https://github.com/TruthHun 分享，让知识传承更久远！ 感谢知识的创造者，感谢知识的分享者，也感谢每一位阅读到此处的读者，因为我们 都将成为知识的传承者。 本文档使用 书栈(BookStack.CN) 构建 - 3 - 

4 .README README downloads 17k/month npm v0.12.0 license MIT VuePress Minimalistic docs generator with Vue component based layout system https://vuepress.vuejs.org/ Features Built-in markdown extensions Table of Contents Custom Containers Line Highlighting Line Numbers Import Code Snippets Using Vue in Markdown Templating Using Components 本文档使用 书栈(BookStack.CN) 构建 - 4 - 

5 .README Vue-powered custom theme system Metadata Content Excerpt Default theme Responsive layout Optional Homepage Simple out-of-the-box header-based search Algolia Search Customizable navbar and sidebar Auto-generated GitHub link and page edit links Miscellaneous Multi-Language Support Service Worker Google Analytics Last Updated Showcase Websites built with VuePress: Vue Ecosystem vue-cli vuex vue-server-renderer vue-router vue-test-utils vue-loader vetur rollup-plugin-vue Community cr-vue vuesax Todo Features VuePress is still a work in progress. There are a few things that it currently does not support but are planned: Plugin support Blogging support 本文档使用 书栈(BookStack.CN) 构建 - 5 - 

6 .README Contributions are welcome! Development Please make sure your version of Node.js is greater than 8. 1. yarn 2. yarn dev # serves VuePress' own docs with itself 3. yarn test # make sure your code change pass the test License MIT 来源(书栈小编注) https://github.com/vuejs/vuepress 本文档使用 书栈(BookStack.CN) 构建 - 6 - 

7 .中文文档 中文文档 README 介绍 快速上手 基本配置 静态资源 Markdown 拓展 在 Markdown 中 使用 Vue 自定义主题 多语言支持 部署 默认主题 配置 本文档使用 书栈(BookStack.CN) 构建 - 7 - 

8 .README README 简洁至上 以 Markdown 为中心的项目结构，以最少的配置帮助你专注于写作。 Vue驱动 享受 Vue + webpack 的开发体验，可以在 Markdown 中使用 Vue 组件，又可以使用 Vue 来开发自定义主 题。 高性能 details: VuePress 会为每个页面预渲染生成静态的 HTML，同时，每个页面被加载的时候，将作为 SPA 运行。 像数 1, 2, 3 一样容易 1. # 安装 2. yarn global add vuepress # 或者：npm install -g vuepress 3. 4. # 新建一个 markdown 文件 5. echo '# Hello VuePress!' > README.md 6. 7. # 开始写作 8. vuepress dev . 9. 10. # 构建静态文件 11. vuepress build . ::: warning 注意 请确保你的 Node.js 版本 >= 8。 ::: 本文档使用 书栈(BookStack.CN) 构建 - 8 - 

9 .介绍 介绍 介绍 VuePress 由两部分组成：一部分是支持用 Vue 开发主题的极简静态网站生成器，另一个部分是为书写技术文档而 优化的默认主题。它的诞生初衷是为了支持 Vue 及其子项目的文档需求。 每一个由 VuePress 生成的页面都带有预渲染好的 HTML，也因此具有非常好的加载性能和搜索引擎优化（SEO）。 同时，一旦页面被加载，Vue 将接管这些静态内容，并将其转换成一个完整的单页应用（SPA），其他的页面则会只 在用户浏览到的时候才按需加载。 它是如何工作的？ 事实上，一个 VuePress 网站是一个由 Vue、Vue Router 和 webpack 驱动的单页应用。如果你以前使用过 Vue 的话，当你在开发一个自定义主题的时候，你会感受到非常熟悉的开发体验，你甚至可以使用 Vue DevTools 去调试你的自定义主题。 在构建时，我们会为应用创建一个服务端渲染（SSR）的版本，然后通过虚拟访问每一条路径来渲染对应的HTML。这 种做法的灵感来源于 Nuxt 的 nuxt generate 命令，以及其他的一些项目，比如 Gatsby。 特性 为技术文档而优化的 内置 Markdown 拓展 在 Markdown 文件中使用 Vue 组件的能力 Vue 驱动的自定义主题系统 自动生成 Service Worker Google Analytics 集成 基于 Git 的 “最后更新时间” 多语言支持 默认主题包含： 响应式布局 可选的主页 简洁的开箱即用的标题搜索 Algolia 搜索 可自定义的导航栏 和侧边栏 自动生成的 GitHub 链接和页面的编辑链接 Todo VuePress 仍然处于开发中，这里有一些目前还不支持、但已经在计划中的特性： 插件 博客系统 本文档使用 书栈(BookStack.CN) 构建 - 9 - 

10 .介绍 我们欢迎你为 VuePress 的开发作出贡献。 为什么不是…? Nuxt VuePress 能做的事情，Nuxt 理论上确实能够胜任，但 Nuxt 是为构建应用程序而生的，而 VuePress 则专注 在以内容为中心的静态网站上，同时提供了一些为技术文档定制的开箱即用的特性。 Docsify / Docute 这两个项目同样都是基于 Vue，然而它们都是完全的运行时驱动，因此对 SEO 不够友好。如果你并不关注 SEO，同 时也不想安装大量依赖，它们仍然是非常好的选择！ Hexo Hexo 一直驱动着 Vue 的文档 —— 事实上，在把我们的主站从 Hexo 迁移到 VuePress 之前，我们可能还有很 长的路要走。Hexo 最大的问题在于他的主题系统太过于静态以及过度地依赖纯字符串，而我们十分希望能够好好地 利用 Vue 来处理我们的布局和交互，同时，Hexo 的 Markdown 渲染的配置也不是最灵活的。 GitBook 我们的子项目文档一直都在使用 GitBook。GitBook 最大的问题在于当文件很多时，每次编辑后的重新加载时间长 得令人无法忍受。它的默认主题导航结构也比较有限制性，并且，主题系统也不是 Vue 驱动的。GitBook 背后的团 队如今也更专注于将其打造为一个商业产品而不是开源工具。 本文档使用 书栈(BookStack.CN) 构建 - 10 - 

11 .快速上手 快速上手 快速上手 ::: warning 注意 请确保你的 Node.js 版本 >= 8。 ::: 全局安装 如果你只是想尝试一下 VuePress，你可以全局安装它： 1. # 安装 2. yarn global add vuepress # 或者：npm install -g vuepress 3. 4. # 新建一个 markdown 文件 5. echo "# Hello VuePress!" > README.md 6. 7. # 开始写作 8. vuepress dev . 9. 10. # 构建静态文件 11. vuepress build . 现有项目 如果你想在一个现有项目中使用 VuePress，同时想要在该项目中管理文档，则应该将 VuePress 安装为本地依 赖。作为本地依赖安装让你可以使用持续集成工具，或者一些其他服务（比如 Netlify）来帮助你在每次提交代码时 自动部署。 1. # 将 VuePress 作为一个本地依赖安装 2. yarn add -D vuepress # 或者：npm install -D vuepress 3. 4. # 新建一个 docs 文件夹 5. mkdir docs 6. 7. # 新建一个 markdown 文件 8. echo "# Hello VuePress!" > docs/README.md 9. 10. # 开始写作 11. npx vuepress dev docs ::: warning 如果你的现有项目依赖了 webpack 3.x，推荐使用 Yarn 而不是 npm 来安装 VuePress。因为在这种情形下， 本文档使用 书栈(BookStack.CN) 构建 - 11 - 

12 .快速上手 npm 会生成错误的依赖树。 ::: 接着，在 package.json 里加一些脚本: 1. { 2. "scripts": { 3. "docs:dev": "vuepress dev docs", 4. "docs:build": "vuepress build docs" 5. } 6. } 然后就可以开始写作了: 1. yarn docs:dev # 或者：npm run docs:dev 要生成静态的 HTML 文件，运行： 1. yarn docs:build # 或者：npm run docs:build 默认情况下，文件将会被生成在 .vuepress/dist ，当然，你也可以通过 .vuepress/config.js 中的 dest 字 段来修改，生成的文件可以部署到任意的静态文件服务器上，参考 部署 来了解更多。 本文档使用 书栈(BookStack.CN) 构建 - 12 - 

13 .基本配置 基本配置 基本配置 配置文件 如果没有任何配置，这个网站将会是非常局限的，用户也无法在你的网站上自由导航。为了更好地自定义你的网站， 让我们首先在你的文档目录下创建一个 .vuepress 目录，所有 VuePress 相关的文件都将会被放在这里。你的项 目结构可能是这样： 1. . 2. ├─ docs 3. │ ├─ README.md 4. │ └─ .vuepress 5. │ └─ config.js 6. └─ package.json 一个 VuePress 网站必要的配置文件是 .vuepress/config.js ，它应该导出一个 JavaScript 对象： 1. module.exports = { 2. title: 'Hello VuePress', 3. description: 'Just playing around' 4. } 对于上述的配置，如果你运行起 dev server，你应该能看到一个页面，它包含一个页头，里面包含一个标题和一个 搜索框。VuePress 内置了基于 headers 的搜索 —— 它会自动为所有页面的标题、 h2 和 h3 构建起一个 简单的搜索索引。 参见 配置 来查看所有可配置的选项。 ::: tip 其他配置格式 你也可以使用 YAML ( .vuepress/config.yml ) 或是 TOML ( .vuepress/config.toml ) 格式的配置文件。 ::: 主题配置 一个 VuePress 主题应该负责整个网站的布局和交互细节。在 VuePress 中，目前自带了一个默认的主题（正是 你现在所看到的），它是为技术文档而设计的。同时，默认主题提供了一些选项，让你可以去自定义导航栏 （navbar）、 侧边栏（sidebar）和 首页（homepage） 等，详情请参见 默认主题 。 如果你想开发一个自定义主题，可以参考 自定义主题。 应用级别的配置 本文档使用 书栈(BookStack.CN) 构建 - 13 - 

14 .基本配置 由于 VuePress 是一个标准的 Vue 应用，你可以通过创建一个 .vuepress/enhanceApp.js 文件来做一些应用级别 的配置，当该文件存在的时候，会被导入到应用内部。 enhanceApp.js 应该 export default 一个钩子函数，并接 受一个包含了一些应用级别属性的对象作为参数。你可以使用这个钩子来安装一些附加的 Vue 插件、注册全局组 件，或者增加额外的路由钩子等： 1. export default ({ 2. Vue, // VuePress 正在使用的 Vue 构造函数 3. options, // 附加到根实例的一些选项 4. router, // 当前应用的路由实例 5. siteData // 站点元数据 6. }) => { 7. // ...做一些其他的应用级别的优化 8. } 本文档使用 书栈(BookStack.CN) 构建 - 14 - 

15 .静态资源 静态资源 静态资源 相对路径 所有的 Markdown 文件都会被 webpack 编译成 Vue 组件，因此你可以，并且应该更倾向于使用相对路径 （Relative URLs）来引用所有的静态资源： 1.  同样地，这在 *.vue 文件的模板中一样可以工作，图片将会被 url-loader 和 file-loader 处理，在运行 生成静态文件的构建任务时，文件会被复制到正确的位置。 除此之外，你也使用 ~ 前缀来明确地指出这是一个 webpack 的模块请求，这将允许你通过 webpack 别名来 引用文件或者 npm 的依赖： 1.  2.  Webpack 的别名可以通过 .vuepress/config.js 中 configureWebpack 来配置，如： 1. module.exports = { 2. configureWebpack: { 3. resolve: { 4. alias: { 5. '@alias': 'path/to/some/dir' 6. } 7. } 8. } 9. } 公共文件 有时，你可能需要提供一个静态资源，但是它们并不直接被你的任何一个 markdown 文件或者主题组件引用 —— 举 例来说，favicons 和 PWA 的图标，在这种情形下，你可以将它们放在 .vuepress/public 中， 它们最终会被复 制到生成的静态文件夹中。 基础路径 如果你的网站会被部署到一个非根路径，你将需要在 .vuepress/config.js 中设置 base ，举例来说，如果你打 算将你的网站部署到 https://foo.github.io/bar/ ，那么 base 的值就应该被设置为 "/bar/" (应当总是以斜 本文档使用 书栈(BookStack.CN) 构建 - 15 - 

16 .静态资源 杠开始，并以斜杠结束)。 有了基础路径（Base URL），如果你希望引用一张放在 .vuepress/public 中的图片，你需要使用这样路 径： /bar/image.png ，然而，一旦某一天你决定去修改 base ，这样的路径引用将会显得异常脆弱。为了解决这个 问题，VuePress 提供了内置的一个 helper $withBase （它被注入到了 Vue 的原型上），可以帮助你生成正确 的路径： 1. <img :src="$withBase('/foo.png')" alt="foo"> 值得一提的是，你不仅可以在你的 Vue 组件中使用上述的语法，在 Markdown 文件中亦是如此。 最后补充一句，一个 base 路径一旦被设置，它将会自动地作为前缀插入到 .vuepress/config.js 中所有以 / 开始的资源路径中。 本文档使用 书栈(BookStack.CN) 构建 - 16 - 

17 .Markdown 拓展 Markdown 拓展 Markdown 拓展 Header Anchors 所有的标题将会自动地应用 anchor 链接，anchor 的渲染可以通过 markdown.anchor 来配置。 链接 内部链接 内部的、并以 .md or .html 结尾的链接，将会被转换成 <router-link> 用于 SPA 导航。 站内的每一个子文件夹都应当有一个 README.md 文件，它会被自动编译为 index.html 。 ::: tip 在链接到一个文件夹的 index.html 时，确保你的链接以 / 结尾，否则该链接将导致 404。比如，用 /config/ 而不是 /config 。 ::: 如果你想要链接到另一个 markdown 文件： 1. 确保链接以 .html 或 .md 结尾； 2. 确保路径大小写正确，因为路径的匹配是大小写敏感的。 示例 以如下的文件结构为例： 1. . 2. ├─ README.md 3. ├─ foo 4. │ ├─ README.md 5. │ ├─ one.md 6. │ └─ two.md 7. └─ bar 8. ├─ README.md 9. ├─ three.md 10. └─ four.md 1. [Home](/) <!-- 跳转到根部的 README.md --> 2. [foo](/foo/) <!-- 跳转到 foo 文件夹的 index.html --> 3. [foo heading anchor](/foo/#heading) <!-- 跳转到 foo/index.html 的特定 anchor 位置 --> 本文档使用 书栈(BookStack.CN) 构建 - 17 - 

18 .Markdown 拓展 4. [foo - one](/foo/one.html) <!-- 具体文件可以使用 .html 结尾 --> 5. [foo - two](/foo/two.md) <!-- 也可以用 .md --> 外部链接 外部的链接将会被自动地设置为 target="_blank" rel="noopener noreferrer" : vuejs.org VuePress on GitHub 你可以自定义通过配置 config.markdown.externalLinks 来自定义外部链接的特性。 Front Matter VuePress 提供了对 YAML front matter 开箱即用的支持: 1. --- 2. title: Blogging Like a Hacker 3. lang: en-US 4. --- 这些数据可以在当前页的正文中使用，在任意的自定义或主题组件中，它可以通过 $page 来访问。 title 和 lang 的 meta 将会被自动地注入到当前的页面中，当然你也可以指定一些额外需要注入的 meta： 1. --- 2. meta: 3. - name: description 4. content: hello 5. - name: keywords 6. content: super duper SEO 7. --- 其他格式的 Front Matter 除了 YAML 之外，VuePress 也支持 JSON 或者 TOML 格式的 front matter。 JSON front matter 需要以花括号开头和结尾： 1. --- 2. { 3. "title": "Blogging Like a Hacker", 4. "lang": "en-US" 5. } 6. --- TOML front matter 需要显式地标注为 TOML： 本文档使用 书栈(BookStack.CN) 构建 - 18 - 

19 .Markdown 拓展 1. ---toml 2. title = "Blogging Like a Hacker" 3. lang = "en-US" 4. --- GitHub 风格的表格 Input 1. | Tables | Are | Cool | 2. | ------------- |:-------------:| -----:| 3. | col 3 is | right-aligned | $1600 | 4. | col 2 is | centered | $12 | 5. | zebra stripes | are neat | $1 | Output Tables Are Cool col 3 is right-aligned $1600 col 2 is centered $12 zebra stripes are neat $1 Emoji Input 1. :tada: :100: Output 目录 Input 1. [[toc]] Output [[toc]] 目录（Table of Contents）的渲染可以通过 markdown.toc 选项来配置。 本文档使用 书栈(BookStack.CN) 构建 - 19 - 

20 .Markdown 拓展 自定义容器 Input 1. ::: tip 2. This is a tip 3. ::: 4. 5. ::: warning 6. This is a warning 7. ::: 8. 9. ::: danger 10. This is a dangerous warning 11. ::: Output ::: tip This is a tip ::: ::: warning This is a warning ::: ::: danger This is a dangerous thing ::: 你也可以自定义块中的标题： 1. ::: danger STOP 2. Danger zone, do not proceed 3. ::: ::: danger STOP Danger zone, do not proceed ::: 代码块中的行高亮 Input 1. ``` js{4} 2. export default { 3. data () { 4. return { 本文档使用 书栈(BookStack.CN) 构建 - 20 - 

21 .Markdown 拓展 5. msg: 'Highlighted!' 6. } 7. } 8. } 9. ``` Output 1. export default { 2. data () { 3. return { 4. msg: 'Highlighted!' 5. } 6. } 7. } 行号 你可以通过配置来为每个代码块显示行号： 1. module.exports = { 2. markdown: { 3. lineNumbers: true 4. } 5. } 示例: " class="reference-link">导入代码段 你可以通过下述的语法导入已经存在的文件中的代码段： 1. <<< @/filepath 它也支持 行高亮： 1. <<< @/filepath{highlightLines} Input 本文档使用 书栈(BookStack.CN) 构建 - 21 - 

22 .Markdown 拓展 1. <<< @/test/markdown/fragments/snippet.js{2} Output <<< @/test/markdown/fragments/snippet.js{2} ::: tip 注意 由于代码段的导入将在 webpack 编译之前执行，因此你无法使用 webpack 中的路径别名，此处的 @ 默认值 是 process.cwd() 。 ::: 进阶配置 VuePress 使用 markdown-it 来渲染 Markdown，上述大多数的拓展也都是通过自定义的插件实现的。想要进一 步的话，你可以通过 .vuepress/config.js 的 markdown 选项，来对当前的 markdown-it 实例做一些自定义 的配置： 1. module.exports = { 2. markdown: { 3. // markdown-it-anchor 的选项 4. anchor: { permalink: false }, 5. // markdown-it-toc 的选项 6. toc: { includeLevel: [1, 2] }, 7. config: md => { 8. // 使用更多的 markdown-it 插件! 9. md.use(require('markdown-it-xxx')) 10. } 11. } 12. } 本文档使用 书栈(BookStack.CN) 构建 - 22 - 

23 .在 Markdown 中 使用 Vue 在 Markdown 中 使用 Vue 在 Markdown 中 使用 Vue 浏览器的 API 访问限制 当你在开发一个 VuePress 应用时，由于所有的页面在生成静态 HTML 时都需要通过 Node.js 服务端渲染，因 此所有的 Vue 相关代码都应当遵循 编写通用代码 的要求。简而言之，请确保只在 beforeMount 或者 mounted 访问浏览器 / DOM 的 API。 如果你正在使用，或者需要展示一个对于 SSR 不怎么友好的组件（比如包含了自定义指令），你可以将它们包裹在 内置的 <ClientOnly> 组件中： 1. <ClientOnly> 2. <NonSSRFriendlyComponent/> 3. </ClientOnly> 请注意，这并不能解决一些组件或库在导入时就试图访问浏览器 API 的问题 —— 如果需要使用这样的组件或库，你 需要在合适的生命周期钩子中动态导入它们： 1. <script> 2. export default { 3. mounted () { 4. import('./lib-that-access-window-on-import').then(module => { 5. // use code 6. }) 7. } 8. } 9. </script> 模板语法 插值 每一个 Markdown 文件将首先被编译成 HTML，接着作为一个 Vue 组件传入 vue-loader ，这意味着你可以在文 本中使用 Vue 风格的插值： Input 1. {{ 1 + 1 }} Output 本文档使用 书栈(BookStack.CN) 构建 - 23 - 

24 .在 Markdown 中 使用 Vue 1. {{ 1 + 1 }} 指令 同样地，也可以使用指令: Input 1. <span v-for="i in 3">{{ i }} </span> Output 1. {{ i }} 访问网站以及页面的数据 编译后的组件没有私有数据，但可以访问 网站的元数据，举例来说： Input 1. {{ $page }} Output 1. { 2. "path": "/using-vue.html", 3. "title": "Using Vue in Markdown", 4. "frontmatter": {} 5. } Escaping 默认情况下，块级 (block) 的代码块将会被自动包裹在 v-pre 中。如果你想要在内联 (inline) 的代码块或 者普通文本中显示原始的大括号，或者一些 Vue 特定的语法，你需要使用自定义容器 v-pre 来包裹： Input 1. ::: v-pre 2. `{{ This will be displayed as-is }}` 3. ::: Output ::: v-pre {{ This will be displayed as-is }} ::: 本文档使用 书栈(BookStack.CN) 构建 - 24 - 

25 .在 Markdown 中 使用 Vue 使用组件 所有在 .vuepress/components 中找到的 *.vue 文件将会自动地被注册为全局的异步组件，如： 1. . 2. └─ .vuepress 3. └─ components 4. ├─ demo-1.vue 5. ├─ OtherComponent.vue 6. └─ Foo 7. └─ Bar.vue 你可以直接使用这些组件在任意的 Markdown 文件中（组件名是通过文件名取到的）： 1. <demo-1/> 2. <OtherComponent/> 3. <Foo-Bar/> ::: warning 重要！ 请确保一个自定义组件的名字包含连接符或者是 PascalCase，否则，它将会被视为一个内联元素，并被包裹在一个 <p> 标签中，这将会导致 HTML 渲染紊乱，因为 HTML 标准规定， <p> 标签中不允许放置任何块级元素。 ::: 使用预处理器 VuePress 对以下预处理器已经内置相关的 webpack 配置： sass 、 scss 、 less 、 stylus 和 pug 。 要使用它们你只需要在项目中安装对应的依赖即可。例如，要使用 sass ，需要安装： 1. yarn add -D sass-loader node-sass 然后你就可以在 Markdown 或是组件中使用如下代码： 1. <style lang="sass"> 2. .title 3. font-size: 20px 4. </style> 要在组件中使用 <template lang="pug"> ，则需要安装 pug 和 pug-plain-loader : 1. yarn add -D pug pug-plain-loader ::: tip 需要指出的是，如果你是一个 stylus 用户，你并不需要在你的项目中安装 stylus 和 stylus-loader ，因 为 VuePress 已经内置了它们。 对于那些没有内置的预处理器，除了安装对应的依赖，你还需要 拓展内部的 Webpack 配置。 本文档使用 书栈(BookStack.CN) 构建 - 25 - 

26 .在 Markdown 中 使用 Vue ::: 脚本和样式提升 有时，你可以只想在当前页面应用一些 JavaScript 或者 CSS，在这种情况下，你可以直接在 Markdown 文件中 使用原生的 <script> 或者 <style> 标签，它们将会从编译后的 HTML 文件中提取出来，并作为生成的 Vue 单文件组件的 <script> 和 <style> 标签。 内置的组件 " class="reference-link">OutboundLink () 用来表明当前是一个外部链接。在 VuePress 中这个组件会紧跟在每一个外部链接后面。 " class="reference-link">ClientOnly 参考 浏览器的 API 访问限制。 " class="reference-link">Content Props: custom - boolean 用法： 当前的 .md 文件渲染的内容，当你在使用 自定义布局 时，它将非常有用。 1. <Content/> 参考: 自定义主题 > 获取渲染内容 " class="reference-link">Badge Props: text - string type - string, 可选值： "tip"|"warn"|"error" ，默认值是： "tip" vertical - string, 可选值： "top"|"middle" ，默认值是： "top" Usage: 你可以在标题文本的末尾，使用这个组件来为某些 API 添加一些状态： 本文档使用 书栈(BookStack.CN) 构建 - 26 - 

27 .在 Markdown 中 使用 Vue 1. ### Badge <Badge text="beta" type="warn"/> <Badge text="0.10.1+"/> 本文档使用 书栈(BookStack.CN) 构建 - 27 - 

28 .自定义主题 自定义主题 自定义主题 ::: tip 提示 主题组件受到同样的 浏览器的 API 访问限制。 ::: VuePress 使用单文件组件来构建自定义主题。想要开发一个自定义主题，首先在你的文档根目录新建一个 .vuepress/theme 文件夹，然后再创建一个 Layout.vue 文件： 1. . 2. └─ .vuepress 3. └─ theme 4. └─ Layout.vue 从这里开始，就和开发一个平时的 Vue 应用一样了，如何组织你的主题完全取决于你。 网站和页面的元数据 Layout 组件将会对每一个文档目录下的 .md 执行一次，同时，整个网站以及特定页面的元数据将分别暴露为 this.$site 和 this.$page 属性，它们将会被注入到每一个当前应用的组件中。 这是你现在看到的这个网站的 $site 的值： 1. { 2. "title": "VuePress", 3. "description": "Vue 驱动的静态网站生成器", 4. "base": "/", 5. "pages": [ 6. { 7. "lastUpdated": 1524027677000, 8. "path": "/", 9. "title": "VuePress", 10. "frontmatter": {} 11. }, 12. ... 13. ] 14. } title , description 和 base 会从 .vuepress/config.js 中对应的的字段复制过来，而 pages 是一 个包含了每个页面元数据对象的数据，包括它的路径、页面标题（明确地通过 YAML front matter 指定，或者通 过该页面的第一个标题取到），以及所有源文件中的 YAML front matter 的数据。 下面的这个对象是你正在看的这个页面的 $page 的值： 本文档使用 书栈(BookStack.CN) 构建 - 28 - 

29 .自定义主题 1. { 2. "lastUpdated": 1524847549000, 3. "path": "/custom-themes.html", 4. "title": "自定义主题", 5. "headers": [/* ... */], 6. "frontmatter": {} 7. } 如果用户在 .vuepress/config.js 配置了 themeConfig ，你将可以通过 $site.themeConfig 访问到它。如此一 来，你可以通过它来对用户开放一些自定义主题的配置 —— 比如指定目录或者页面的顺序，你也可以结合 $site.pages 来动态地构建导航链接。 最后，别忘了，作为 Vue Router API 的一部分， this.$route 和 this.$router 同样可以使用。 ::: tip 提示 lastUpdated 是这个文件最后一次 git 提交的 UNIX 时间戳，更多细节请参考：最后更新时间。 ::: 内容摘抄 如果一个 markdown 文件中有一个 <!-- more --> 注释，则该注释之前的内容会被抓取并暴露在 $page.excerpt 属性中。如果你在开发一个博客主题，你可以用这个属性来渲染一个带摘抄的文章列表。 获取渲染内容 当前的 .md 文件渲染的内容，可以作为一个独特的全局组件 <Content/> 来使用，你可能想要它显示在页面中 的某个地方。一个最简单的主题，可以是一个唯一的 Layout.vue 组件，并包含以下内容： 1. <template> 2. <div class="theme-container"> 3. <Content/> 4. </div> 5. </template> 应用配置 自定义主题也可以通过主题根目录下的 enhanceApp.js 文件来对 VuePress 应用进行拓展配置。这个文件应当 export default 一个钩子函数，并接受一个包含了一些应用级别属性的对象作为参数。你可以使用这个钩子来安装 一些附加的 Vue 插件、注册全局组件，或者增加额外的路由钩子等： 1. export default ({ 2. Vue, // VuePress 正在使用的 Vue 构造函数 3. options, // 附加到根实例的一些选项 4. router, // 当前应用的路由实例 5. siteData // 站点元数据 6. }) => { 本文档使用 书栈(BookStack.CN) 构建 - 29 -