Frontmatter 配置

frontmatter 支持基于页面的配置。在每个 Markdown 文件中，可以使用 frontmatter 配置来覆盖主题配置中的大部分选项。

首页配置

description

Teek 提供了 description 选项，用于在首页 Banner 展示一些描述信息，您可以通过 tk.description 或者 tk.banner.description 来配置首页的 description。

提示

description 获取优先级：tk.banner.description > banner.description > tk.description >。

yaml

---
layout: home

tk:
  description:
    - 故事由我书写，旅程由你见证，传奇由她聆听 —— 来自 Young Kbt
    - 积跬步以至千里，致敬每个爱学习的你 —— 来自 Evan Xu
    - 这一生波澜壮阔或是不惊都没问题 —— 来自 Weibw
---

features

Teek 提供了 features 选项，用于在首页展示一些功能介绍。

请通过 frontmatter.tk.features 配置 features，这样可以避免与 VitePress 的 features 冲突。

如果您是博客风格，你也可以通过 frontmatter.tk.banner.features 或 frontmatter.banner.features 配置 features。

features 获取优先级

文档风格：：frontmatter.tk.features > teekConfig.features
博客风格：frontmatter.tk.banner.features > frontmatter.banner.features > teekConfig.banner.features

文档风格的 features 配置内容请看 Doc Feature。
博客风格风格的 features 配置内容请看 Banner Feature。

文档风格博客风格

yaml

tk:
  teekHome: false
  features:
    - title: 快速开发
      details: 提供了完整版参考代码和精简版开发代码
      image: /feature/ui.svg
      highlights:
        - title: 从零安装：运行 <code>pnpm add vitepress-theme-teek vitepress</code> 以从 NPM 下载 Teek 主题。
        - title: 现有模板：运行 <code>git clone https://github.com/Kele-Bingtang/vitepress-theme-teek-docs-template.git</code> 以下载当前文档模板。

    - title: 拥有丰富的 Features，并持续更新
      details: 满足大部分开发场景。
      image: /feature/features.svg
      features:
        - title: 最新流行稳定技术栈
          icon: icon-github
          details: 基于 Vue3.2、TypeScript、Vite4、Pinia、Element-Plus 等最新技术栈开发
          link: /guide/intro

        - title: 简单上手 & 学习
          icon: <svg viewBox="0 0 24 24" width="1.2em" height="1.2em"><path fill="currentColor" d="m23 12l-7.071 7.071l-1.414-1.414L20.172 12l-5.657-5.657l1.414-1.414L23 12zM3.828 12l5.657 5.657l-1.414 1.414L1 12l7.071-7.071l1.414 1.414L3.828 12z"></path></svg>
          details: 项目结构清晰，代码简单、易读。

        - title: 规范工程化工作流
          icon: /teek-logo-mini.svg
          details: 配置 Eslint、Prettier、Husky、Commitlint、Lint-staged 规范前端工程代码规范。

        - title: 完善的打包优化方案
          icon: icon-github
          details: 内置规范的打包目录，提供打包压缩功能，减少打包体积。

        - title: 丰富的组件
          icon: /teek-logo-mini.svg
          details: 提供丰富的通用组件、业务组件。
          link: /ecosystem/components

        - title: 常用 Hook 函数
          icon: icon-gitee
          details: 提供丰富的组件、常用 Hooks 封装，实现复用思想，减少重复开发，提高效率。

        - title: 个性化主题配置
          icon: icon-xiangce
          details: 提供主题颜色配置，暗黑、灰色、色弱等模式切换。
          link: /guide/theme-enhance

        - title: 多种布局配置
          icon: /teek-logo-mini.svg
          details: 提供多种布局、标签栏切换，布局显隐，满足大部分场景。

        - title: 项目权限管控
          icon: /teek-logo-mini.svg
          details: 采用 RBAC 权限管控，提供菜单、路由及按钮粗细粒度权限管理方案

        - title: 国际化
          icon: /teek-logo-mini.svg
          details: 内置常用国际化转换函数，支持自定义国际化切换，

        - title: IFrame 嵌入
          icon: /teek-logo-mini.svg
          details: 提供 IFrame 嵌入、缓存功能，支持门户 Portal 布局。

        - title: 自定义指令
          icon: /teek-logo-mini.svg
          details: 内置多种 Vue 自定义指令，提供傻瓜式指令一键注册功能。

        - title: Axios 封装
          icon: /teek-logo-mini.svg
          details: 基于 Axios 封装常用请求模块，内置业务拦截器、异常拦截器。

        - title: 多种图标类型
          icon: /teek-logo-mini.svg
          details: 支持 IconFont、SVG、Iconify 等多种图标类型渲染。
          link: /guide/icon-use

    - title: 布局
      details: 多种布局、标签栏切换，布局组件显隐
      image: /feature/layout.svg
      highlights:
        - title: 六大布局
          icon: /teek-logo-mini.svg
          details: 内置纵向、经典、横向、分栏、混合、子系统六大布局切换

        - title: 深色模式
          icon: /teek-logo-mini.svg
          details: 可以自由切换浅色模式与深色模式

        - title: 主题色切换
          icon: /teek-logo-mini.svg
          details: 支持自定义主题色并允许用户在预设的主题颜色之间切换

        - title: 布局组件
          icon: /teek-logo-mini.svg
          details: 支持图标、面包屑、导航栏等组件显隐，内置缓存功能，记住用户的布局配置

yaml

---
layout: home

tk:
  features:
    - title: 指南
      details: Hd Security 使用指南说明
      link: /01.指南/
      images: /img/web.png
    - title: 设计
      description: Hd Security 设计思路说明
      link: /design/
      images: /img/ui.png
    - title: API
      description: Hd Security 所有的 API 介绍
      link: /07.API/01.API - 登录/
      images: /img/other.png
---

主题配置

在首页 index.md 的 frontmatter，可以覆盖 config 主题配置的首页相关选项：

banner 横幅
topArticle 精选文章
category 分类
tag 标签
friendLink 友情链接
docAnalysis 站点分析
post 文章列表
article 文章信息（作者、创建时间、分类、标签等）
page 分页
...

在首页 index.md 的 frontmatter 中配置时，建议以 tk 开头，然后是主题配置的选项，举个示例：

yaml

---
tk:
  banner:
    enabled: true
    bgStyle: fullImg
    imgSrc:
      - /img/bg1.jpg
      - /img/bg2.jpg
  category:
    enabled: true
    limit: 7
  article:
    showIcon: false
  page:
    pageSize: 20
---

这些配置将会覆盖 config 主题配置中的对应选项。

提示

不以 tk 开头也是可以的，Teek 支持的 frontmatter 既可以是 tk.xx.xx，也可以是 xx.xx，其中 tk.xx.xx 优先级更高。

文章页配置

在文章页的 frontmatter，可以覆盖 config 主题配置的文章页相关选项：

author 作者信息
article 文章信息（作者、创建时间、分类、标签等）
breadcrumb 面包屑
articleShare 文章分享
appreciation 赞赏
...

在文章页的 frontmatter 中配置时，直接填写 config 主题配置的对应选项，举个示例：

yaml

---
author:
  name: TianKe
  link: https://github.com/Kele-Bingtang/vitepress-theme-teek
article:
  showCategory: true
breadcrumb:
  separator: -
---

文章配置

除了支持覆盖主题配置的选项，Teek 还提供了以下额外的选项：

yaml

---
title: 标题
date: 2025-03-07 01:16:28
permalink: /pages/b1ad26
categories:
  - 分类 1
  - 分类 2
tags:
  - 标签 1
titleTag: 原创
top: true
sticky: 1
sidebar: true
article: true
comment: true
description: 文章摘要
coverImg: /img/web.png
docAnalysis: true
inCatalogue: true
autoTitle: true
articleUpdate: true
inHomePost: true
---

title

类型：string

页面标题，将作为一级标题显示在页面上。

支持填写 HTML 标签 v1.3.0：

基础 HTMLBadge 组件TkTitleTag 组件TkIcon 图标

yaml

---
title: frontmatter 配置 <span style="color:#395AE3">原创</span>
---

yaml

---
title: frontmatter 配置 <Badge type="tip" text="原创" />
---

yaml

---
title: frontmatter 配置 <TkTitleTag type="tip" text="原创" position="right" />
---

yaml

---
title: frontmatter 配置 <TkIcon icon="simple-icons:gitee" color="var(--tk-theme-color)" />
---

除此之外，frontmatter.title 支持所有的基础 HTML 以及已经全局注册的 Vue 组件。

如何注册全局 Vue 组件

在 .vitepress/theme/index.ts 中的 enhanceApp 函数中进行，通过 app.component("your componentName", your component) 方法进行注册。

date

类型：string

页面创建时间，将作为创建时间显示在首页的文章列表、文章页顶部。

permalink

类型：string

页面永久链接，将作为页面访问的 URL 路径，该配置项由 vitepress-plugin-permalink 提供。

titleTag v1.1.0

用于给标题添加 原创、转载、优质、推荐 等自定义标记。

添加了标题标记的文章，在文章列表、文章页、归档页、目录页的文章标题都会显示此标记。

除此之外，也可以直接在 frontmatter.title 前后通过 <TkTitleTag> 组件的方式添加标题标记。

标题后标题前

yaml

---
title: frontmatter 配置 <TkTitleTag type="tip" text="原创" position="right" />
---

yaml

---
title: <TkTitleTag type="tip" text="原创" position="right" /> frontmatter 配置
---

top

类型：boolean
默认值：false

标记为精选文章。如果为 true，则在首页的精选文章卡片中显示，如果多个文章都设置了 top: true，则按照 date 进行排序（最新时间在上面）。

sticky

类型：number

文章置顶，设置了此项将在首页文章列表中处于置顶位置，如果同时设置了 top: true，则在精选文章卡片的序号添加高亮背景色，背景色请看主题配置 - tagColor。

类型：boolean
默认值：true

侧边栏，true 表示显示侧边栏。设置为 false 表示不显示侧边栏。

article

类型：boolean
默认值：true

非文章页的标记，非文章页如目录页、关于、友情链接等自定义页面，需要设置此项。设置之后这个页面将被认定为非文章页，不显示面包屑和文章信息（作者、时间、分类、标签等），不显示在如下模块中：

首页的文章列表
归档页
文章最近更新栏

comment

类型：boolean
默认值：true

评论功能，true 表示显示评论区。设置为 false 表示不显示评论区。

description

类型：string
默认值：null

文章摘要，将显示在首页的文章列表。

coverImg

类型：string
默认值：null

封面图片，将显示在首页的文章列表。

inCatalogue

类型：boolean
默认值：true

目录页，true 表示允许 Markdown 文档纳入目录里。设置为 false 表示不允许，该配置项由 vitepress-plugin-catalogue 插件提供。

docAnalysis

类型：boolean
默认值：true

站点分析，true 表示允许站点信息功能对 Markdown 文档进行数据分析和统计。设置为 false 表示不允许，该配置项由 vitepress-plugin-doc-analysis 插件提供。

autoTitle

类型：boolean
默认值：true

如果 Markdown 不设置一级标题，在访问页面的时候自动添加一级标题。设置为 false 表示不允许自动添加一级标题，该配置项由 vitepress-plugin-md-h1 插件提供。

一级标题获取优先级：frontmatter.title > 文件名

articleUpdate v1.2.0

类型：boolean
默认值：true

是否在文章底部显示最近更新栏。

inHomePost v1.3.0

类型：boolean
默认值：true

Markdown 文档是否在首页的文章列表中显示。

sidebarSort v1.4.1

类型：number
默认值：9999

侧边栏排序，值越小越靠前，设置此项将覆盖文件名序号进行排序，由 vitepress-plugin-sidebar-resolve 插件提供。

sidebarPrefix v1.4.1

类型：string
默认值：""

侧边栏标题前缀，可以添加 HTML 如 iconfont 图标，由 vitepress-plugin-sidebar-resolve 插件提供。

sidebarSuffix v1.4.1

类型：string
默认值：""

侧边栏标题后缀，可以添加 HTML 如 iconfont 图标，由 vitepress-plugin-sidebar-resolve 插件提供。

articleBanner v1.5.0

类型：boolean
默认值：true

是否显示文章页的 Banner 栏，仅当没有侧边栏的文章页生效。

coverColor v1.5.0

类型：string
默认值：""

文章页 Banner 的背景色，仅当 articleBanner 为 true 时生效。

功能页配置

上述的 frontmatter 配置为通用配置，适用于任何 Markdown 文档。

除此之外，还有一些针对功能页的 frontmatter 局部配置，详细请看目录页配置和功能页配置。

Frontmatter 配置 ​

首页配置 ​

description ​

features ​

主题配置 ​

文章页配置 ​

文章配置 ​

title ​

date ​

permalink ​

categories ​

tags ​

titleTag v1.1.0 ​

top ​

sticky ​

sidebar ​

article ​

comment ​

description ​

coverImg ​

inCatalogue ​

docAnalysis ​

autoTitle ​

articleUpdate v1.2.0 ​

inHomePost v1.3.0 ​

sidebarSort v1.4.1 ​

sidebarPrefix v1.4.1 ​

sidebarSuffix v1.4.1 ​

articleBanner v1.5.0 ​

coverColor v1.5.0 ​

功能页配置 ​

Frontmatter 配置

首页配置

description

features

主题配置

文章页配置

文章配置

title

date

permalink

categories

tags

titleTag v1.1.0

top

sticky

sidebar

article

comment

description

coverImg

inCatalogue

docAnalysis

autoTitle

articleUpdate v1.2.0

inHomePost v1.3.0

sidebarSort v1.4.1

sidebarPrefix v1.4.1

sidebarSuffix v1.4.1

articleBanner v1.5.0

coverColor v1.5.0

功能页配置