如何创建自定义 VuePress 主题

如果您已经听说过 VuePress,那么可能会知道它是一个功能极小的静态站点生成器。VuePress 使创建文本繁多的文档网站变得简单,比 Nuxt.js 容易得多。

但是,您是否知道 VuePress 有一个基于 Vue 构建的自定义主题系统,可以让您使用自定义功能构建自己的全功能主题?

在本文中,我们将介绍如何开始创建自己的自定义主题,遵循一些最佳实践,以及如何集成第三方 UI 库以快速创建布局。

例如,让我们来看看VuePress 文档网站。它使用默认主题。默认主题开箱即用,具有许多自定义功能,如内置搜索,可自定义导航和侧边栏,甚至是自动生成的 GitHub 链接和页面编辑链接,并用 github 托管这些页面。

在创建自定义主题有着和使用 vue 一样的开发体验。

当前版本 1.0.0-alpha.44 还不是稳定版本,可能略有变动。

设置 VuePress 项目

首先,确保在系统上安装了 VuePress。

npm install -g vuepress
1

构建内容

VuePress 的魅力在于它允许您根据自己的喜好构建内容。项目中的每个 markdown 文件都将编译为静态 HTML 文件。 例如,您的项目可能结构如下:

vuepress-theme-koala
ㄴguide
  ㄴREADME.md
  ㄴgetting-started.md
  ㄴconfig.md
ㄴ.vuepress
  ㄴconfig.js
1
2
3
4
5
6
7

因此,一旦您的项目有内容,您如何开始创建自定义主题以显示该内容?

创建自定义 VuePress 主题

在上面的文件夹结构示例中,您可能已经注意到名为的文件夹 .vuepress。此文件夹是您的配置和所有特定于 VuePress 的文件的位置。它也是您的自定义主题文件的位置。

要创建自定义主题,请在 VuePress 项目中的 theme 目录内创建一个目录 .vuepress,然后创建一个Layout.vue文件。

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

在主题中呈现您网站的内容。

最简单的主题可以只是一个 Layout.vue 具有以下标记的组件:

<div class="theme-container">
    <Content/>
</div>
1
2
3

.md 正在呈现的当前文件的已编译内容 将作为特殊<Content/>全局组件提供。

另一种思考 Layout.vue 文件的方式是作为主题的起点,因为实际上,完全充实的主题需要的不仅仅是单个文件。

将第三方 UI 集成到主题中

cd 到 theme 文件下安装 ui 库 如 ant-design-vue

npm i ant-design-vue 在 theme/enhanceApp.js中注册 ui 组件(当然最好是按需加载)

import Antd from 'ant-design-vue'
import 'ant-design-vue/dist/antd.css'
import Layout from 'ant-design-vue/lib/layout'
import Tag from 'ant-design-vue/lib/tag'
import 'ant-design-vue/lib/layout/style/index.css'
import 'ant-design-vue/lib/tag/style/index.css'
export default ({ Vue, isServer }) => {
  Vue.use(Layout) Vue.use(Tag)
}
1
2
3
4
5
6
7
8
9

布局就随意发挥了咯 假设我们有个主页 Home.vue 还有个详情页 Detail.vue

Home.vue

<a-layout>
  <a-layout-content>
  {{$site.pages}}
  </a-layout-content>
</a-layout>
1
2
3
4
5

Detail.veu

<a-layout>
  <a-layout-sider>Sider</a-layout-sider>
  <a-layout-content>
    <Content/>
  </a-layout-content>
</a-layout>
1
2
3
4
5
6

Layou.vue















 












<template>
  <div>
    <header>{{ $site.themeConfig.nav }}</header>
    <componen :is="layout" class="main-content" />
  </div>
</template>

<script>
import Home from './Home'
import Detail from './Detail'

export default {
  computed: {
    layout() {
      const { path } = this.$page
      if (path === '/')
        return Home

      else
        return Detail

    },
  },
}
</script>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

请注意高亮部分,即为对应的原始数据,有了数据可以自己随意组织界面

结论

最终,创建 VuePress 主题可以提供与创建 Vue.js 应用程序一样多的灵活性。您可以自由地以最适合您的方式布置您的主题。

在这篇文章中,我们介绍了一些最佳实践,可以在主题组件中使用的数据,以及如何与 UI 库集成以创建布局。

番外篇

本人也写了一个主题 vuepress-theme-koala

安装

npm i vuepress-theme-koala
1

使用

.vuepress/congig.js

module.exports = {
  theme: 'vuepress-theme-koala',
}
1
2
3

提示

vuepress 设计理念是约定大于配置,此主题的配置等同于 vuepress 文档

其他

VuePress 提供了对 YAML front matter 开箱即用的支持: vuepress-theme-koala 扩展的字段如下

---
poster: xx/xx.png
tag: vue,js
---
#poster为首页列表的封面
#tag为文章的标签英文逗号分隔
1
2
3
4
5
6

over