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 为按钮文字
---
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
分别对应归档 / 分类 / 标签页面
---
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 中开启,会自动生成 | 下一页 |
---
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
即可快速生成
"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[])[];
}
Adsense
- 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;
}
预览: