Vitepress Theme Teek

主题

Teeker2025-03-08
3511
15.7m

卡片栏配置 ​

homeCardListPosition v1.2.0 ​

  • 类型：left | right | false
  • 默认值：right

首页卡片栏列表位置，当为 left 则在文章列表左侧，当为 right 则在文章列表右侧，当为 false 时则不显示卡片栏。

ts
// .vitepress/config.mts
import { defineTeekConfig } from "vitepress-theme-teek/config";

const teekConfig = defineTeekConfig({
  homeCardListPosition: "right",
});

homeCardSort ​

  • 类型：("topArticle" | "category" | "tag" | "friendLink" | "docAnalysis")[]
  • 默认值：["topArticle", "category", "tag", "friendLink", "docAnalysis"]

首页卡片的位置排序，当设置了 homeCardSort 但没有全部补全内容，Teek 会将剩余内容按照 homeCardSort 的顺序进行添加。

ts
// .vitepress/config.mts
import { defineTeekConfig } from "vitepress-theme-teek/config";

const teekConfig = defineTeekConfig({
  homeCardSort: ["topArticle", "category", "tag", "friendLink", "docAnalysis"],
});
yaml
---
tk:
  homeCardSort:
    - topArticle
    - category
    - tag
    - friendLink
    - docAnalysis
---

tagColor v1.1.5 ​

  • 类型：string[]
  • 默认值：
json
[
  { "border": "#bfdbfe", "bg": "#eff6ff", "text": "#2563eb" },
  { "border": "#e9d5ff", "bg": "#faf5ff", "text": "#9333ea" },
  { "border": "#fbcfe8", "bg": "#fdf2f8", "text": "#db2777" },
  { "border": "#a7f3d0", "bg": "#ecfdf5", "text": "#059669" },
  { "border": "#fde68a", "bg": "#fffbeb", "text": "#d97706" },
  { "border": "#a5f3fc", "bg": "#ecfeff", "text": "#0891b2" },
  { "border": "#c7d2fe", "bg": "#eef2ff", "text": "#4f46e5" }
]

标签背景色，用于精选文章卡片的 top + sticky 功能和标签卡片的标签，背景色按顺序显示。

当在文章页的 frontmatter 配置时，如果颜色值有 # 号时请添加引号。

ts
// .vitepress/config.mts
import { defineTeekConfig } from "vitepress-theme-teek/config";

const teekConfig = defineTeekConfig({
  bgColor: [
    { border: "#bfdbfe", bg: "#eff6ff", text: "#2563eb" },
    { border: "#e9d5ff", bg: "#faf5ff", text: "#9333ea" },
    { border: "#fbcfe8", bg: "#fdf2f8", text: "#db2777" },
    { border: "#a7f3d0", bg: "#ecfdf5", text: "#059669" },
    { border: "#fde68a", bg: "#fffbeb", text: "#d97706" },
    { border: "#a5f3fc", bg: "#ecfeff", text: "#0891b2" },
    { border: "#c7d2fe", bg: "#eef2ff", text: "#4f46e5" },
  ],
});
yaml
---
tk:
  bgColor:
    - border: "#bfdbfe"
      bg: "#eff6ff"
      text: "#2563eb"
    - border: "#e9d5ff"
      bg: "#faf5ff"
      text: "#9333ea"
    - border: "#fbcfe8"
      bg: "#fdf2f8"
      text: "#db2777"
    - border: "#a7f3d0"
      bg: "#ecfdf5"
      text: "#059669"
    - border: "#fde68a"
      bg: "#fffbeb"
      text: "#d97706"
    - border: "#a5f3fc"
      bg: "#ecfeff"
      text: "#0891b2"
    - border: "#c7d2fe"
      bg: "#eef2ff"
      text: "#4f46e5"
---

blogger ​

博主信息，显示在首页左边第一个卡片。

ts
// .vitepress/config.mts
import { defineTeekConfig } from "vitepress-theme-teek/config";

const teekConfig = defineTeekConfig({
  blogger: {
    name: "天客", // 博主昵称
    slogan: "朝圣的使徒，正在走向编程的至高殿堂！", // 博主签名
    avatar: "https://testingcf.jsdelivr.net/gh/Kele-Bingtang/static/user/avatar1.png", // 博主头像
    shape: "circle-rotate", // 头像风格：square 为方形头像，circle 为圆形头像，circle-rotate 可支持鼠标悬停旋转，circle-rotate-last 将会持续旋转 59s
    circleBgImg: "/blog/bg4.webp", // 背景图片
    circleBgMask: true, // 遮罩层是否显示，仅当 shape 为 circle 且 circleBgImg 配置时有效
    circleSize: 100, // 头像大小
    color: "#ffffff", // 字体颜色
    // 状态，仅当 shape 为 circle 相关值时有效
    status: {
      icon: "😪", // 状态图标
      size: 24, // 图标大小
      title: "困", // 鼠标悬停图标的提示语
    },
  },
});
yaml
---
tk:
  blogger:
    name: 天客
    slogan: 朝圣的使徒，正在走向编程的至高殿堂！
    avatar: https://testingcf.jsdelivr.net/gh/Kele-Bingtang/static/user/avatar1.png
    shape: circle-rotate
    circleBgImg: /blog/bg4.webp
    circleBgMask: true
    circleSize: 100
    color: #ffffff
    status:
      icon: "😪",
      size: 24,
      title: "困"
---
ts
import type { TkAvatarProps } from "@teek/components/common/Avatar";

interface Blogger {
  /**
   * 博主昵称
   */
  name: string;
  /**
   * 博主签名
   */
  slogan?: string;
  /**
   * 博主头像
   */
  avatar?: string;
  /**
   * 头像风格：square 为方形头像，circle 为圆形头像，circle-rotate 可支持鼠标悬停旋转，circle-rotate-last 将会持续旋转 59s
   *
   * @default 'square'
   */
  shape?: TkAvatarProps["shape"] | "circle-rotate" | "circle-rotate-last";
  /**
   * 背景图片地址，仅当 shape 为 circle 相关值时有效
   *
   * @since v1.1.5
   */
  circleBgImg?: string;
  /**
   * 遮罩层是否显示，仅当 shape 为 circle 且 circleBgImg 配置时有效
   *
   * @default true
   * @since v1.3.1
   */
  circleBgMask?: boolean;
  /**
   * 圆形头像大小，仅当 shape 为 circle 相关值时有效
   *
   * @default 100
   * @since v1.4.6
   */
  circleSize?: TkAvatarProps["size"];
  /**
   * 字体颜色
   *
   * @since v1.3.1
   */
  color?: string;
  /**
   * 状态，仅当 shape 为 circle 相关值时有效
   *
   * @since v1.4.6
   */
  status?: {
    /**
     * 图标
     */
    icon: string;
    /**
     * 图标大小
     *
     * @default 24
     */
    size?: TkAvatarProps["size"];
    /**
     * 鼠标悬停图标的提示语
     */
    title?: string;
  };
}

topArticle ​

精选文章卡片配置。

ts
// .vitepress/config.mts
import { defineTeekConfig } from "vitepress-theme-teek/config";

const teekConfig = defineTeekConfig({
  topArticle: {
    enabled: true, // 是否启用精选文章卡片
    title: "${icon}精选文章", // 卡片标题
    emptyLabel: "暂无精选文章", // 精选文章为空时的标签
    limit: 5, // 一页显示的数量
    autoPage: false, // 是否自动翻页
    pageSpeed: 4000, // 翻页间隔时间，单位：毫秒。autoPage 为 true 时生效
    dateFormat: "yyyy-MM-dd hh:mm:ss", // 精选文章的日期格式
  },
});
yaml
---
tk:
  topArticle:
    enabled: true
    title: ${icon}精选文章
    emptyLabel: 暂无精选文章
    limit: 5
    autoPage: false
    pageSpeed: 4000
    dateFormat: yyyy-MM-dd hh:mm:ss
---
ts
import type { VpRouter } from "@teek/composables";

interface TopArticle {
  /**
   * 是否启用精选文章卡片
   *
   * @default true
   */
  enabled?: boolean;
  /**
   * 卡片标题
   *
   * @default '${icon}精选文章'
   */
  title?: string | ((icon: string) => string);
  /**
   * 精选文章为空时的标签
   *
   * @default '暂无精选文章'
   */
  emptyLabel?: string;
  /**
   * 一页显示的数量
   *
   * @default 5
   */
  limit?: number;
  /**
   * 是否自动翻页
   *
   * @default false
   */
  autoPage?: boolean;
  /**
   * 翻页间隔时间，单位：毫秒。autoPage 为 true 时生效
   *
   * @default 4000 (4秒)
   */
  pageSpeed?: number;
  /**
   * 精选文章的日期格式
   *
   * @default 'yyyy-MM-dd hh:mm:ss'
   */
  dateFormat?: "yyyy-MM-dd" | "yyyy-MM-dd hh:mm:ss" | ((date: number | string) => string);
  /**
   * 点击标题时触发，可以通过 router.go 跳转到其他页面，也可以通过 window.open 打开新窗口
   *
   * @since v1.1.2
   */
  titleClick?: (router: VpRouter) => void;
}

category ​

分类卡片配置。

ts
// .vitepress/config.mts
import { defineTeekConfig } from "vitepress-theme-teek/config";

const teekConfig = defineTeekConfig({
  category: {
    enabled: true, // 是否启用分类卡片
    path: "/categories", // 分类页访问地址
    pageTitle: "${icon}全部分类", // 分类页卡片标题
    homeTitle: "${icon}文章分类", // 卡片标题
    moreLabel: "更多 ...", // 查看更多分类标签
    emptyLabel: "暂无文章分类", // 分类为空时的标签
    limit: 5, // 一页显示的数量
    autoPage: false, // 是否自动翻页
    pageSpeed: 4000, // 翻页间隔时间，单位：毫秒。autoPage 为 true 时生效
  },
});
yaml
---
tk:
  category:
    enabled: true
    path: /categories
    pageTitle: ${icon}全部分类
    homeTitle: ${icon}文章分类
    moreLabel: 更多 ...
    emptyLabel: 暂无文章分类
    limit: 5
    autoPage: false
    pageSpeed: 4000
---
ts
interface Category {
  /**
   * 是否启用分类卡片
   *
   * @default true
   */
  enabled?: boolean;
  /**
   * 分类页访问地址
   *
   * @default '/categories'
   */
  path?: string;
  /**
   * 分类页卡片标题
   *
   * @default '${icon}全部分类'
   */
  pageTitle?: string | ((icon: string) => string);
  /**
   * 卡片标题
   *
   * @default '${icon}文章分类'
   */
  homeTitle?: string | ((icon: string) => string);
  /**
   * 查看更多分类标签
   *
   * @default '更多 ...'
   */
  moreLabel?: string;
  /**
   * 分类为空时的标签
   *
   * @default '暂无文章分类'
   */
  emptyLabel?: string;
  /**
   * 一页显示的数量
   *
   * @default 5
   */
  limit?: number;
  /**
   * 是否自动翻页
   *
   * @default false
   */
  autoPage?: boolean;
  /**
   * 翻页间隔时间，单位：毫秒。autoPage 为 true 时生效
   *
   * @default 4000 (4秒)
   */
  pageSpeed?: number;
}

tag ​

标签卡片配置。

ts
// .vitepress/config.mts
import { defineTeekConfig } from "vitepress-theme-teek/config";

const teekConfig = defineTeekConfig({
  tag: {
    enabled: true, // 是否启用标签卡片
    path: "/tags", // 标签页访问地址
    pageTitle: "${icon}全部标签", // 标签页页卡片标题
    homeTitle: "${icon}热门标签", // 卡片标题
    moreLabel: "更多 ...", //  查看更多分类标签
    emptyLabel: "暂无标签", // 标签为空时的标签
    limit: 21, // 一页显示的数量
    autoPage: false, // 是否自动翻页
    pageSpeed: 4000, // 翻页间隔时间，单位：毫秒。autoPage 为 true 时生效
  },
});
yaml
---
tk:
  tag:
    enabled: true
    path: /tags
    pageTitle: ${icon}全部标签
    homeTitle: ${icon}热门标签
    moreLabel: 更多 ...
    emptyLabel: 暂无标签
    limit: 5
    autoPage: false
    pageSpeed: 4000
---
ts
interface Tag {
  /**
   * 是否启用标签卡片
   *
   * @default true
   */
  enabled?: boolean;
  /**
   * 标签页访问地址
   *
   * @default '/tags'
   */
  path?: string;
  /**
   * 标签页页卡片标题
   *
   * @default '${icon}全部标签'
   */
  pageTitle?: string | ((icon: string) => string);
  /**
   * 卡片标题
   *
   * @default '${icon}热门标签'
   */
  homeTitle?: string | ((icon: string) => string);
  /**
   * 查看更多分类标签
   *
   * @default '更多 ...'
   */
  moreLabel?: string;
  /**
   * 标签为空时的标签
   *
   * @default '暂无标签'
   */
  emptyLabel?: string;
  /**
   * 一页显示的数量
   *
   * @default 21
   */
  limit?: number;
  /**
   * 是否自动翻页
   *
   * @default false
   */
  autoPage?: boolean;
  /**
   * 翻页间隔时间，单位：毫秒。autoPage 为 true 时生效
   *
   * @default 4000 (4秒)
   */
  pageSpeed?: number;
}

友情链接卡片配置。

ts
// .vitepress/config.mts
import { defineTeekConfig } from "vitepress-theme-teek/config";

const teekConfig = defineTeekConfig({
  friendLink: {
    enabled: true, // 是否启用友情链接卡片
    list: [
      {
        name: "Teeker",
        desc: "朝圣的使徒，正在走向编程的至高殿堂！",
        avatar: "https://testingcf.jsdelivr.net/gh/Kele-Bingtang/static/user/avatar2.png",
        link: "http://notes.teek.top/",
      },
      {
        name: "Teeker Design Vue3",
        desc: "一个颜值强大、功能丰富、开箱即用的中后台管理系统解决方案",
        avatar: "https://testingcf.jsdelivr.net/gh/Kele-Bingtang/static/teek-design/20250807012638.png",
        link: "https://vue3-design-docs.teek.top/",
      },
    ], // 友情链接数据列表
    title: "${icon}友情链接", // 卡片标题
    emptyLabel: "暂无友情链接", // 友情链接为空时的标签
    limit: 5, // 一页显示的数量
    autoScroll: false, // 是否自动滚动
    scrollSpeed: 2500, // 滚动间隔时间，单位：毫秒。autoScroll 为 true 时生效
    autoPage: false, // 是否自动翻页
    pageSpeed: 4000, // 翻页间隔时间，单位：毫秒。autoPage 为 true 时生效
  },
});
yaml
---
tk:
  friendLink:
    enabled: true
    list:
      - name: Teeker
        desc: 朝圣的使徒，正在走向编程的至高殿堂！
        avatar: https://testingcf.jsdelivr.net/gh/Kele-Bingtang/static/user/avatar2.png
        link: http://notes.teek.top/
      - name: Teeker Design Vue3
        desc: 一个颜值强大、功能丰富、开箱即用的中后台管理系统解决方案
        avatar: https://testingcf.jsdelivr.net/gh/Kele-Bingtang/static/teek-design/20250807012638.png
        link: https://vue3-design-docs.teek.top/
    title: ${icon}友情链接
    emptyLabel: 暂无友情链接
    limit: 5
    autoScroll: false
    scrollSpeed: 2500
    autoPage: false
    pageSpeed: 4000
---
ts
import type { VpRouter } from "vitepress-theme-teek";

interface FriendLink {
  /**
   * 是否启用友情链接卡片
   *
   * @default true
   */
  enabled?: boolean;
  /**
   * 友情链接数据列表
   */
  list?: {
    /**
     * 友链名称
     */
    name: string;
    /**
     * 友链头像
     */
    avatar?: string;
    /**
     * 友链描述
     */
    desc?: string;
    /**
     * 友链链接
     */
    link?: string;
    /**
     * img 标签的 alt
     *
     * @default name
     */
    alt?: string;
  }[];
  /**
   * 卡片标题
   *
   * @default '${icon}友情链接'
   */
  title?: string | ((icon: string) => string);
  /**
   * 友情链接为空时的标签
   *
   * @default '暂无友情链接'
   */
  emptyLabel?: string;
  /**
   * 一页显示的数量
   *
   * @default 5
   */
  limit?: number;
  /**
   * 是否自动滚动
   *
   * @default false
   */
  autoScroll?: boolean;
  /**
   * 滚动间隔时间，单位：毫秒。autoScroll 为 true 时生效
   *
   * @default 2500 (2.5秒)
   */
  scrollSpeed?: number;
  /**
   * 是否自动翻页
   *
   * @default false
   */
  autoPage?: boolean;
  /**
   * 翻页间隔时间，单位：毫秒。autoPage 为 true 时生效
   *
   * @default 4000 (4秒)
   */
  pageSpeed?: number;
  /**
   * 点击标题时触发，可以通过 router.go 跳转到其他页面，也可以通过 window.open 打开新窗口
   *
   * @since v1.1.2
   */
  titleClick?: (router: VpRouter) => void;
}

docAnalysis ​

站点信息卡片配置。

ts
// .vitepress/config.mts
import { defineTeekConfig } from "vitepress-theme-teek/config";

const teekConfig = defineTeekConfig({
  docAnalysis: {
    enabled: true, // 是否启用站点信息卡片
    createTime: "2021-10-19", // 站点创建时间
    wordCount: true, // 是否开启文章页的字数统计
    readingTime: true, // 是否开启文章页的阅读时长统计
    // 访问量、访客数统计配置
    statistics: {
      provider: "busuanzi", // 网站流量统计提供商
      siteView: true, // 是否开启首页的访问量和排名统计
      pageView: true, // 是否开启文章页的浏览量统计
      tryRequest: false, // 如果请求网站流量统计接口失败，是否重试
      tryCount: 5, // 重试次数，仅当 tryRequest 为 true 时有效
      tryIterationTime: 2000, // 重试间隔时间，单位：毫秒，仅当 tryRequest 为 true 时有效
      permalink: true, // 是否只统计永久链接的浏览量，如果为 false，则统计 VitePress 默认的文档目录链接
    },
    // 自定义现有信息
    overrideInfo: [
      {
        key: "lastActiveTime",
        label: "活跃时间",
        value: (_, currentValue) => (currentValue + "").replace("前", ""),
        show: true,
      },
    ],
    // 自定义额外信息
    appendInfo: [{ key: "index", label: "序号", value: "天客 99" }],
  },
});
yaml
---
tk:
  docAnalysis:
    enabled: true
    createTime: 2021-10-19
    wordCount: true
    readingTime: true
    statistics:
      provider: "busuanzi"
      siteView: true
      pageView: true
    appendInfo:
      - key: "index"
        label: "序号"
        value: "天客 99"
---
ts
interface DocAnalysis {
  /**
   * 是否启用站点信息卡片
   *
   * @default true
   */
  enabled?: boolean;
  /**
   * 卡片标题
   *
   * @default '${icon}站点信息'
   */
  title?: string | ((icon: string) => string);
  /**
   * 项目创建时间
   */
  createTime?: string;
  /**
   * 是否开启文章页的字数统计
   *
   * @default true
   */
  wordCount?: boolean;
  /**
   * 是否开启文章页的阅读时长统计
   *
   * @default true
   */
  readingTime?: boolean;
  /**
   * 访问量、访客数统计配置
   */
  statistics?: {
    /**
     * 自建网站流量统计的 URL，支持的 URL 格式与提供商 provider 绑定
     */
    url?: string;
    /**
     * 网站流量统计提供商
     */
    provider?: "" | "busuanzi" | "vercount";
    /**
     * 是否开启首页的访问量和排名统计
     *
     * @default true
     */
    siteView?: boolean;
    /**
     * 是否开启文章页的浏览量统计
     *
     * @default true
     */
    pageView?: boolean;
    /**
     * 如果请求网站流量统计接口失败，是否重试，类型 boolean
     *
     * @default false
     */
    tryRequest?: boolean;
    /**
     * 重试次数，仅当 tryRequest 为 true 时有效
     *
     * @default 5
     */
    tryCount?: number;
    /**
     * 重试间隔时间，单位毫秒，仅当 tryRequest 为 true 时有效
     *
     * @default 2000
     */
    tryIterationTime?: number;
    /**
     * 是否只统计永久链接的浏览量，如果为 false，则统计 VitePress 默认的文档目录链接
     *
     * @default true
     */
    permalink?: boolean;
    /**
     * 自定义请求函数，返回 UvPvData 数据
     *
     * @param url 统计接口地址
     * @param createScriptFn 创建一个 script 标签的函数
     */
    requestFn?: (url: string | undefined, createScriptFn: typeof createScript) => UvPvData | Promise<UvPvData>;
  };
  /**
   * 自定义现有信息
   * originValue 为计算前的数据，currentValue 为计算后的数据（加单位的数据），针对 lastActiveTime 这些需要判断 N 分、N 时、N 天的 key，originValue 为具体的时间，需要自行计算
   */
  overrideInfo?: (Omit<PartialKey<DocAnalysisInfo, "label">, "value"> & {
    value?: (originValue: string | number, currentValue?: string | number) => string;
  })[];
  /**
   * 自定义额外信息，类型和 overrideInfo 一样
   * @default []
   */
  appendInfo?:
    | (Omit<DocAnalysisInfo, "key"> & { key: string })[]
    | (() => (Omit<DocAnalysisInfo, "key"> & { key: string })[]);
}

interface DocAnalysisInfo {
  /**
   * 站点信息唯一标识
   */
  key:
    | "totalPosts"
    | "weekAddNum"
    | "monthAddNum"
    | "runtime"
    | "totalWordCount"
    | "lastActiveTime"
    | "viewCount"
    | "visitCount"
    | string;
  /**
   * 站点信息标签
   */
  label: string;
  /**
   * 站点信息值的描述
   */
  value: string;
  /**
   * 是否显示在站点信息
   *
   * @default true
   */
  show?: boolean;
}

提示

如果想开启访问量、访客数统计，请使用 statistics.provider 选择网站流量统计提供商。

当想修改站点信息内置的信息时，可以使用 overrideInfo 配置项，该配置项是一个数组对象，对象的 key 为信息标识，value 是一个函数，接收两个参数 originValue 和 currentValue：

  • originValue：站点信息卡片的原始值，如创建时间为 2021-10-19
  • currentValue：站点信息卡片当前渲染的值，如创建时间渲染的值为 N 天前

比如想将 文章数目 改为 文章总数目：

ts
// .vitepress/config.mts
import { defineTeekConfig } from "vitepress-theme-teek/config";

const teekConfig = defineTeekConfig({
  docAnalysis: {
    overrideInfo: [{ key: "totalPosts", label: "文章总数目" }],
  },
});

比如想隐藏最后活动时间：

ts
// .vitepress/config.mts
import { defineTeekConfig } from "vitepress-theme-teek/config";

const teekConfig = defineTeekConfig({
  docAnalysis: {
    overrideInfo: [{ key: "lastActiveTime", show: false }],
  },
});

key 可选值如下：

  • totalPosts：文章总数
  • weekAddNum：近一周新增
  • monthAddNum：近一月新增
  • runtime：已运行时间
  • totalWordCount：本站总字数
  • lastActiveTime：最后活动时间
  • viewCount：本站被访问了
  • visitCount：本站曾来访过

获取网站访问量数据

如果你想要获取网站访问量数据，可以通过监听 Teek 触发的事件获取：

ts
window.addEventListener("views", (event: any) => {
  console.log("网站访问量数据", event.detail);
});

利用这个事件，你可以在站点信息卡片配置利用 appendInfo 来配置更多的访问量信息：

vue
<script setup lang="ts">
import type { TeekConfig } from "vitepress-theme-teek";
import Teek, { teekConfigContext, isClient } from "vitepress-theme-teek";
import { provide, ref } from "vue";

const teekConfig = ref<TeekConfig>({});

provide(teekConfigContext, teekConfig);

if (isClient) {
  window.addEventListener("views", (event: any) => {
    const { site_pv } = event.detail;

    // 设置站点信息
    teekConfig.value.docAnalysis = {
      appendInfo: [{ key: "siteUv", label: "网站访客数", value: site_pv }],
      // ... 其他配置项
    };
  });
}
</script>

<template>
  <Teek.Layout></Teek.Layout>
</template>
最近更新