文章

置顶

置顶文章需要在 Frontmatter 中开启，为文章设置 order 属性就可以将其置顶，设置的数字即排序，越小越靠前，但不能为0

pinned 为置顶文章的文本描述，默认为 HOT，在此修改只对当前文章生效

---
order: 1
pinned: '置顶'
---

如果你想要修改所有置顶文章的文本描述，需要前往 .vitepress/config.ts 文件中，修改 pinned 属性

.vitepress/config.ts

export default defineConfigWithTheme<ThemeConfig>({
  themeConfig: {
	page: {
      pinned: '置顶'
    }
  }
});

草稿 / 删除

在文章的 Frontmatter 中设置 draft: true 或者 deleted: true 时，会将文章添加到 excludePosts 数组中

提示

draft 与 deleted 本质上没有任何区别，都是添加到 srcExclude 中在构建时排除。

添加两种别名纯粹是用来区分未完成的草稿和已删除的文章。

draft: true
# 或者
deleted: true

在调用 usePosts 生成文章列表时，会同时得到 excludePosts 数组，将它添加到解构到 srcExculde 中，即可在构建时直接排除。

.vitepress/config.ts

const { excludePosts } = await usePosts();

export default defineConfig<ThemeConfig>({
  srcExclude: [...excludePosts]
});

隐藏

危险

隐藏文章仅仅在文章列表中隐藏，直接访问 URL 时仍可访问，如果需要彻底隐藏，请设置为草稿！

在文章的 Frontmatter 中设置 hidden: true 即可将文章隐藏，隐藏后文章将不再出现在列表中。

同时设置 head 避免搜索引擎收录（主题会自动添加）

hidden: true
head:
  - - meta
    - name: robots
      content: noindex, nofollow

通过 usePosts 可以获取到隐藏的文章列表 hiddenPosts，最后在 sitemap 中将这些文章排除

.vitepress/config.ts

const { hiddenPosts } = await usePosts();

export default defineConfig<ThemeConfig>({
  sitemap: {
    hostname: 'https://example.com',
    transformItems: (items) => {
      return items.filter((item) => !hiddenPosts.has(item.url.replace(/\.html$/, '')));
    }
  }
});

加密

在 .vitepress/config.ts 中导入并调用 installEncryptedMarkdown 函数

.vitepress/config.ts

import { installEncryptedMarkdown } from '../src/utils/encryptedMarkdown.ts';

export default defineConfig<ThemeConfig>({
  transformPageData(pageData) {
    delete pageData.frontmatter.password;
  },
  markdown: {
    config: (md) => {
      installEncryptedMarkdown(md); 
    }
  }
});

在文章的 Frontmatter 中设置 password: 123456 即可开启加密

password: 123456

永久链接

提示

永久链接仅对博客文章目录（默认为 posts）下的文章生效，无侵入性，不会改变其他目录文章的 URL。

永久链接是博客的重要组成部分，使用永久链接后，文章的 URL 不再与 Markdown 文件名相关联，方便后期修改文件名。

此功能默认开启，主题会自动在 Frontmatter 中为每一篇文章生成一个 6 位的 ID，永久链接固定前缀 posts 与 ID 组成。例如，ID 为 123456，文章的链接便是 /posts/123456

修改 ID

当然，你也可以通过在 Frontmatter 中直接填写文章的 ID 来达到修改永久链接的目的，例如下面这样，链接就变成了 /posts/vitepress

id: vitepress

修改前缀

默认情况下，所有的永久链接前缀都为 posts，你可以在 usePosts 方法导入文章列表时，通过 permalink 参数可将其修改，此时，文章的链接就变成了 /custom/vitepress

提示

永久链接的前缀无需与文章目录相同，文件夹名为 posts，前缀仍然可以是 custom

.vitepress/config.ts

const { posts } = await usePosts({ permalink: 'custom' });

关闭永久链接

如果你想将永久链接彻底关闭，则可以将 permalink 设置为 '' 空字符串，此时链接将回退回默认的 Markdown 文件路径。

单篇文章

提示

Frontmatter 中的 permalink 优先级最高！

如果只想为一篇文章设置永久链接，只需要在该文章的 Frontmatter 中配置 permalink

permalink: my-first-post

此时，该文章的链接便为 /my-first-post

摘要

摘要会在文章列表的标题下方展示，分为自动摘要和手动摘要，其中手动摘要优先级高于自动摘要

摘要的内容会将文章的各级标题、代码块移除，仅展示文章正文内容

提示

1.无论摘要内容多少，在文章列表中 PC 端最多展示一行；移动端最多展示两行

2.优先级：description -> <!--more--> -> 自动摘要

自动摘要

通过 usePosts 方法的 excerpt 参数配置，设置后，所有文章都会自动摘要，值为摘要的字数。

默认为 0 不开启。

.vitepress/config.ts

const { posts } = await usePosts({ excerpt: 150 });

手动摘要 <!--more-->

除了自动摘要外，你还可以在 Markdown 中手动添加 <!--more--> 标记，用于指示摘要的结束位置，标记前的内容为摘要内容，不受自动摘要的字数限制。

描述 description

如果有为文章设置描述，那描述的内容也将称为摘要。

通过在 Frontmatter 中填写 description 即可开启。

description: '自定义摘要内容'

meta

VitePress 会自动将 Frontmatter 中的 description 添加到 <meta> 标签中，但前面两种摘要不会自动添加，我们需要通过 transformPageData 钩子将它添加进去。

.vitepress/config.ts

const { posts, descriptionMap } = await usePosts({ excerpt: 150 });

export default defineConfig<ThemeConfig>({
  transformPageData(pageData) {
    const { frontmatter, description } = pageData;
    const { id } = frontmatter;

    if (!description) {
      pageData.description = descriptionMap.get(id) as string;
    }
  }
});

上一页 / 下一页

主题提供了两种方式开启上一页与下一页，两者的样式与实现原理完全不同，各有优缺点，可以自行选择其中一种方式开启。

• 组件版：本主题自定义的组件，通过 #doc-after 插槽插入页面底部。
  • 优点：开启方便，单次设置即可，无需改动 Markdown 文件
  • 缺点：仅对博客文章生效，文档页则会使用默认主题的上一页与下一页，风格割裂
• 默认版：VitePress 默认主题自带的主题，自动向 Frontmatter 中添加 prev 与 next 实现。
  • 优点：风格统一
  • 缺点：每次编辑时间、标题以及永久链接时，会同步更新前后文章的 Frontmatter，造成文章编辑时间以及 Commit 记录混乱。

组件版

组件版需要在 ThemeLayout.vue 中导入并添加到 #doc-after 插槽中，PrevNext 组件接收三个 props

• prevText：上一页文本描述（默认为 “上一篇”）
• nextText：下一页文本描述（默认为 “下一篇”）
• showPinned：是否包含置顶文章（默认包含）

.vitepress/theme/Layout.vue

<template>
  <Layout>
    <template #doc-after>
      <PrevNext />
    </template>
  </Layout>
</template>

<script lang="ts" setup>
import DefaultTheme from 'vitepress/theme';
import PrevNext from '../../src/components/PrevNext.vue';

const { Layout } = DefaultTheme;
</script>

默认版

默认版的上一页 / 下一页功能沿用了 VitePress 默认主题的上下页链接功能，你可以在每一篇文章的 Frontmatter 中直接配置。

---
prev:
  text: 上一篇文章标题
  link: /posts/prev
next:
  text: 下一篇文章标题
  link: /posts/next
---

如果你希望为所有的文章开启上一页 / 下一页功能，可以在 usePosts 生成文章列表时，传入 nav 参数，主题会自动为你的所有文章添加 Frontmatter

.vitepress/config.ts

const { posts, hiddenPosts, excludePosts, rewrites } = await usePosts({ nav: true });

Frontmatter

所有属性

Frontmatter 位于 Markdown 文件的最开头，声明了当前文章的各种属性。

提示

斜体 为 VitePress 默认主题自带的 Frontmatter

参数名	必填	默认值	备注
draft			设置为 true 时，自动添加到 srcExclude 中，排除构建
hidden			设置为 true 时，隐藏文章（仅在文章列表中隐藏）
order			置顶文章排序，数字越小越靠前，不能为 0
pinned			置顶文章文本描述
password			文章密码
id	自动生成	6 位随机字符	文章 ID
title	自动生成	文件名	文章标题
datetime	自动生成	文件创建时间	发布时间
permalink			永久链接
outline		config.ts 中设置的值	目录标题的级别
description			文章描述（自定义摘要内容）
category			分类
tags			标签
prev	若在 usePosts 中设置 nav: true，会自动生成		上一页
next	同上		下一页
head			HTML 中的 head

完整示例

---
draft: true
deleted: true
hidden: true
order: 1
pinned: '置顶'
password: 123456
id: 123456
title: VitePress Theme Minimalism 使用文档   
datetime: '2024/01/01 10:00:00'
permalink: /posts/minimalism
outline: deep
description: '自定义摘要内容'
category: 分类 A
tags: 
  - 标签 A
  - 标签 B
prev:
  text: 上一篇文章标题
  link: /posts/prev
next:
  text: 下一篇文章标题
  link: /posts/next
head:
  - - meta
    - name: robots
      content: 'noindex, nofollow'
---