组件配置

部分内置组件（插件），来源 vitepress.yiov.top 推荐

groupIcon - 分组代码块图标

作用于 code-group 代码块，提供语言/工具图标，基于 vitepress-plugin-group-icons 插件实现。

npmyarnpnpmbun

npm create @sugarat/theme@latest

yarn create @sugarat/theme

pnpm create @sugarat/theme

bun create @sugarat/theme

:::code-group
```sh [npm]
npm create @sugarat/theme@latest
```
```sh [yarn]
yarn create @sugarat/theme
```
```sh [pnpm]
pnpm create @sugarat/theme
```
```sh [bun]
bun create @sugarat/theme
```
:::

const blogTheme = getThemeConfig({
  // 自定义图标
  groupIcon: {

  }
})

也可以关闭这个功能

const blogTheme = getThemeConfig({
  groupIcon: false
})

oml2d - 看板娘集成

Type：WidgetOptions

为网站提供一个 Live2D 看板组件。

一点说明

通过内置 l2d-widget 实现, 可以通过 oml2d 选项配置。

通过这个能力可以快速加入并定制属于自己的看板娘, 开启只需要为其传递一个配置选项即可

以下是一个简单的使用示例，当模型加载成功时它将出现在您网站的左下角。

const blogTheme = getThemeConfig({
  oml2d: {
    size: { width: 200, height: 200 },
    mobileSize: { width: 120, height: 120 },
    model: [
      {
        path: 'https://registry.npmmirror.com/oml2d-models/latest/files/models/Senko_Normals/senko.model3.json',
        offset: [0, 0.2]
      }
    ]
  }
})

其中 size 用于设置看板娘画布尺寸，mobileSize 用于设置移动端尺寸（命中 max-width: 768px 时生效）。model.offset 用于微调模型在画布里的位置，格式为 [x, y]。x 为负数时模型向左移动，正数向右移动；y 为正数时模型向上移动，负数向下移动。

效果图如下

之后您还可以前往 l2d-widget 文档查阅更多自定义内容

版本说明

由于时间原因，主题内置的版本不一定都是最新的，可以通过 resolutions 配置指定要使用的版本。

下面是使用示例，配置在 package.json 中，其它依赖覆盖版本也是这样操作。

json

{
  "resolutions": {
    "l2d-widget": "^0.1.0"
  }
}

task-checkbox

Type: boolean | TaskCheckbox

支持渲染 markdown 任务列表，内置 markdown-it-task-checkbox 插件提供支持

🥔 TODO
真不戳
内置任务列表

语法如下

* [ ] 🥔 TODO
* [ ] 真不戳
* [x] 内置任务列表

默认开启，你可以进一步配置

① 关闭② 进一步配置③ type

const blogTheme = getThemeConfig({
  taskCheckbox: false
})

const blogTheme = getThemeConfig({
  taskCheckbox: {
    // refer https://github.com/linsir/markdown-it-task-checkbox for options
  }
})

interface TaskCheckbox {
  disabled?: boolean
  divWrap?: boolean
  divClass?: string
  idPrefix?: string
  ulClass?: string
  liClass?: string
}

timeline

Type: boolean
default: true

提供 markdown 时间线语法，在 vitepress 中使用 markdown 渲染时间线（时间轴）样式。

一点说明

内置 vitepress-markdown-timeline 实现

效果如下

2023-05-24

do some thing1
do some thing2

2023-05-23

do some thing3 do some thing4

语法如下

::: timeline 2023-05-24
- **do some thing1**
- do some thing2
:::

::: timeline 2023-05-23
do some thing3
do some thing4
:::

关闭

const blogTheme = getThemeConfig({
  timeline: false
})

tabs

Type: boolean

支持局部的tabs面板，默认开启

我之前手动安装配置了怎么办？

① package.json 中移除 vitepress-plugin-tabs 依赖

② .vitepress/theme/index.ts 中移除注册的组件enhanceAppWithTabs

③ （可选）getThemeConfig 中移除配置项tabs

一点说明

基于 vitepress-plugin-tabs@0.2.0 内置实现

效果如下

a content

a content 2

简单的使用方式如下（效果如上面的示例）

:::tabs
== tab a
a content
== tab b
b content
:::

:::tabs
== tab a
a content 2
== tab b
b content 2
:::

共享状态的使用方式如下

:::tabs key:ab
== tab a
a content
== tab b
b content
:::

:::tabs key:ab
== tab a
a content 2
== tab b
b content 2
:::

a content

a content 2

不需要也可以关闭

// .vitepress/blog-theme.ts
const blogTheme = getThemeConfig({
  tabs: false
})

card - 产品/项目卡片

Type: boolean | ProductCardOptions
default: true

TIP

底层由独立插件 vitepress-plugin-product-card 提供，你也可以在非本主题项目中单独使用。

提供 markdown ::: card 容器语法，用于在文章中快速展示产品/项目/工具卡片列表（如首页 "我的产品"）。

效果如下

我的产品

🍬

博客主题 @sugarat/theme

基于 VitePress 实现的简约风博客主题，开箱即用，支持深色模式、评论、RSS、Pagefind 全文搜索等。

GitHub VitepressVueTheme

📥

EasyPicker（轻取）

在线文件收集系统，一站式存储、无需注册即可提交，支持私有化部署。

GitHub Vue工具

✍️

个人博客

记录随笔与学习笔记的地方，同步更新在掘金。

GitHub VitepressVueBlog

🖼️

七牛云 OSS 图床

基于七牛云对象存储服务搭建的图床应用，前端纯静态，无需后端。

GitHub Vue工具

语法如下

::: card 我的产品

- icon: 🍬
  iconColor: "#f5d24a"
  title: 博客主题 @sugarat/theme
  link: https://theme.sugarat.top
  github: https://github.com/ATQQ/sugar-blog
  tags: [Vitepress, Vue, Theme]
  desc: 基于 **VitePress** 实现的简约风博客主题，开箱即用，支持深色模式、评论、RSS、Pagefind 全文搜索等。

----

- icon: 📥
  iconColor: "#4f8cff"
  title: EasyPicker（轻取）
  link: https://docs.ep.sugarat.top
  github: https://github.com/ATQQ/easypicker2-client
  tags: [Vue, 工具]
  desc: 在线文件收集系统，一站式存储、无需注册即可提交，支持 [私有化部署](https://docs.ep.sugarat.top/deploy/)。

----

- icon: ✍️
  iconColor: "#ff8f6b"
  title: 个人博客
  link: https://sugarat.top
  github: https://github.com/ATQQ/sugar-blog
  tags: [Vitepress, Vue, Blog]
  desc: 记录随笔与学习笔记的地方，同步更新在 [掘金](https://juejin.cn/user/1028798615918983)。

----

- icon: 🖼️
  iconColor: "#7cd6a4"
  title: 七牛云 OSS 图床
  link: https://imgbed.sugarat.top/
  github: https://github.com/ATQQ/image-bed-qiniu
  tags: [Vue, 工具]
  desc: 基于七牛云对象存储服务搭建的图床应用，前端纯静态，无需后端。

:::

字段说明：

icon：图标，支持图片 URL（http/https 或以 / 开头的站内绝对路径）或单个字符（配合 iconColor 作为底色）
iconColor：字符图标的背景色，可选
title：卡片标题（必填）
link：跳转链接，可选，命中时点击标题在新标签打开
github：GitHub 仓库地址，可选。填写后组件挂载时会自动请求 https://api.github.com/repos/{owner}/{repo} 获取创建 / 最后更新时间并展示
showCreated / showUpdated：布尔值，可选。单卡覆盖全局开关（默认均为 true）
tags：标签数组，形如 [a, b, "包含空格的标签"]
desc：描述，支持内联 Markdown（如 **加粗**、[链接](url)）

多张卡片之间使用一行 ----（4 个及以上短横线）分隔。

GitHub 时间自动展示

当卡片配置了 github 字段时，会调用 GitHub 公开 API 自动拉取仓库的创建时间与最后更新时间（created_at / pushed_at），并以 YYYY-MM-DD 格式展示在描述下方。默认两者都开启，可以：

全局关闭创建/更新时间中的任意一个：

// .vitepress/blog-theme.ts
const blogTheme = getThemeConfig({
  productCard: {
    showCreated: false,
    showUpdated: true
  }
})

单卡覆盖（在容器语法内声明，优先级高于全局）：

::: card

- title: 只显示更新时间
  github: https://github.com/owner/repo
  showCreated: false

:::

注意：GitHub 匿名接口有 60 次/小时 IP 限流；请求失败时时间信息会静默隐藏。

不需要该功能也可以整体关闭

// .vitepress/blog-theme.ts
const blogTheme = getThemeConfig({
  productCard: false
})

ProductCardOptions 与 ProductCardItem 类型定义如下

interface ProductCardOptions {
  /** 是否展示 GitHub 仓库创建时间，默认 true */
  showCreated?: boolean
  /** 是否展示 GitHub 仓库最后更新时间，默认 true */
  showUpdated?: boolean
}

interface ProductCardItem {
  icon?: string
  iconColor?: string
  title: string
  link?: string
  github?: string
  tags?: string[]
  descHtml?: string
  showCreated?: boolean
  showUpdated?: boolean
}

Mermaid - 图表

Type: boolean|object

通过解析类 Markdown 的文本语法来实现图表的创建和动态修改。

一点说明

基于 vitepress-plugin-mermaid 实现

简单语法如下，详细流程图语法见 Mermaid 中文文档

```mermaid
flowchart TD
  Start --> Stop
```

效果如下

默认关闭，可以通过设置 mermaid: true 开启，或进行进一步配置。

① 开启② 进一步配置

const blogTheme = getThemeConfig({
  mermaid: true
})

const blogTheme = getThemeConfig({
  mermaid: {
    // refer https://mermaid.js.org/config/setup/modules/mermaidAPI.html#mermaidapi-configuration-defaults for options
  }
})

下面看一下官方其它案例

时序图

甘特图

数学公式

$a \neq 0$

Attention (Q, K, V) = softmax (\frac{Q K^{⊤}}{\sqrt{d}}) V

VitePress 官方提供了内置支持，安装相关依赖，配置开启即可。

npm add -D markdown-it-mathjax3@^4

.vitepress/config.mts

export default {
  markdown: {
    math: true
  }
}

UserWorksPage

Type: UserWorks

用于作品列表展示

效果如下，详见个人作品展示

新建一个works.md文件，放入以下内容

---
layout: page
title: 个人作品展示
sidebar: false
outline: [2,3]
sticky: 1
---
<UserWorksPage />

内容配置方式如下

defaulttype

const blogTheme = getThemeConfig({
  works: {
    title: '个人项目/线上作品',
    description: '记录开发的点点滴滴',
    topTitle: '举些🌰',
    list: [
      {
        title: '博客主题 @sugarat/theme',
        description: '基于 vitepress 实现的博客主题',
        time: {
          start: '2023/01/29'
        },
        github: {
          owner: 'ATQQ',
          repo: 'sugar-blog',
          branch: 'master',
          path: 'packages/theme'
        },
        status: {
          text: '自定义badge'
        },
        url: 'https://theme.sugarat.top',
        cover:
          'https://img.cdn.sugarat.top/mdImg/MTY3MzE3MDUxOTMwMw==673170519303',
        tags: ['Vitepress', 'Vue'],
        links: [
          {
            title: '一个简约风的VitePress博客主题',
            url: 'https://juejin.cn/post/7196517835380293693'
          }
        ]
      }
    ]
  }
})

interface UserWorks {
  title: string
  description?: string
  topTitle?: string
  list: UserWork[]
}
interface UserWork {
  title: string
  description: string
  time:
  | string
  | {
    start: string
    end?: string
    lastupdate?: string
  }
  status?: {
    text: string
    type?: 'tip' | 'warning' | 'danger'
  }
  url?: string
  github?:
  | string
  | {
    owner: string
    repo: string
    branch?: string
    path?: string
  }
  cover?:
  | string
  | string[]
  | {
    urls: string[]
    layout?: 'swiper' | 'list'
  }
  links?: {
    title: string
    url: string
  }[]
  tags?: string[]
  top?: number
}

组件配置 ​

groupIcon - 分组代码块图标 ​

oml2d - 看板娘集成 ​

task-checkbox ​

timeline ​

tabs ​

card - 产品/项目卡片 ​

GitHub 时间自动展示 ​

Mermaid - 图表 ​

数学公式 ​

UserWorksPage ​

组件配置

groupIcon - 分组代码块图标

oml2d - 看板娘集成

task-checkbox

timeline

tabs

card - 产品/项目卡片

GitHub 时间自动展示

Mermaid - 图表

数学公式

UserWorksPage