如何创建自定义 VuePress 主题 ¶
如果您已经听说过 VuePress,那么可能会知道它是一个功能极小的静态站点生成器。VuePress 使创建文本繁多的文档网站变得简单,比 Nuxt.js 容易得多。
但是,您是否知道 VuePress 有一个基于 Vue 构建的自定义主题系统,可以让您使用自定义功能构建自己的全功能主题?
在本文中,我们将介绍如何开始创建自己的自定义主题,遵循一些最佳实践,以及如何集成第三方 UI 库以快速创建布局。
例如,让我们来看看VuePress 文档网站。它使用默认主题。默认主题开箱即用,具有许多自定义功能,如内置搜索,可自定义导航和侧边栏,甚至是自动生成的 GitHub 链接和页面编辑链接,并用 github 托管这些页面。
在创建自定义主题有着和使用 vue 一样的开发体验。
当前版本 1.0.0-alpha.44 还不是稳定版本,可能略有变动。
设置 VuePress 项目 ¶
首先,确保在系统上安装了 VuePress。
npm install -g vuepress
复制成功
构建内容 ¶
VuePress 的魅力在于它允许您根据自己的喜好构建内容。项目中的每个 markdown 文件都将编译为静态 HTML 文件。 例如,您的项目可能结构如下:
vuepress-theme-koala ㄴguide ㄴREADME.md ㄴgetting-started.md ㄴconfig.md ㄴ.vuepress ㄴconfig.js
复制成功
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
复制成功
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>
复制成功
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) }
复制成功
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>
复制成功
2
3
4
5
Detail.veu
<a-layout> <a-layout-sider>Sider</a-layout-sider> <a-layout-content> <Content/> </a-layout-content> </a-layout>
复制成功
2
3
4
5
6
Layou.vue
<template> <div> <header>{{ $site.themeConfig.nav }}</header> <componen class="main-content" :is="layout" /> </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>
复制成功
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
请注意高亮部分,即为对应的原始数据,有了数据可以自己随意组织界面
结论 ¶
最终,创建 VuePress 主题可以提供与创建 Vue.js 应用程序一样多的灵活性。您可以自由地以最适合您的方式布置您的主题。
在这篇文章中,我们介绍了一些最佳实践,可以在主题组件中使用的数据,以及如何与 UI 库集成以创建布局。
番外篇 ¶
本人也写了一个主题 vuepress-theme-koala
安装 ¶
npm i vuepress-theme-koala
复制成功
使用 ¶
.vuepress/congig.js
module.exports = { theme: 'vuepress-theme-koala' }
复制成功
2
3
提示 ¶
vuepress 设计理念是约定大于配置,此主题的配置等同于 vuepress 文档
其他 ¶
VuePress 提供了对 YAML front matter 开箱即用的支持: vuepress-theme-koala 扩展的字段如下
--- poster: xx/xx.png tag: vue,js --- #poster为首页列表的封面 #tag为文章的标签英文逗号分隔
复制成功
2
3
4
5
6
over