VitePress 极简主题：文章配置

前置条件

使用以下功能，需要在 .vitepress/config.ts 导入并调用 themeTransformPageData 与 themeMdPlugin；否则部分功能将无法生效！

.vitepress/config.ts

import { themeTransformPageData } from '../src/utils/themeTransformPageData.ts';
import { themeMdPlugin } from '../src/utils/themeMdPlugin.ts';

export default defineConfig<ThemeConfig>({
  transformPageData(pageData, ctx) {
    themeTransformPageData(pageData, ctx);
  },
  markdown: {
    config: (md) => {
      md.use(themeMdPlugin);
    }
  }
});

置顶

提示

置顶的文章无论在哪个目录中，都会展示在首页与自身板块！

置顶文章需要在 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$/, '')));
    }
  }
});

加密

在文章的 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: '自定义摘要内容'

上一页 / 下一页

上一页 / 下一页功能由 PrevNext 组件提供，需要在 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>

Frontmatter

所有属性

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

提示

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

参数名	描述	备注
draft / deleted	构建时排除（自动添加到 srcExclude 中）	布尔类型：true / false
hidden	隐藏文章（仅在文章列表中隐藏）	布尔类型：true / false
order	置顶文章排序	数字类型，数字越小越靠前，不能为 0
pinned	置顶文章标签	字符串类型，默认为 HOT
index	首页展示（针对其他文章目录）	布尔类型：true / false，默认 false
password	文章密码	字符串类型
id	文章 ID	自动生成，默认为 6 位随机字符，支持自定义
title	文章标题	自动生成，默认为文件名，支持自定义
datetime	发布时间	自动生成，默认为文件创建时间，支持自定义
permalink	永久链接	可选，默认按 文件夹 + ID 自动生成，例如 /posts/minimalism
description	文章描述	描述将作为自定义摘要内容，优先级高于自动摘要
category	分类	一篇文章只能有一个分类
tags	标签	一篇文章可以有多个标签
outline	目录层级	VitePress 自带属性
head	HTML 中的 head

完整示例

---
draft: true
deleted: true
hidden: true
order: 1
pinned: '置顶'
index: true
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
head:
  - - meta
    - name: robots
      content: 'noindex, nofollow'
---