VitePress Theme Minimalism 使用文档

发布于2023年10月02日

更新于2025年12月18日

标签

警告

本文档已废弃，不再更新，请查看最新文档

指引

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

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

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

安装

提示

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

安装依赖：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 文件夹即可

主页模式

警告

切换模式时，请先将根目录下的 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 Documentation

发布于2023年10月02日

更新于2025年12月18日

分类建站

标签

博客

Guide

Assuming you are already using VitePress and copied the theme to .vitepress according to the Install step, when you run it for the first time via pnpm dev, it will generate index.md page1.md page2.md etc. These Markdown files will be used as the leading page or posts list.

Therefore, you need to create your posts in the posts directory (which can be modified by parameters in usePosts, see Install for more details), each Markdown file represents a post, and you need to add Frontmatter at the top of each Markdown file to describe the post title, publication time, etc.

The Markdown files in the rest of the directory are used as documents, and you can configure a Sidebar for them in the .vitepress/config.ts.

Install

提示

If it's a new install, you can just clone the repository as a template

Install dependencies：pnpm add fast-glob gray-matter less medium-zoom remove-markdown @waline/client -D
Copy file: Copy the src folder to your VitePress root directory; copy the vitepress/theme/index.ts to your VitePress
Import theme type: Import defineConfigWithTheme and ThemeConfig
Import posts list: Imports the usePosts method, accepts an object containing the following configuration items

Key	Default	Description
pageSize	10	number of posts per page
index	true	if or not to set the posts list as home page
srcDir	posts	posts folder name
outDir	/	posts list, archives/category/tags page output paths
lang	zh	language
autoExcerpt	0	automatic excerpt, value is the number of summary words
prev	true	previous post
next	true	next post

Theme Config: themeConfig Object
- posts - posts list, generated by the usePosts method
- page - posts list configuration item
  - max - max number of pagination, the first and last page buttons will be displayed when exceeding the number, default is 5
  - pinned - the description of pinned post, default is [置顶]
  - outDir - posts lites, posts list, archives/category/tags page output paths (needs to be consistent with the usePosts method for category and tags routing)
- comment - comment configuration item
  - server - Waline server address, once filled in, will enable the comment function. The deployment method can be found in Waline Get Started
  - More configuration items, refer to Waline Component Props
- ads - Customized Ads
- adsense - Google Adsense

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

Update

Copy the latest version of the repository src folder and overwrite the old version src folder

Home Page Mode

警告

When switching modes, please first delete Markdown files such as index.md page1.md page2.md in the root directory and run the project again.

The theme provide two homepage modes, you can use posts list as the homepage(refer to Demo1), you can also use the leading page as the homepage(refer to Demo2), You can switch through the index parameter of the usePosts method

Leading Page

When the parameter is set to false,ths posts list generated from the posts folder will be named page1.md page2.md page3.md, and the leading page will be named index.md, modify the content of the leading page by modifying the props of the Home component.

imgUrl: image url
title
desc: description
links: object array，including url and text

markdown

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

When the leading page as hompage,it is recommended to add the Posts directory separately to the nav,which can be configured as follows.

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

Posts List

When the parameter is set to true (defaults to true, can be omitted), the posts list generated from the posts will be named index.md page2.md page3.md , Compared to the pervious mode, the leading page is directly removedand page1.md is named index.md, the nav configuration is as follows.

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

Archives / Category / Tags

If the post has categorie or tags, category.md and tags.md will be automatically generated according to outDir.
The archives page requires a new archives.md
The type of the Group component can be archives category tags which corresponds to the archives/category/tags pages respectively.

yaml

---
title: Archives
layout: page
---
<Group type='archives' lang='en' />

Configure Archives and Tags links in nav

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

frontmatter

参数名	必填	默认值	备注
title	auto generate	filename	post title
datetime	auto generate	file birthtime	publishing time
permalink	auto generate	srcDir + 6 random Base-16 digits	permaent link
outline		the value set in config.ts	level of directory
order			order of pinned posts, the smaller the number the higher the priority, can not be 0
pinned			the description of pinned post
category			category
tags			tags
prev	If true in usePosts, it will auto generate		pervios post
next	If true in usePosts, it will auto generate		next post

yaml

---
title: VitePress Theme Minimalism Documentation
datetime: '2023/10/01 10:00:00'
permalink: /posts/minimalism
outline: deep
order: 1
pinned: '[Pinned]'
category: Category
tags: 
  - Tag
prev:
  text: Previous Post
  link: /posts/aaaaaa
next:
  text: Next Post
  link: /posts/bbbbbb
---

User Snippets

VS Code can quickly generate Frontmatter by setting User Snippets.
VS Code Settings -> User Snippets -> markdown.json , paste the following code into {}
In the .md file, type md to quickly generate

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

Customized Ads

If the elements in the array are IAd objects, the ads will be displayed in order.
If the elements in the array are IAd arrays, one of the advertisements will be displayed randomly in the array.

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: the client of the Adsense account
The rest of the values are the values of the slot of the ad unit
In addition to this, you need to add the ['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 ​

VitePress Theme Minimalism Documentation ​

Guide ​

Install ​

Update ​

Home Page Mode ​

Leading Page ​

Posts List ​

Archives / Category / Tags ​

frontmatter ​

User Snippets ​

Customized Ads ​

Adsense ​

VitePress Theme Minimalism 使用文档

指引

安装

更新

主页模式

引导页

文章列表

归档 / 分类 / 标签

frontmatter

用户代码片段

自定义广告

Adsense

VitePress Theme Minimalism Documentation

Guide

Install

Update

Home Page Mode

Leading Page

Posts List

Archives / Category / Tags

frontmatter

User Snippets

Customized Ads

Adsense