跳至主要內容

Theme Hope 主题配置指南

2026/2/1GuideVuePressTheme大约 13 分钟...

vuepress-theme-hope 是一个功能强大的 VuePress 主题，提供了丰富的功能和美观的界面。

1. 主题特点

  • ✨ 功能丰富: 支持博客和文档模式，内置多种 Markdown 增强功能
  • 🎨 美观界面: 现代化设计，支持深色模式
  • 🔍 搜索支持: 集成本地搜索和 Algolia 搜索
  • 📝 Markdown 增强: 代码块高亮、任务列表、数学公式等
  • 💬 评论系统: 支持多种评论插件
  • 📊 统计分析: 内置页面浏览量统计

2. 安装步骤

2.1 安装依赖

在现有 VuePress 项目中执行：

npm install -D vuepress-theme-hope@latest

2.2 更新配置文件

编辑 docs/.vuepress/config.js：

import { viteBundler } from '@vuepress/bundler-vite'
import { hopeTheme } from 'vuepress-theme-hope'
import { defineUserConfig } from 'vuepress'

export default defineUserConfig({
  lang: 'zh-CN',
  title: '你的博客名称',
  description: '你的博客描述',

  bundler: viteBundler(),

  theme: hopeTheme({
    // 主题颜色模式配置
    darkmode: 'switch', // 支持深色模式切换

    // 导航栏配置
    navbar: [
      { text: '首页', link: '/' },
      { text: '文章', link: '/posts/' },
    ],

    // 侧边栏配置
    sidebar: 'structure', // 自动生成侧边栏

    // 仓库信息
    repo: 'your-username/your-repo',

    // 编辑链接
    docsDir: 'docs',
    
    // Hope 主题特有功能
    plugins: {
      // Markdown 增强
      mdEnhance: {
        gfm: true,
        container: true,
        linkCheck: true,
        vPre: true,
        tabs: true,
        codetabs: true,
        align: true,
        attrs: true,
        sup: true,
        sub: true,
        footnote: true,
        mark: true,
        figure: true,
        imgLazyload: true,
        tasklist: true,
      },
    },
  }),
})

2.3 启动开发服务器

npm run dev

访问 http://localhost:8080 查看效果。

3. 搜索功能集成

VuePress Theme Hope 支持多种搜索插件，主要有两种方案：

  • Algolia DocSearch：云端搜索，速度快，功能强大，需要申请
  • Slimsearch：本地搜索，开箱即用，无需申请

3.1 搜索方案对比

特性DocSearch (Algolia)Slimsearch
搜索速度⚡⚡⚡ 极快（云端）⚡⚡ 快（本地）
搜索质量🎯 智能匹配、拼写纠错、模糊搜索🎯 基础匹配
索引方式云端索引，自动更新构建时生成本地索引
配置难度🔧🔧 需要申请账号🔧 零配置
费用🆓 开源项目免费🆓 完全免费
网络依赖需要联网无需联网
适用场景大型文档站、公开项目中小型站点、内网项目
首次可用需等待爬虫索引（几小时）立即可用

选择建议

  • 优先推荐 Slimsearch：开箱即用，无需等待，适合快速上手
  • 大型项目推荐 Algolia：搜索体验更好，但需要申请和配置

3.2 方案一：Slimsearch（本地搜索，推荐）

3.2.1 什么是 Slimsearch

Slimsearch 是 VuePress 官方提供的本地搜索插件，具有以下特点：

  • ✅ 零配置：安装即用，无需申请任何服务
  • 🚀 快速启动：构建时生成索引，立即可用
  • 🔒 隐私保护：完全本地化，不依赖第三方服务
  • 📦 轻量级：打包体积小，不影响页面加载速度
  • 🌐 离线可用：支持离线搜索

3.2.2 安装配置

Slimsearch 插件已经安装（@vuepress/plugin-slimsearch），只需在配置文件中启用即可。

编辑 docs/.vuepress/config.js：

export default defineUserConfig({
  theme: hopeTheme({
    plugins: {
      // 启用 Slimsearch
      slimsearch: {
        // 索引全部内容
        indexContent: true,
        // 自定义字段（可选）
        customFields: [
          {
            name: 'category',
            getter: (page) => page.frontmatter.category,
          },
          {
            name: 'tag',
            getter: (page) => page.frontmatter.tag,
          },
        ],
      },
    },
  }),
})

注意

同时只能启用一个搜索插件。如果要使用 Slimsearch，需要注释掉 docsearch 配置。

3.2.3 配置选项

slimsearch: {
  // 是否索引页面内容（推荐开启）
  indexContent: true,
  
  // 是否索引页面摘要
  indexOptions: {
    // 设置分词器
    tokenize: 'forward',
  },
  
  // 自定义字段
  customFields: [
    {
      name: 'category',
      getter: (page) => page.frontmatter.category,
      formatter: 'Category: $content',
    },
    {
      name: 'tag', 
      getter: (page) => page.frontmatter.tag,
      formatter: 'Tag: $content',
    },
  ],
  
  // 热键配置
  hotKeys: [
    { key: 'k', ctrl: true },
    { key: '/', ctrl: true },
  ],
  
  // 搜索延迟（毫秒）
  searchDelay: 150,
  
  // 建议词数量
  suggestionsCount: 10,
  
  // 本地化
  locales: {
    '/': {
      placeholder: '搜索文档',
    },
  },
}

3.2.4 使用方法

  1. 启动开发服务器：npm run dev
  2. 查看搜索框：导航栏右侧会出现搜索图标
  3. 快捷键：按 Ctrl + K 或 Ctrl + / 打开搜索

3.3 方案二：Algolia DocSearch（云端搜索）

3.3.1 什么是 Algolia DocSearch

Algolia DocSearch 是一个强大的文档搜索服务，为开源项目提供免费的搜索功能。它具有以下特点：

  • ⚡ 快速响应：毫秒级搜索速度
  • 🎯 智能匹配：支持模糊搜索和拼写纠错
  • 🌐 多语言支持：支持中文等多种语言
  • 📱 响应式设计：完美适配移动端
  • 🆓 免费使用：对开源项目完全免费

3.3.2 申请 DocSearch

方式一：加入官方 DocSearch 计划（推荐）

  1. 访问申请页面

    前往 DocSearch 申请页面

  2. 填写申请表单

    需要提供以下信息：

    • 网站 URL（必须是公开可访问的）
    • 邮箱地址
    • 仓库地址（可选）

    申请要求

    • 网站必须是公开的文档或技术博客
    • 你必须是网站的所有者
    • 网站内容必须是开源的

  3. 等待审核

    提交后，Algolia 团队会审核你的申请。通过后，他们会：

    • 自动爬取你的网站内容
    • 创建搜索索引
    • 将 apiKey、indexName 和 appId 发送到你的邮箱

  4. 配置爬虫

    收到邮件后，登录 Algolia Crawler 配置爬虫规则。

方式二：自建爬虫

如果你的网站不符合官方 DocSearch 的要求，可以自己运行爬虫：

  1. 注册 Algolia 账号
  2. 创建应用和索引
  3. 参考 官方文档 运行自己的爬虫

3.3.3 安装插件

npm install -D @vuepress/plugin-docsearch@2.0.0-rc.121

版本匹配

确保安装的版本与 vuepress-theme-hope 版本兼容。当前主题版本为 2.0.0-rc.102，对应的 docsearch 版本为 2.0.0-rc.121。

3.3.4 配置插件

在 docs/.vuepress/config.js 中配置 DocSearch：

import { hopeTheme } from 'vuepress-theme-hope'

export default defineUserConfig({
  theme: hopeTheme({
    plugins: {
      docsearch: {
        appId: 'YOUR_APP_ID',           // 替换为你的 App ID
        apiKey: 'YOUR_API_KEY',         // 替换为你的 API Key
        indexName: 'YOUR_INDEX_NAME',   // 替换为你的索引名称
        
        // 中文本地化配置
        locales: {
          '/': {
            placeholder: '搜索文档',
            translations: {
              button: {
                buttonText: '搜索文档',
              },
              modal: {
                searchBox: {
                  resetButtonTitle: '清除查询条件',
                  cancelButtonText: '取消',
                },
                footer: {
                  selectText: '选择',
                  navigateText: '切换',
                  closeText: '关闭',
                },
              },
            },
          },
        },
      },
    },
  }),
})

3.3.5 配置爬虫规则

登录 Algolia Crawler，配置适用于 VuePress Theme Hope 的爬虫规则：

new Crawler({
  appId: "YOUR_APP_ID",
  apiKey: "YOUR_API_KEY",
  rateLimit: 8,
  startUrls: [
    "https://YOUR_WEBSITE_URL/",
  ],
  sitemaps: [
    "https://YOUR_WEBSITE_URL/sitemap.xml",
  ],
  discoveryPatterns: [
    "https://YOUR_WEBSITE_URL/**",
  ],
  schedule: "at 02:00 every 1 day",
  actions: [
    {
      indexName: "YOUR_INDEX_NAME",
      pathsToMatch: ["https://YOUR_WEBSITE_URL/**"],
      recordExtractor: ({ $, helpers }) => {
        return helpers.docsearch({
          recordProps: {
            lvl0: {
              selectors: [".vp-sidebar-link.active", "[vp-content] h1"],
              defaultValue: "Documentation",
            },
            lvl1: "[vp-content] h1",
            lvl2: "[vp-content] h2",
            lvl3: "[vp-content] h3",
            lvl4: "[vp-content] h4",
            lvl5: "[vp-content] h5",
            lvl6: "[vp-content] h6",
            content: "[vp-content] p, [vp-content] li",
          },
          recordVersion: "v3",
        });
      },
    },
  ],
  initialIndexSettings: {
    YOUR_INDEX_NAME: {
      attributesForFaceting: ["type", "lang"],
      attributesToRetrieve: ["hierarchy", "content", "anchor", "url"],
      attributesToHighlight: ["hierarchy", "content"],
      attributesToSnippet: ["content:10"],
      camelCaseAttributes: ["hierarchy", "content"],
      searchableAttributes: [
        "unordered(hierarchy.lvl0)",
        "unordered(hierarchy.lvl1)",
        "unordered(hierarchy.lvl2)",
        "unordered(hierarchy.lvl3)",
        "unordered(hierarchy.lvl4)",
        "unordered(hierarchy.lvl5)",
        "unordered(hierarchy.lvl6)",
        "content",
      ],
      distinct: true,
      attributeForDistinct: "url",
      customRanking: [
        "desc(weight.pageRank)",
        "desc(weight.level)",
        "asc(weight.position)",
      ],
    },
  },
});

重要配置

initialIndexSettings.YOUR_INDEX_NAME.attributesForFaceting 必须包含 "lang"，否则插件无法正常工作。

3.3.6 测试搜索

  1. 启动开发服务器：npm run dev
  2. 在导航栏应该能看到搜索框
  3. 输入关键词测试搜索功能

首次使用

首次配置后，需要等待 Algolia 爬虫完成第一次爬取（可能需要几分钟到几小时）。你可以在 Algolia Crawler 控制台手动触发爬取。

4. 首页配置 (Homepage Configuration)

VuePress Theme Hope 提供了强大的首页配置功能，支持两种展示方式。

4.1 基础配置

首页配置在 docs/README.md 的 Frontmatter 中完成。

4.1.1 Hero 区域配置

Hero 区域是首页顶部的大图展示区域：

---
home: true
title: 首页

# Hero 区域
heroText: 你的站点名称
tagline: 站点标语
heroImage: /assets/images/hero.png
heroImageDark: /assets/images/hero-dark.png  # 深色模式（可选）
heroAlt: 站点 Logo  # 无障碍文本（可选）

# 背景图片
bgImage: /assets/images/bg.png
bgImageDark: /assets/images/bg-dark.png  # 深色模式（可选）
---

完整配置选项：

配置项说明类型
home启用首页布局true
title页面标题字符串
heroText主标题字符串
tagline副标题/标语字符串
heroImageHero 图片路径
heroImageDark深色模式 Hero 图片路径
heroAlt图片替代文本字符串
bgImage背景图片路径
bgImageDark深色模式背景图片路径
heroFullScreen全屏显示true / false

4.1.2 样式自定义

可以通过以下配置自定义 Hero 区域的样式：

# Hero 区域样式（CSS 字符串）
heroStyle: "background-color: #000"

# 或使用对象格式
heroStyle:
  background-color: "#000"
  padding: "50px"

# Hero 图片样式
heroImageStyle:
  width: 200px
  height: 200px
  border-radius: 50%

# 背景图片样式
bgImageStyle:
  opacity: 0.5
  background-size: cover
  background-position: center

4.1.3 主页按钮

在 Hero 区域下方显示操作按钮：

actions:
  - text: 开始阅读 →
    link: /guide/
    type: primary    # 主要按钮（蓝色）
    icon: book       # 可选：图标
  
  - text: GitHub
    link: https://github.com/your-repo
    type: secondary  # 次要按钮（灰色）
    icon: fab fa-github

按钮配置项：

  • text: 按钮文字
  • link: 链接地址
  • type: 按钮类型（primary 或 secondary）
  • icon: 图标（可选，支持 FontAwesome 等）

4.2 功能展示方式

有两种方式展示项目功能和特性，只能选择其中一种。

4.2.1 方式一：features（简单列表）

适合简单的功能列表展示，配置简单直观：

features:
  - title: 🤖 AI 工具
    details: AI 编程助手使用指南
    link: /ai/
    icon: robot  # 可选：使用图标代替 emoji
  
  - title: 🐧 Linux
    details: Linux 服务器运维
    link: /os/linux/
  
  - title: 🏠 NAS
    details: 家庭实验室搭建
    link: /homelab/nas/

配置项说明：

  • title: 功能标题（支持 HTML 和 emoji）
  • details: 功能描述（支持 HTML）
  • link: 链接地址（可选）
  • icon: 图标（可选）

4.2.2 方式二：highlights（高级展示）

适合需要多个章节、更丰富展示的场景：

highlights:
  # 第一个章节
  - header: 🚀 快速开始
    description: 选择你感兴趣的分类，开始探索
    image: /assets/images/section1.png
    bgImage: /assets/images/bg1.png
    color: "#fff"
    type: "un-order"  # order / un-order / no-order
    highlights:
      - title: AI 工具
        details: AI 编程助手与开源模型
        link: /ai/
      - title: Linux 服务器
        details: 服务器运维实战
        link: /os/linux/
  
  # 第二个章节（使用 features）
  - header: 💡 核心特性
    description: 为什么选择我们
    bgImage: https://example.com/bg.jpg
    bgImageStyle:
      background-repeat: repeat
      background-size: initial
    features:
      - title: 实战经验
        icon: book
        details: 所有教程来自真实项目
      - title: 持续更新
        icon: sync
        details: 跟随技术发展
      - title: 深入浅出
        icon: graduation-cap
        details: 从基础到进阶

highlights 章节配置项：

配置项说明类型
header章节标题支持 HTML
description章节描述支持 HTML
image章节图片路径
imageDark深色模式章节图片路径
bgImage章节背景图片路径
bgImageDark深色模式背景图片路径
color文字颜色CSS 颜色值
type列表类型order / un-order / no-order
highlights亮点列表数组
features功能列表数组

列表类型说明：

  • order: 有序列表（1, 2, 3...）
  • un-order: 无序列表（带圆点，默认）
  • no-order: 无列表样式

4.3 页脚配置

# 版权信息
copyright: MIT Licensed | Copyright © 2024-present

# 页脚内容（支持 HTML）
footer: <a href="/about/">关于本站</a> | <a href="/privacy/">隐私政策</a>

# 禁用页脚
footer: false

4.4 完整配置示例

项目中提供了完整的配置示例：

使用建议

  1. 简单站点：使用 features 方式，配置简单，效果清晰
  2. 复杂站点：使用 highlights 方式，可以创建多个章节，展示更丰富
  3. 图片路径：使用绝对路径（以 / 开头），存放在 docs/.vuepress/public/ 目录

重要提醒

  • features 和 highlights 只能使用其中一个，不能同时使用
  • 图片路径必须是绝对路径或完整 URL
  • Frontmatter 中的媒体文件无法被打包器跟踪，相对路径不会工作

4.5 参考资源

5. 配置说明

5.1 深色模式

Theme Hope 支持三种深色模式配置：

darkmode: 'switch'   // 显示切换按钮（推荐）
darkmode: 'toggle'   // 简单切换
darkmode: 'auto'     // 自动适配系统
darkmode: 'enable'   // 强制深色
darkmode: 'disable'  // 禁用深色

5.2 主题颜色配置

Theme Hope 支持自定义主题颜色，甚至可以提供多个颜色供用户选择。

配置文件位置：docs/.vuepress/styles/config.scss

单一主题色

设置一个固定的主题颜色：

$theme-color: #3eaf7c;

多个主题色（推荐）

设置多个颜色后，主题会自动在页面右上角显示调色板图标，用户可以选择自己喜欢的颜色：

$theme-color: #3eaf7c, #2196f3, #f26d6d, #fb9b5f, #1a1a1a, #ffd700, #b76e79;

本站配置：

  • 🟢 翠绿色 (#3eaf7c) - 清新自然，适合技术文档
  • 🔵 蓝色 (#2196f3) - 科技感强，专业稳重
  • 🔴 红色 (#f26d6d) - 温暖活力，醒目突出
  • 🟠 橙色 (#fb9b5f) - 明亮友好，轻松愉悦
  • ⚫ 黑金色 (#1a1a1a) - 低调奢华，高端大气
  • 🟡 土豪金 (#ffd700) - 富贵典雅，金碧辉煌
  • 🌸 玫瑰金 (#b76e79) - 浪漫优雅，时尚精致

深色/浅色模式分别设置

为深色和浅色模式设置不同的颜色值：

// 单一颜色的深浅模式
$theme-color: (
  light: rgb(59, 186, 129),
  dark: rgb(30, 140, 90),
);

// 多个颜色，其中一个支持深浅模式
$theme-color: (
  (
    light: rgb(59, 186, 129),
    dark: rgb(30, 140, 90),
  ),
  #2196f3,
  #f26d6d,
  #fb9b5f
);

5.3 侧边栏

自动生成（推荐）：

sidebar: 'structure'  // 根据文件结构自动生成

手动配置：

sidebar: {
  '/guide/': [
    {
      text: '指南',
      children: [
        '/guide/README.md',
        '/guide/getting-started.md',
      ],
    },
  ],
}

5.4 Markdown 增强

Theme Hope 提供了丰富的 Markdown 增强功能：

5.4.1 自定义容器（警告框）

VuePress Theme Hope 支持多种自定义容器，用于显示提示、警告等信息。

支持的容器类型：

::: tip 提示标题
这是一个提示框（绿色）
:::

::: note 注释标题
这是一个注释框（蓝色）
:::

::: info 信息标题
这是一个信息框（蓝色）
:::

::: warning 警告标题
这是一个警告框（黄色）
:::

::: danger 危险标题
这是一个危险框（红色）
:::

::: important 重要标题
这是一个重要提示框（紫色）
:::

::: details 点击展开
这是一个可折叠的详情框
:::

效果示例：

推荐方案

推荐使用 Neon PostgreSQL 方案，配置最简单。

注意事项

不要将数据库凭证提交到公开仓库！

危险操作

此操作将删除所有数据，请谨慎操作！

常见错误：

::: important GitHub 风格语法不兼容

❌ 错误写法（GitHub 风格，VuePress 不支持）：

> [!TIP]
> 这是一个提示

> [!IMPORTANT]
> 这是重要信息

> [!WARNING]
> 这是警告

✅ 正确写法（VuePress 容器语法）：


::: tip
这是一个提示
:::

::: important
这是重要信息
:::

::: warning
这是警告
:::

容器标题：

  • 标题是可选的，如果不需要标题，直接省略即可
  • 标题会显示在容器顶部
::: tip
没有标题的提示框
:::
::: tip 自定义标题
有自定义标题的提示框
:::

5.4.2 其他 Markdown 增强功能

  • 代码块分组: 使用 @tab 语法
  • 数学公式: 支持 KaTeX
  • 流程图: 支持 Mermaid
  • 任务列表: - [ ] 和 - [x]
  • 上下标: ^上标^ 和 ~下标~
  • 标记高亮: ==高亮文本==
  • 脚注: [^1] 和 [^1]: 脚注内容

5.5 图片资源配置 (Image Assets)

Theme Hope 支持丰富的图片配置，我们在 docs/.vuepress/config.js 中进行了如下配置：

theme: hopeTheme({
  logo: '/assets/images/logo.png',     // 导航栏 Logo
  favicon: '/favicon.png',             // 站点 Favicon

  // 博客相关图片
  blog: {
    avatar: '/assets/images/avatar.png', // 博主头像
    roundAvatar: true,                   // 圆形头像
  },
})

首页 (README.md) 的图片配置：

heroImage: /assets/images/hero.png      # 亮色模式 Hero 图
heroImageDark: /assets/images/hero.png  # 深色模式 Hero 图
bgImage: /assets/images/bg.png          # 背景图

所有图片资源存放于：docs/.vuepress/public/assets/images/

6. 常见问题

Q: 为什么警告框不显示？

A: 确保使用 VuePress 容器语法，而不是 GitHub 风格的语法。

❌ 错误：

> [!TIP]
> 提示内容

✅ 正确：

::: tip
提示内容
:::

VuePress Theme Hope 支持的容器类型：tip、note、info、warning、danger、important、details。

详见 5.4.1 自定义容器 章节。

Q: 如何启用博客功能？

A: 在主题配置中添加 blog: true，并在文章的 Frontmatter 中添加 date 字段。

Q: 如何添加评论系统？

A: 配置 plugins.comment，支持 Giscus、Waline 等多种评论插件。

Q: 如何自定义主题颜色？

A: 创建 docs/.vuepress/styles/palette.scss 文件，覆盖主题颜色变量。

7. 更多资源