Vitepress Theme Teek

主题

Teeker2025-03-08
3138
13.5m

文章配置 ​

articleBanner v1.5.0 ​

文章页顶部 Banner，仅在没有侧边栏的文章页生效，如果您还不了解什么是 ArticleBanner ，请查看 ArticleBanner 示例。

文章页 Banner 的背景色支持封面图和背景色 2 个类型：

  1. 封面图：读取 frontmatter.coverImg 的属性，如果获取不到，则使用配置文件的 articleBanner.defaultCoverImg，如果依然获取不到，则走背景色逻辑
  2. 背景色：读取 frontmatter.coverColor 的属性，如果获取不到，则使用配置文件的 articleBanner.defaultCoverColor，如果依然获取不到，则使用主题色作为默认的背景色

为了防止封面图过于亮导致文字无法看见，Teek 会使用背景色来降低封面图的亮色，因此 最合理的使用是同时配置封面图和背景色，且背景色的值应该和封面图颜色一致。

提示

Teek 提供的封面图样式会将封面图稍微放大，然后添加模糊效果，这样也许不满足你的需求，你可以自行修改样式。

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

const teekConfig = defineTeekConfig({
  articleBanner: {
    enabled: true, // 是否启用单文章页 Banner
    showCategory: true, // 是否展示分类
    showTag: true, // 是否展示标签
    defaultCoverImg: "", // 默认封面图
    defaultCoverBgColor: "", // 默认封面背景色，优先级低于 defaultCoverImg
  },
});
yaml
---
articleBanner:
  enabled: true
  showCategory: true
  showTag: true
  coverImg: ""
  coverBgColor: ""
---
ts
interface ArticleBanner {
  /**
   * 是否启用单文章页 Banner
   *
   * @default false
   */
  enabled?: boolean;
  /**
   * 是否展示分类
   *
   * @default true
   */
  showCategory?: boolean;
  /**
   * 是否展示标签
   *
   * @default true
   */
  showTag?: boolean;
  /**
   * 默认封面图
   */
  defaultCoverImg?: string;
  /**
   * 默认封面背景色，优先级低于 defaultCoverImg
   */
  defaultCoverBgColor?: string;
}

如果您想修改 ArticleBanner 的面包屑配置，如隐藏面包屑，请往下参阅 breadcrumb 的配置。

如果您想隐藏 ArticleBanner 的作者、日期、字数、阅读时长等信息，请往下参阅 articleAnalyze 的配置。

提示

使用了 ArticleBanner，则 articleAnalyze 的 showCategory 和 showTag 配置将无效。如果想隐藏分类和标签，直接通过 articleBanner.showCategory 和 articleBanner.showTag 配置。

articleAnalyze ​

文章信息分析配置，分别作用在首页和文章页。

提示

如果在 config.mts 中配置，则首页和文章页都生效。

文章页的图片点击可以预览，但是当图片元素的 class 里存在 no-preview，则不会触发预览，这对于兼容 Teek 的图片相关插件有所帮助。

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

const teekConfig = defineTeekConfig({
  articleAnalyze: {
    showIcon: true, // 作者、日期、分类、标签、字数、阅读时长、浏览量等文章信息的图标是否显示
    dateFormat: "yyyy-MM-dd hh:mm:ss", // 文章日期格式，首页和文章页解析日期时使用
    showInfo: true, // 是否展示作者、日期、分类、标签、字数、阅读时长、浏览量等文章信息，分别作用于首页和文章页
    showAuthor: true, // 是否展示作者
    showCreateDate: true, // 是否展示创建日期
    showUpdateDate: false, // 是否展示更新日期，仅在文章页显示
    showCategory: false, // 是否展示分类
    showTag: false, // 是否展示标签
  },
});
yaml
---
tk:
  articleAnalyze:
    showIcon: true
    dateFormat: yyyy-MM-dd hh:mm:ss
    showInfo: true
    showAuthor: true
    showCreateDate: true
    showUpdateDate: false
    showCategory: false
    showTag: false
---
yaml
---
articleAnalyze:
  showIcon: true
  dateFormat: yyyy-MM-dd hh:mm:ss
  showInfo: true
  showAuthor: true
  showCreateDate: true
  showUpdateDate: false
  showCategory: false
  showTag: false
---
ts
interface Article {
  /**
   * 作者、日期、分类、标签、字数、阅读时长、浏览量等文章信息的图标是否显示
   *
   * @default true
   */
  showIcon?: boolean;
  /**
   * 文章日期格式，首页和文章页解析日期时使用
   *
   * @default 'yyyy-MM-dd'
   */
  dateFormat?: "yyyy-MM-dd" | "yyyy-MM-dd hh:mm:ss" | ((date: string) => string);
  /**
   * 是否展示作者、日期、分类、标签、字数、阅读时长、浏览量等文章信息，分别作用于首页和文章页
   * 如果 showInfo 为数组，则控制在哪里显示，如 ["post"] 只在首页的 Post 列表显示基本信息；如果为 boolean 值，则控制基本信息是否展示，如 false 则在首页和文章页都不显示基本信息
   *
   * @default true
   */
  showInfo?: boolean | ArticleInfoPosition[];
  /**
   * 是否展示作者
   *
   * @default true
   */
  showAuthor?: boolean | ArticleInfoPosition[];
  /**
   * 是否展示创建日期
   *
   * @default true
   */
  showCreateDate?: boolean | ArticleInfoPosition[];
  /**
   * 是否展示更新日期，仅在文章页显示
   *
   * @default false
   */
  showUpdateDate?: boolean;
  /**
   * 是否展示分类
   *
   * @default false
   */
  showCategory?: boolean | ArticleInfoPosition[];
  /**
   * 是否展示标签
   *
   * @default false
   */
  showTag?: boolean | ArticleInfoPosition[];
  /**
   * 指定文章信息的传送位置，仅限在文章页生效，默认在文章页顶部
   */
  teleport?: {
    /**
     * 指定需要传送的元素选择器
     */
    selector?: string;
    /**
     * 指定传送到元素的位置，before 在元素前，after 在元素后
     *
     * @default 'after'
     */
    position?: "before" | "after";
    /**
     * 指定一个 class 名，如果传送的位置和其他元素太接近，可以利用 class 来修改 margin
     *
     * @default teleport
     */
    className?: string;
  };
  /**
   * 文章页图片查看器配置
   */
  imageViewer?: Partial<ImageViewerProps>;
}

配置项中，teleport 可以将文章信息传送到指定位置，仅限在文章页生效，默认在文章页顶部。

如将文章信息传到一级标题下面：

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

const teekConfig = defineTeekConfig({
  articleAnalyze: {
    teleport: {
      selector: "h1",
      position: "after",
      className: "h1-bottom-info",
    },
  },
});
yaml
---
tk:
  articleAnalyze:
    teleport:
      selector: h1
      position: after
      className: h1-bottom-info
---

面包屑配置。

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

const teekConfig = defineTeekConfig({
  breadcrumb: {
    enabled: true, // 是否启用面包屑
    showCurrentName: false, // 面包屑最后一列是否显示当前文章的文件名
    separator: "/", // 面包屑分隔符
    homeLabel: "首页", // 鼠标悬停首页图标的提示文案
  },
});
yaml
---
tk:
  breadcrumb:
    enabled: true
    showCurrentName: false
    separator: /
    homeLabel: 首页
---
ts
interface Breadcrumb {
  /**
   * 是否启用面包屑
   *
   * @default true
   */
  enabled?: boolean;
  /**
   * 面包屑最后一列是否显示当前文章的文件名
   *
   * @default false
   */
  showCurrentName?: boolean;
  /**
   * 面包屑分隔符
   *
   * @default '/'
   */
  separator?: string;
  /**
   * 鼠标悬停首页图标的提示文案
   *
   * @default '首页'
   */
  homeLabel?: string;
}

pageStyle ​

  • 类型："default" | "card" | "segment" | "card-nav" | "segment-nav"
  • 默认值：default

文章页的样式风格，default 为 VitePress 原生风格，card 为单卡片风格，segment 为片段卡片风格，card-nav 和 segment-nav 会额外修改导航栏样式。

提示

在文章页的 frontmatter 配置 pageStyle，可以针对不同的文章页开启不同的样式风格。

如果使用了主题增强的布局尺寸切换，且布局尺寸不是 VitePress 默认尺寸，则该配置项失效

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

const teekConfig = defineTeekConfig({
  pageStyle: "segment-nav",
});
yaml
---
pageStyle: segment-nav
---

appreciation ​

赞赏功能配置。

赞赏功能提供 3 个位置选择：

  • doc-after：文章页底部，评论区上方
  • doc-after-popper：文章页底部，评论区上方，以弹框形式出现 v1.3.0
  • aside-bottom：文章页大纲栏下方

每个位置分别有不同的配置项。

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

const teekConfig = defineTeekConfig({
  appreciation: {
    position: "doc-after", // 赞赏位置
    // 赞赏配置
    options: {
      icon: "weChatPay", // 赞赏图标，内置 weChatPay 和 alipay
      expandTitle: "打赏支持", // 展开标题，支持 HTML
      collapseTitle: "下次一定", // 折叠标题，支持 HTML
      content: `<img src='/teek-logo-large.png'>`, // 赞赏内容，支持 HTML
      expand: false, // 是否默认展开，默认 false
    },
  },
});
ts
// .vitepress/config.mts
import { defineTeekConfig } from "vitepress-theme-teek/config";

const teekConfig = defineTeekConfig({
  appreciation: {
    position: "doc-after-popper", // 赞赏位置
    // 赞赏配置
    options: {
      trigger: "click", // 触发方式
      icon: "weChatPay", // 赞赏图标，内置 weChatPay 和 alipay
      title: "打赏支持", // 展开标题，支持 HTML
      content: `<img src='/teek-logo-large.png'> <img src='/teek-logo-large.png'>`, // 赞赏内容，支持 HTML
    },
  },
});
ts
// .vitepress/config.mts
import { defineTeekConfig } from "vitepress-theme-teek/config";

const teekConfig = defineTeekConfig({
  appreciation: {
    position: "aside-bottom", // 赞赏位置
    // 赞赏配置
    options: {
      title: `<span style="color: var(--tk-theme-color)">欢迎打赏支持</span>`, // 赞赏标题，支持 HTML
      content: `<img src='/teek-logo-large.png'>`, // 赞赏内容，支持 HTML
    },
  },
});
ts
import type { IconProps } from "vitepress-theme-teek";

type Appreciation<T extends keyof AppreciationPosition = ""> = {
  /**
   * 赞赏位置
   */
  position?: T;
  /**
   * 赞赏配置
   */
  options?: AppreciationPosition[T];
};

type AppreciationPosition = {
  "": object;
  "aside-bottom": {
    /**
     * 赞赏标题，支持 HTML
     */
    title?: string;
    /**
     * 赞赏内容，支持 HTML
     */
    content?: string;
  };
  "doc-after": {
    /**
     * 自定义按钮 HTML
     */
    buttonHtml?: string;
    /**
     * 赞赏图标，内置 weChatPay 和 alipay
     */
    icon?: IconProps["icon"] | "weChatPay" | "alipay";
    /**
     * 展开标题，支持 HTML
     */
    expandTitle?: string;
    /**
     * 折叠标题，支持 HTML
     */
    collapseTitle?: string;
    /**
     * 赞赏内容，支持 HTML
     */
    content?: string;
    /**
     * 是否默认展开
     *
     * @default false
     */
    expand?: boolean;
  };
  "doc-after-popper": {
    /**
     * 触发方式
     *
     * @default "click"
     */
    trigger?: "click" | "hover";
    /**
     * 自定义按钮 HTML
     */
    buttonHtml?: string;
    /**
     * 赞赏图标，内置 weChatPay 和 alipay
     */
    icon?: IconProps["icon"] | "weChatPay" | "alipay";
    /**
     * 赞赏标题，支持 HTML
     */
    title?: string;
    /**
     * 赞赏内容，支持 HTML
     */
    content?: string;
  };
};

Teek 内置两个 icon：

  • weChatPay：微信支付图标
  • alipay：支付宝图标

如果您需要自定义图标，则通过 icon 配置项传入。

赞赏功能同样支持在单个 Markdown 的 frontmatter 配置来覆盖全局配置。

yaml
---
appreciation:
  position: doc-after
  options:
    icon: weChatPay
    expandTitle: 打赏支持
    collapseTitle: 下次一定
    content: "<img src='/teek-logo-large.png'>"
    expand: false
---

articleShare ​

文章分享配置。

本功能主要是在文章右侧的大纲栏添加一个按钮，点击后自动复制文章链接到剪贴板。

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

const teekConfig = defineTeekConfig({
  articleShare: {
    enabled: true, // 是否开启文章链接分享功能
    text: "分享此页面", // 分享按钮文本
    copiedText: "链接已复制", // 复制成功文本
    query: false, // 是否包含查询参数
    hash: false, // 是否包含哈希值
  },
});
yaml
---
articleShare:
  enabled: true
  text: 分享此页面
  copiedText: 链接已复制
  query: false
  hash: false
---
ts
import type { IconProps } from "vitepress-theme-teek";

interface ArticleShare {
  /**
   * 是否开启文章链接分享功能
   *
   * @default false
   */
  enabled?: boolean;
  /**
   * 分析按钮图标
   */
  icon?: IconProps["icon"];
  /**
   * 分享按钮文本
   *
   * @default '分享此页面'
   */
  text?: string;
  /**
   * 复制成功图标
   */
  copiedIcon?: IconProps["icon"];
  /**
   * 复制成功文本
   *
   * @default '链接已复制'
   */
  copiedText?: string;
  /**
   * 是否包含查询参数
   *
   * @default false
   */
  query?: boolean;
  /**
   * 是否包含哈希值
   *
   * @default false
   */
  hash?: boolean;
}

articleTopTip ​

在每个文章页顶部显示 VitePress 容器添加提示，使用场景如超过半年的文章自动提示文章内容可能已过时。

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

const teekConfig = defineTeekConfig({
  articleTopTip: (frontmatter, localeIndex, page) => {
    const tip: Record<string, string> = {
      type: "warning",
      text: "文章发布较早，内容可能过时，阅读注意甄别。",
    };

    // 大于半年，添加提示
    const longTime = 6 * 30 * 24 * 60 * 60 * 1000;
    if (frontmatter.date && Date.now() - new Date(frontmatter.date).getTime() > longTime) return tip;
  },
});
ts
import type { PageData } from "vitepress";
import type { VpContainerProps } from "@teek/components/common/VpContainer/src/vpContainer";

interface TeekConfig {
  /**
   * 文章页顶部使用 VitePress 容器添加提示
   *
   * @param frontmatter 文档 frontmatter
   * @param localeIndex 当前国际化语言
   * @param page 文章信息，即 useData().page 的信息
   */
  articleTopTip?: (
    frontmatter: PageData["frontmatter"],
    localeIndex: string,
    page: PageData
  ) => VpContainerProps | undefined;
}

如果全局开启了该功能，但希望在某个文章页隐藏该功能，有两种方式实现：

  • frontmatter.articleTopTip 设置为 false
  • 在 config.ts 中配置 articleTopTip 时，第一个参数为 frontmatter，因此可以在函数自定义判断，如 if(frontmatter.topTip === false) return，那么就可以在 Markdown 的 frontmatter.topTip 设置为 false

articleBottomTip v1.3.4 ​

在每个文章页顶部显示 VitePress 容器添加提示，使用场景如添加文章版权声明。

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

const teekConfig = defineTeekConfig({
  articleBottomTip: frontmatter => {
    if (typeof window === "undefined") return;

    const hash = false;
    const query = false;
    const { origin, pathname, search } = window.location;
    const url = `${origin}${frontmatter.permalink ?? pathname}${query ? search : ""}${hash ? location.hash : ""}`;
    const author = "Teek";

    return {
      type: "tip",
      // title: "声明", // 可选
      text: `<p>作者：${author}</p>
             <p style="margin-bottom: 0">链接：<a href="${decodeURIComponent(url)}" target="_blank">${decodeURIComponent(url)}</a></p>
             <p>版权：此文章版权归 ${author} 所有，如有转载，请注明出处!</p>
            `,
    };
  },
});
ts
import type { PageData } from "vitepress";
import type { VpContainerProps } from "@teek/components/common/VpContainer/src/vpContainer";

interface TeekConfig {
  /**
   * 文章页底部使用 VitePress 容器添加提示
   *
   * @param frontmatter 文档 frontmatter
   * @param localeIndex 当前国际化语言
   * @param page 文章信息，即 useData().page 的信息
   */
  articleBottomTip?: (
    frontmatter: PageData["frontmatter"],
    localeIndex: string,
    page: PageData
  ) => VpContainerProps | undefined;
}

如果全局开启了该功能，但希望在某个文章页隐藏该功能，有两种方式实现：

  • frontmatter.articleBottomTip 设置为 false
  • 在 config.ts 中配置 articleBottomTip 时，第一个参数为 frontmatter，因此可以在函数自定义判断，如 if(frontmatter.bottomTip === false) return，那么就可以在 Markdown 的 frontmatter.bottomTip 设置为 false

articleUpdate v1.2.0 ​

文章页底部的最近更新栏配置。

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

const teekConfig = defineTeekConfig({
  articleUpdate: {
    enabled: true, // 是否启用文章最近更新栏
    limit: 3, // 文章最近更新栏显示数量
  },
});
yaml
---
articleShare: false # 禁用文章分享栏
---
yaml
---
articleShare:
  enabled: true
  limit: 3
---
ts
interface ArticleUpdate {
  /**
   * 是否启用文章最近更新栏
   *
   * @since v1.2.1
   * @default true
   */
  enabled?: boolean;
  /**
   * 文章最近更新栏显示数量
   *
   * @since v1.2.1
   * @default 3
   */
  limit?: number;
}
最近更新