Theme Extending

About 1 min

vuepress-theme-hope supports extending just like @vuepress/theme-default.

You can create your own theme based on vuepress-theme-hope and use it locally or publish it according to your needs.

How to Extend Theme Hope

You need to create an entry file for your theme and import hopeTheme from vuepress-theme-hope.

In your entry file, set extends: hopeTheme(options) to extend the vuepress-theme-hope theme.

The aliases of the same name (alias) and layouts (layouts) of your own newly created theme has higher priority over the extended theme vuepress-theme-hope, which means that you can override vuepress-theme-hope components via alias option in theme api, and you can add or override layouts via layouts in client config file.

.vuepress/theme/index.ts
import { getDirname
, path
 } from "vuepress/utils";
import { hopeTheme
 } from "vuepress-theme-hope";
import type { ThemeOptions } from "vuepress-theme-hope";

const __dirname
 = getDirname
(import.meta.url
);

export default (options
: ThemeOptions) => ({
  name
: "vuepress-theme-local",

  extends
: hopeTheme
(options
, { custom
: true }),

  alias
: {
    // You can override or add aliases here
    // For example, here we change the vuepress-theme-hope HomePage component to components/HomePage.vue under our own theme
    "@theme-hope/components/home/HomePage": path
.resolve
(
      __dirname
,
      "./components/HomePage.vue",
    ),
  },
});

.vuepress/theme/index.js
import { getDirname, path } from "vuepress/utils";
import { hopeTheme } from "vuepress-theme-hope";

const __dirname = getDirname(import.meta.url);

export default (options) => ({
  name: "vuepress-theme-local",

  extends: hopeTheme(options, { custom: true }),

  alias: {
    // You can override or add aliases here
    // For example, here we change the vuepress-theme-hope HomePage component to components/HomePage.vue under our own theme
    "@theme-hope/components/home/HomePage": path.resolve(
      __dirname,
      "./components/HomePage.vue",
    ),
  },
});

Also, you can add or override layout provided by vuepress-theme-hope via layouts with slots in your theme client config file.

.vuepress/layout/Home.vue
<script setup lang="ts">
import { Layout } from "vuepress-theme-hope/client";
</script>

<template>
  <Layout>
    <!-- Overriding default hero logo to advanced ones, like home page of theme docs -->
    <template #heroLogo>
      <div>A 3D logo</div>
    </template>
    <!-- Introduce comment component using pageBottom slot -->
    <template #pageBottom>
      <CommentService />
    </template>
  </Layout>
</template>

.vuepress/layout/Layout.vue
<script setup lang="ts">
import { Layout } from "vuepress-theme-hope/client";
</script>

<template>
  <Layout>
    <!-- Adding ADs before Markdown content with contentBefore slot -->
    <template #contentBefore>
      <div>AD contents</div>
    </template>
  </Layout>
</template>

.vuepress/client.ts
import { defineClientConfig } from "vuepress/client";
import Changelog from "./layouts/Changelog.vue";
import Home from "./layouts/Home.vue";
import Layout from "./layouts/Changelog.vue";

export default defineClientConfig({
  // You can override or add layouts here
  layouts: {
    // a home page layout with customized hero logo
    Home,
    // For example, here we change the default layout of vuepress-theme-hope to layouts/Layout.vue with ADs
    Layout,
    // Also we added a Changelog layout
    Changelog,
  },
});