VuePress

开发主题

提示

在阅读该指南之前，你最好先了解一下 开发插件 指南。

创建一个主题

VuePress 主题是一个特殊的插件，它应该符合 主题 API 。和插件一样，主题可以是一个 主题对象 或一个 主题函数 。

const { path } = require('@vuepress/utils')

const fooTheme = {
  name: 'vuepress-theme-foo',
  layouts: {
    Layout: path.resolve(__dirname, 'layouts/Layout.vue'),
    404: path.resolve(__dirname, 'layouts/404.vue'),
  },
  // ...
}
1
2
3
4
5
6
7
8
9
10
const { path } = require('@vuepress/utils')

const fooTheme = (options, app) => {
  return {
    name: 'vuepress-theme-foo',
    layouts: {
      Layout: path.resolve(__dirname, 'layouts/Layout.vue'),
      404: path.resolve(__dirname, 'layouts/404.vue'),
    },
    // ...
  }
}
1
2
3
4
5
6
7
8
9
10
11
12

layouts 字段声明了你的主题提供的布局。

一个主题必须提供至少两个布局：Layout 和 404 。

Layout 布局应该包含 Content 组件来展示 Markdown 内容：

<template>
  <div>
    <Content />
  </div>
</template>
1
2
3
4
5

404 布局会被用于 404.html 页面：

<template>
  <div>404 Not Found</div>
</template>
1
2
3

你可以提供多个布局，用户可以通过 layout Frontmatter 来修改布局。

发布到 NPM

一个典型的主题 Package 的结构如下所示：

vuepress-theme-foo
├─ lib
│  ├─ layouts
│  │  ├─ Layout.vue
│  │  └─ 404.vue
│  └─ index.js
└─ package.json
1
2
3
4
5
6
7

主题入口

lib/index.js 文件是主题入口，它应当直接导出主题：

module.exports = fooTheme
1
export default fooTheme
1

提示

注意，主题入口会在 Node 中被加载，因此它应为 CommonJS 格式。

如果你使用 ESM 格式，你需要使用 babel在新窗口打开 或 typescript在新窗口打开 来将它编译成 CommonJS 。

package.json

为了把 Package 发布到 NPM 上，package.json在新窗口打开 文件是必需的：

{
  "name": "vuepress-theme-foo",
  "version": "1.0.0",
  "keywords": [
    "vuepress-theme",
  ],
  "main": "lib/index.js",
  "files": [
    "lib"
  ]
}
1
2
3
4
5
6
7
8
9
10
11
  • 将 name 按照约定命名： vuepress-theme-xxx 或 @org/vuepress-theme-xxx 。
  • 在 keywords 中包含 vuepress-theme ，这样用户可以在 NPM 上搜索到你的主题。
  • 将 main 设为主题入口文件。
  • 设置 files ，仅发布 lib 目录下的文件。