开发主题

提示

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

创建一个主题

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

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

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

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

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

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

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

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

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

发布到 NPM

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

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

主题入口

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

  • CJS
  • ESM
  1. module.export = fooTheme
  1. export default fooTheme

提示

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

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

package.json

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

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