VitePress Theme Minimalism 使用文档

指引

假设你已经在使用 VitePress，并根据安装步骤将主题复制到 .vitepress 中，当你首次通过 pnpm dev 运行时，会根据 posts 目录中的所有 Markdown 文件在根目录中生成 index.md page1.md page2.md 等文件，这些 Markdown 文件将作为引导页或文章列表。

因此，你需要在 posts 目录（可以在 usePosts 中通过参数修改，详见安装）中创建你的文章，每个 Markdown 文件代表一篇文章，同时需要在每个 Markdown 文件的顶部添加 Frontmatter 用于描述文章标题、发布时间等等。

其余目录的 Markdown 文件，则作为文档，在 .vitepress/config.ts 中为其配置 Sidebar 即可。

安装

TIP

若全新安装，可以直接克隆仓库作为模板

安装依赖：pnpm add fast-glob gray-matter less medium-zoom remove-markdown @waline/client -D
复制文件：将仓库中的 src 文件夹复制到你的 VitePress 根目录中；将 .vitepress/theme/index.ts 复制到你的 VitePress 中
导入主题类型：导入 defineConfigWithTheme 与 ThemeConfig
导入文章列表：导入 usePosts 方法，接受一个对象，其中包含以下配置项

参数名	默认值	备注
pageSize	10	每页文章数
index	true	是否将文章列表设置为主页
srcDir	posts	文章文件夹
outDir	/	文章列表、归档/分类/标签页输出路径
lang	zh	语言
autoExcerpt	0	自动摘要，值为摘要字数
prev	true	上一页
next	true	下一页

主题配置：themeConfig 对象
- posts - 文章列表，通过 usePosts 方法生成
- page - 文章列表配置项
  - max - 分页器最大页数，超出后显示首页与尾页按钮，默认为 5
  - pinned - 置顶文章文本描述，默认为 [置顶]
  - outDir - 文章列表、分类/归档/标签页输出路径（需与 usePosts 方法中保持一致，用于分类与标签页路由）
- comment - 评论配置项
  - serverURL - Waline 服务端地址，填入后会开启评论功能，部署方式见 Waline 快速上手
  - 更多配置项参考 Waline 组件属性
- ads - 自定义广告
- adsense - Google Adsense

// .vitepress/config.ts
import { defineConfigWithTheme } from 'vitepress';
import type { ThemeConfig } from '../src/types';
import { usePosts } from '../src/composables/usePosts';

const { posts, rewrites } = await usePosts({ pageSize: 7, index: false, folder: 'posts' });
export default defineConfigWithTheme<ThemeConfig>({
  rewrites,
  themeConfig: {
    posts,
	page: {
      max: 5,
      pinned: '[置顶]'
    },
    comment: {
      serverURL: 'https://domain.com'
    },
    ads: {},
    adsense: {}
  }
});

更新

复制最新版仓库 src 文件夹覆盖旧版本 src 文件夹即可

主页模式

WARNING

切换模式时，请先将根目录下的 index.md page1.md page2.md 等 Markdown 文件删除，再次运行项目

主题提供了两种主页模式，可以将文章列表作为主页（参考演示站1），也可以将引导页作为主页（参考演示站2），可以通过 usePosts 方法的 index 参数来切换

引导页

当将参数设置为 false 时，从 posts 文件夹中生成的文章列表将命名为 page1.md page2.md page3.md ，同时会生成引导页命名为 index.md ，通过修改 Home 组件的 props 来修改引导页中的内容

imgUrl: 主页图片
title: 主页标题
desc: 主页描述
links: 对象数组，url 为链接，text 为按钮文字

markdown

---
layout: page
---
<Home imgUrl="/profile.png" title="只抄" desc="Less is more." :links="[{ url: 'https://github.com/izhichao/vitepress-theme-minimalism', text: 'Github ->' }]" />

当引导页作为主页时，建议将 Posts 目录单独添加到 nav 中，可以进行如下配置

// .vitepress/config.ts
export default defineConfigWithTheme<ThemeConfig>({
  themeConfig: {
    nav: [
      { text: 'Home', link: '/' },
      { text: 'Posts', link: '/page1' }
    ]
  }
}

文章列表

当将参数设置为 true 时（默认为 true，可以省略），从 posts 文件夹中生成的文章列表将命名为 index.md page2.md page3.md ，与上一种模式相比，直接省去了引导页，将 page1.md 命名为 index.md，nav 配置如下

// .vitepress/config.ts
export default defineConfigWithTheme<ThemeConfig>({
  themeConfig: {
    nav: [
      { text: 'Home', link: '/' }
    ]
  }
}

归档 / 分类 / 标签

如果文章有设置分类或者标签，会根据 outDir 的自动生成 category.md 与 tags.md
归档页面需要新建 archives.md
Group 组件的 type 可选 archives category tags 分别对应归档 / 分类 / 标签页面

yaml

---
title: 归档
layout: page
---
<Group type='archives' lang='zh' />

在 nav 配置归档 / 分类 / 标签链接

// .vitepress/config.ts
export default defineConfigWithTheme<ThemeConfig>({
  themeConfig: {
    nav: [
      { text: 'Archives', link: '/archives' },
      { text: 'Category', link: '/category' },
      { text: 'Tags', link: '/tags' }
    ]
  }
}

frontmatter

参数名	必填	默认值	备注
title	自动生成	文件名	文章标题
datetime	自动生成	文件创建时间	发布时间
permalink	自动生成	srcDir + 6位随机字符	永久链接
outline		config.ts 中设置的值	目录标题的级别
order			置顶文章排序，数字越小越靠前，不能为 0
pinned			置顶文章文本描述
category			分类
tags			标签
prev	若在 usePosts 中开启，会自动生成		上一页
next	若在 usePosts 中开启，会自动生成		下一页

yaml

---
title: VitePress Theme Minimalism 使用文档
datetime: '2023/10/01 10:00:00'
permalink: /posts/minimalism
outline: deep
order: 1
pinned: '[置顶]'
category: 分类
tags: 
  - 标签
prev:
  text: 上一篇文章标题
  link: /posts/aaaaaa
next:
  text: 下一篇文章标题
  link: /posts/bbbbbb
---

用户代码片段

VS Code 可以通过设置用户代码片段，快速生成 Frontmatter
VS Code 左下角 设置 -> User Snippets -> markdown.json，将以下代码粘贴到 {} 中
在 .md 文件中，通过输入 md 即可快速生成

json

"minimalism-setup": {
  "prefix": "md",
  "body": [
    "---",
    "title: ${TM_FILENAME_BASE}",
    "datetime: '${CURRENT_YEAR}-${CURRENT_MONTH}-${CURRENT_DATE} ${CURRENT_HOUR}:${CURRENT_MINUTE}:${CURRENT_SECOND}'",
    "outline: deep",
    "category: ${0}",
    "tags: ",
    "  - ${1}",
    "---",
    "",
    "# ${TM_FILENAME_BASE}"
  ],
  "description": "minimalism-setup"
}

自定义广告

若数组中的元素为 IAd 对象，广告将按顺序展示
若数组中的元素为 IAd 数组，则在该数组中随机展示其中一个广告

interface IAd {
  title: string;
  img: string;
  link?: string;
}

interface IAds {
  sidebarNavBefore?: (IAd | IAd[])[];
  sidebarNavAfter?: (IAd | IAd[])[];
  asideOutlineBefore?: (IAd | IAd[])[];
  asideOutlineAfter?: (IAd | IAd[])[];
  docBefore?: (IAd | IAd[])[];
  docAfter?: (IAd | IAd[])[];
}

client：Adsense 账号的 client
其余值为广告单元的 slot 的值
除此之外，还需要在 head 中添加 ['script', {}, "window['addAds'] = function(){\n (adsbygoogle = window.adsbygoogle || []).push({});\n}"]

interface IAdsense {
  client?: string;
  sidebarNavBefore?: string;
  sidebarNavAfter?: string;
  asideOutlineBefore?: string;
  asideOutlineAfter?: string;
  docBefore?: string;
  docAfter?: string;
}

VitePress Theme Minimalism 使用文档 ​

指引 ​

安装 ​

更新 ​

主页模式 ​

引导页 ​

文章列表 ​

归档 / 分类 / 标签 ​

frontmatter ​

用户代码片段 ​

自定义广告 ​

Adsense ​

预览: