查看“VuePress开发主题”的源代码

== 创建一个主题 ==

VuePress 主题是一个特殊的插件，它应该符合 主题 API 。和插件一样，主题可以是一个 ''主题对象'' 或一个 ''主题函数'' ，并且通常通过一个函数来接收配置项：

<syntaxhighlight lang="ts">import { getDirname, path } from '@vuepress/utils'

const __dirname = getDirname(import.meta.url)

const fooTheme = (options) => {
  // 返回一个主题对象
  return {
    name: 'vuepress-theme-foo',

    // 主题的客户端配置文件的路径
    clientConfigFile: path.resolve(__dirname, 'client.js'),

    // 设置自定义 dev / build 模板
    // 如果没有指定模板，将会使用 `@vuepress/client` 提供的默认模板
    templateBuild: path.resolve(__dirname, 'templates/build.html'),
    templateDev: path.resolve(__dirname, 'templates/dev.html'),

    // 使用插件
    plugins: [
      // ...
    ],

    // 其他的插件 API 也都可用
  }
}

const barTheme = (options) => {
  // 返回一个主题函数
  return (app) => {
    return {
      name: 'vuepress-theme-bar',
      // ...
    }
  }
}</syntaxhighlight>
然后，创建主题的客户端配置文件 <code>client.js</code> :

<syntaxhighlight lang="ts">import { defineClientConfig } from '@vuepress/client'
import Layout from './layouts/Layout.vue'
import NotFound from './layouts/NotFound.vue'

export default defineClientConfig({
  layouts: {
    Layout,
    NotFound,
  },
})</syntaxhighlight>
<code>layouts</code> 字段声明了你的主题提供的布局。一个主题必须提供至少两个布局：<code>Layout</code> 和 <code>NotFound</code> 。前者用于提供一般页面的默认布局，后者用于提供 404 页面的布局。

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

<pre class="vue">&lt;template&gt;
  &lt;div&gt;
    &lt;Content /&gt;
  &lt;/div&gt;
&lt;/template&gt;</pre>
<code>NotFound</code> 布局会被用于 <code>404.html</code> 页面：

<pre class="vue">&lt;template&gt;
  &lt;div&gt;404 Not Found&lt;/div&gt;
&lt;/template&gt;</pre>
你可以提供多个布局，用户可以通过 layout Frontmatter 来修改布局。

<span id="发布到-npm"></span>
== 发布到 NPM ==

同样的，对于主题也有 [https://docs.npmjs.com/cli/v8/configuring-npm/package-json package.json] 相关的约定：

<syntaxhighlight lang="json">{
  "name": "vuepress-theme-foo",
  "keywords": [
    "vuepress-theme"
  ]
}</syntaxhighlight>
* 将 <code>name</code> 按照约定命名： <code>vuepress-theme-xxx</code> 或 <code>@org/vuepress-theme-xxx</code> ，它应该和 ''主题对象'' 的 name 字段保持一致。
* 在 <code>keywords</code> 中包含 <code>vuepress-theme</code> ，这样用户可以在 NPM 上搜索到你的主题。