CreateHub

主题

主题配置 ​

所有页面 UI 相关的设置都在 themeConfig 里。

站点基本设置 ​

ts
export default defineConfig({
  title: '站点名称',              // 浏览器标签页标题（默认）
  titleTemplate: ':title - 站点名称', // 页面标题模板
  description: '站点描述',         // SEO 描述
  lang: 'zh-CN',                  // 语言，影响 HTML lang 属性

  themeConfig: {
    siteTitle: '左上角名称',       // 不设置就用 title
  }
})

titleTemplate 给每个页面标题加前后缀。:title 是占位符，会被替换为当前页面标题：

ts
titleTemplate: ':title - HYC工作组'   // "项目A → 项目A - HYC工作组"
titleTemplate: 'HYC工作组 | :title'   // "项目A → HYC工作组 | 项目A"
titleTemplate: false                  // 完全关闭，只用页面自己的标题

主题色 ​

VitePress 用 CSS 变量控制颜色。创建 .vitepress/theme/custom.css：

css
:root {
  /* 主色调（三个色阶） */
  --vp-c-brand-1: #3b82f6;   /* 按钮、链接等主色 */
  --vp-c-brand-2: #2563eb;   /* 悬停时 */
  --vp-c-brand-3: #1d4ed8;   /* 点击时 */
  --vp-c-brand-soft: rgba(59, 130, 246, 0.14);  /* 按钮背景 */

  /* 文字颜色 */
  --vp-c-text-1: #1a1a2e;    /* 主要文字 */
  --vp-c-text-2: #4a4a5e;    /* 次要文字 */
  --vp-c-text-3: #7a7a8e;    /* 辅助文字 */

  /* 背景色 */
  --vp-c-bg: #ffffff;
  --vp-c-bg-soft: #f6f6f7;
  --vp-c-bg-alt: #f1f1f2;

  /* 边框 */
  --vp-c-border: #e2e2e3;
  --vp-c-divider: #e2e2e3;
}

另一套暗黑模式变量：

css
html.dark {
  --vp-c-brand-1: #818cf8;
  --vp-c-brand-2: #6366f1;
  --vp-c-brand-3: #4f46e5;
  --vp-c-brand-soft: rgba(129, 140, 248, 0.16);

  --vp-c-text-1: #e4e4e7;
  --vp-c-text-2: #a1a1aa;
  --vp-c-text-3: #71717a;

  --vp-c-bg: #1b1b1f;
  --vp-c-bg-soft: #252529;
  --vp-c-bg-alt: #2b2b30;

  --vp-c-border: #3c3f44;
  --vp-c-divider: #2e2e32;
}

快速配色

拿不准颜色的话，用 VitePress 主题色生成器 找一个颜色，取 500/600/700 三个色阶就行。

字体 ​

css
:root {
  --vp-font-family-base: 'Inter', 'Noto Sans SC', sans-serif;
  --vp-font-family-mono: 'Fira Code', monospace;
}

如果不想用默认的 Inter 字体（减小输出体积），改用 vitepress/theme-without-fonts 导入：

ts
// .vitepress/theme/index.ts
import DefaultTheme from 'vitepress/theme-without-fonts'
import './custom.css'
export default DefaultTheme

暗黑模式切换 ​

ts
themeConfig: {
  darkModeSwitchLabel: '主题',              // 开关旁边的文字
  lightModeSwitchTitle: '切换到浅色模式',    // 鼠标悬停提示
  darkModeSwitchTitle: '切换到深色模式',
}

本地搜索 ​

VitePress 自带本地搜索，不需要任何第三方服务：

ts
themeConfig: {
  search: {
    provider: 'local',     // 本地搜索
    options: {
      // 搜索结果的片段长度
      miniSearch: {
        searchOptions: {
          fuzziness: 0.2,  // 模糊匹配度
        }
      },
      // 中文文本
      translations: {
        button: {
          buttonText: '搜索文档',
          buttonAriaLabel: '搜索文档',
        },
        modal: {
          displayDetails: '显示详情',
          noResultsText: '无法找到相关结果',
          resetButtonTitle: '清除查询',
          footer: {
            selectText: '选择',
            navigateText: '切换',
            closeText: '关闭',
          },
        },
      },
    },
  },
}

大纲（右侧目录） ​

控制页面右侧的目录显示：

ts
themeConfig: {
  outline: {
    label: '本页目录',       // 标题文字
    level: [2, 3],          // 显示 h2 和 h3
    // level: 'deep',       // 等同于 [2, 6]
    // level: [2, 6],       // 显示 h2 到 h6
  },
}
配置效果
level: [2, 3]只显示 h2 和 h3
level: 'deep'显示 h2 ~ h6
level: [2, 4]显示 h2 ~ h4

也可以在单个页面的 frontmatter 中覆盖：

yaml
---
outline: deep          # 等同于 [2, 6]
# 或
outline: [2, 4]        # 当前页只显示 h2 ~ h4
---

上下页导航 ​

页面底部自动显示的上一页/下一页：

ts
themeConfig: {
  docFooter: {
    prev: '上一页',
    next: '下一页',
  },
}

文本基于侧边栏的顺序自动推断。在 frontmatter 中可以为特定页面自定义：

yaml
---
prev: '/某个页面'
next: '/另一个页面'
---

编辑链接 ​

页面底部显示"在 GitHub 上编辑"的链接：

ts
themeConfig: {
  editLink: {
    pattern: 'https://github.com/用户名/仓库/edit/main/createhub/:path',
    text: '在 GitHub 上编辑此页',
  },
}

单个页面可以关闭：

yaml
---
editLink: false
---

最后更新时间 ​

基于 Git 提交记录显示页面最后更新时间：

ts
themeConfig: {
  lastUpdated: {
    text: '最后更新于',
    formatOptions: {
      dateStyle: 'short',
      timeStyle: 'medium',
    },
  },
}

页脚 ​

ts
themeConfig: {
  footer: {
    message: '基于 VitePress 构建',
    copyright: '© 2026 HYC工作组',
  },
}

404 页面 ​

自定义页面不存在的提示：

ts
themeConfig: {
  notFound: {
    title: '页面未找到',
    quote: '你来到了未知领域，不如返回首页？',
    linkLabel: '返回首页',
    linkText: '带我回去',
  },
}

社交链接 ​

ts
themeConfig: {
  socialLinks: [
    { icon: 'github', link: 'https://github.com/xxx' },
    { icon: 'bilibili', link: 'https://space.bilibili.com/xxx' },
  ]
}

使用自定义 SVG 图标 ​

ts
{
  icon: {
    svg: '<svg viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg">...</svg>'
  },
  link: 'https://example.com',
  ariaLabel: '我的站点'
}

SVG 中用 fill="currentColor" 可以让颜色跟随主题。

通过 head 快速注入样式 ​

不想创建主题文件的话，在配置的 head 数组里直接写 CSS：

ts
head: [
  ['style', {}, `
    :root {
      --vp-c-brand-1: #ff6600;
    }

    /* 去掉手机点击蓝框，保留键盘导航焦点提示 */
    * {
      -webkit-tap-highlight-color: transparent;
      outline: none;
    }
    :focus-visible {
      outline: 2px solid var(--vp-c-brand-1);
    }
  `]
]

适合改个颜色、调个间距的小改动。

移动端优化

-webkit-tap-highlight-color: transparent 去掉 iOS/Android 点击时的蓝色高亮；outline: none + :focus-visible 配合，在去掉触摸焦点框的同时保留键盘 Tab 导航的可访问性。

Powered by VitePress