• 开发主题
    • 获取渲染内容
    • 内容摘抄
    • 目录结构
    • 布局组件
    • 使用插件
    • 网站和页面的元数据
    • 应用配置

    开发主题

    想要书写一个主题，首先在你文档根目录创建一个 .vuepress/theme 目录，接着创建一个 Layout.vue 文件：

    1. .
    2. └─ .vuepress
    3.  └─ theme
    4.      └─ Layout.vue

    到这里，就像开发一个普通的 Vue 应用一样。如何组织你的主题，这完全取决于你。

    获取渲染内容

    当前的 .md 文件渲染的内容，可以作为一个独特的全局组件 <Content/> 来使用，你可能想要它显示在页面中的某个地方。一个最简单的主题，可以是一个唯一的 Layout.vue 组件，并包含以下内容：

    1. <template>
    2.   <div class="theme-container">
    3.     <Content/>
    4.   </div>
    5. </template>

    更多请阅读:

    • Markdown 插槽

    内容摘抄

    如果一个 markdown 文件中有一个 <!— more —> 注释，则该注释之前的内容会被抓取并暴露在 $page.excerpt 属性中。如果你在开发一个博客主题，你可以用这个属性来渲染一个带摘抄的文章列表。

    目录结构

    随着需求的变化，只有一个布局组件 Layout.vue 可能还不够，你可能想要定义更多的布局组件用于不同的页面，你可能还想要自定义一个调色板，甚至应用一些插件。

    那么是时候重新组织你的主题了！一个约定的主题的目录结构如下：

    1. theme
    2. ├── global-components
    3. │   └── xxx.vue
    4. ├── components
    5. │   └── xxx.vue
    6. ├── layouts
    7. │   ├── Layout.vue (必要的)
    8. │   └── 404.vue
    9. ├── styles
    10. │   ├── index.styl
    11. │   └── palette.styl
    12. ├── templates
    13. │   ├── dev.html
    14. │   └── ssr.html
    15. ├── index.js
    16. ├── enhanceApp.js
    17. └── package.json
    • theme/global-components: 该目录下的组件都会被自动注册为全局组件。想了解更多，请参考 @vuepress/plugin-register-components。
    • theme/components: Vue 组件。
    • theme/layouts: 布局组件，其中 Layout.vue 是必需的。
    • theme/styles: 全局的样式和调色板。
    • theme/templates: 修改默认的模板文件。
    • theme/index.js: 主题文件的入口文件。
    • theme/enhanceApp.js: 主题水平的客户端增强文件。

    注意

    当你将你的主题以一个 npm 包的形式发布时，如果你没有任何主题配置，即没有 theme/index.js，那么你需要将 package.json 中的 "main" 字段设置为 layouts/Layout.vue，只有这样 VuePress 才能正确地解析主题。

    1. {
    2.   ...
    3.   "main": "layouts/Layout.vue",
    4.   ...
    5. }

    布局组件

    假设你的主题 layouts 目录如下：

    1. theme
    2. └── layouts
    3.    ├── Layout.vue
    4.    ├── AnotherLayout.vue
    5.    └── 404.vue

    然后，所有的页面将会默认使用 Layout.vue 作为布局组件，对于那些匹配不到的路由将会使用 404.vue。

    如果你想要在某一个页面中使用 AnotherLayout.vue 作为布局组件，那么你只需要更新这个页面的 frontmatter：

    1. ---
    2. layout: AnotherLayout
    3. ---

    提示

    每个 layout 组件都可能会渲染出截然不同的页面，如果你想设置一些全局的 UI（如全局的 <header>），可以考虑使用 globalLayout。

    使用插件

    你可以通过主题的配置文件 themePath/index.js 来给主题应用一些插件：

    1. module.exports = {
    2.   plugins: [
    3.     '@vuepress/pwa',
    4.     { 
    5.       serviceWorker: true,
    6.       updatePopup: true
    7.     }
    8.   ]
    9. }

    网站和页面的元数据

    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 的值：

    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 同样可以使用。

    提示

    lastUpdated 是这个文件最后一次 git 提交的 UNIX 时间戳，更多细节请参考：最后更新时间。

    参考:

    • 全局计算属性.

    应用配置

    自定义主题也可以通过主题根目录下的 enhanceApp.js 文件来对 VuePress 应用进行拓展配置。这个文件应当 export default 一个钩子函数，并接受一个包含了一些应用级别属性的对象作为参数。你可以使用这个钩子来安装一些附加的 Vue 插件、注册全局组件，或者增加额外的路由钩子等：

    1. export default ({
    2.   Vue, // VuePress 正在使用的 Vue 构造函数
    3.   options, // 附加到根实例的一些选项
    4.   router, // 当前应用的路由实例
    5.   siteData // 站点元数据
    6. }) => {
    7.   // ...做一些其他的应用级别的优化
    8. }