文章配置

articleAnalyze

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

提示

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

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

config.mts

// .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, // 是否展示标签
  },
});

首页 index.md

---
tk:
  articleAnalyze:
    showIcon: true
    dateFormat: yyyy-MM-dd hh:mm:ss
    showInfo: true
    showAuthor: true
    showCreateDate: true
    showUpdateDate: false
    showCategory: false
    showTag: false
---

文章页 xxx.md

---
articleAnalyze:
  showIcon: true
  dateFormat: yyyy-MM-dd hh:mm:ss
  showInfo: true
  showAuthor: true
  showCreateDate: true
  showUpdateDate: false
  showCategory: false
  showTag: false
---

更多配置项

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 可以将文章信息传送到指定位置，仅限在文章页生效，默认在文章页顶部。

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

config.mts

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

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

文章页 xxx.md

---
tk:
  articleAnalyze:
    teleport:
      selector: h1
      position: after
      className: h1-bottom-info
---

breadcrumb

面包屑配置。

config.mts

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

const teekConfig = defineTeekConfig({
  breadcrumb: {
    enabled: true, // 是否启用面包屑
    showCurrentName: false, // 面包屑最后一列是否显示当前文章的文件名
    separator: "/", // 面包屑分隔符
  },
});

文章页 xxx.md

---
tk:
  breadcrumb:
    enabled: true
    showCurrentName: false
    separator: /
---

更多配置项

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 默认尺寸，则该配置项失效

config.mts

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

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

文章页 xx.md

---
pageStyle: segment-nav
---

appreciation

赞赏功能配置。

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

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

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

文章页底部

// .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
    },
  },
});

文章页底部 Popper

// .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
    },
  },
});

文章页大纲栏下方

// .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
    },
  },
});

更多配置项

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 配置来覆盖全局配置。

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

articleShare

文章分享配置。

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

config.mts

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

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

文章页 xx.md

---
articleShare:
  enabled: true
  text: 分享此页面
  copiedText: 链接已复制
  query: false
  hash: false
---

更多配置项

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 容器添加提示，使用场景如超过半年的文章自动提示文章内容可能已过时。

config.mts

// .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;
  },
});

类型

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;
}

articleBottomTip v1.3.4

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

config.mts

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

const teekConfig = defineTeekConfig({
  articleBottomTip: () => {
    return {
      type: "tip",
      // title: "声明",
      text: `<p>作者：Teek</p>
             <p>版权：此文章版权归 Teek 所有，如有转载，请注明出处!</p>
             <p style="margin-bottom: 0">链接：可点击右上角分享此页面复制文章链接</p>
            `,
    };
  },
});

类型

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;
}

articleUpdate v1.2.0

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

config.mts

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

const teekConfig = defineTeekConfig({
  articleUpdate: {
    enabled: true, // 是否启用文章最近更新栏
    limit: 3, // 文章最近更新栏显示数量
  },
});

文章页1 xx.md

---
articleShare: false # 禁用文章分享栏
---

文章页2 xx.md

---
articleShare:
  enabled: true
  limit: 3
---

更多配置项

interface ArticleUpdate {
  /**
   * 是否启用文章最近更新栏
   *
   * @since v1.2.1
   * @default true
   */
  enabled?: boolean;
  /**
   * 文章最近更新栏显示数量
   *
   * @since v1.2.1
   * @default 3
   */
  limit?: number;
}

:::