Skip to content
关注微信公众号ouo.io - 縮短網址也可以賺錢

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

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

  1. 安装依赖pnpm add fast-glob gray-matter less medium-zoom remove-markdown @waline/client -D
  2. 复制文件:将仓库中的 src 文件夹复制到你的 VitePress 根目录中;将 .vitepress/theme/index.ts 复制到你的 VitePress 中
  3. 导入主题类型:导入 defineConfigWithThemeThemeConfig
  4. 导入文章列表:导入 usePosts 方法,接受一个对象,其中包含以下配置项
参数名默认值备注
pageSize10每页文章数
indextrue是否将文章列表设置为主页
srcDirposts文章文件夹
outDir/文章列表、归档/分类/标签页输出路径
langzh语言
autoExcerpt0自动摘要,值为摘要字数
prevtrue上一页
nexttrue下一页
  1. 主题配置themeConfig 对象

    • posts - 文章列表,通过 usePosts 方法生成

    • page - 文章列表配置项

      • max - 分页器最大页数,超出后显示首页与尾页按钮,默认为 5
      • pinned - 置顶文章文本描述,默认为 [置顶]
      • outDir - 文章列表、分类/归档/标签页输出路径(需与 usePosts 方法中保持一致,用于分类与标签页路由 )
    • comment - 评论配置项

    • ads - 自定义广告

    • adsense - Google Adsense

js
// .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 中,可以进行如下配置

js
// .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 配置如下

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

归档 / 分类 / 标签

  1. 如果文章有设置分类或者标签,会根据 outDir 的自动生成 category.mdtags.md
  2. 归档页面需要新建 archives.md
  3. Group 组件的 type 可选 archives category tags 分别对应归档 / 分类 / 标签页面
yaml
---
title: 归档
layout: page
---
<Group type='archives' lang='zh' />
  1. 在 nav 配置归档 / 分类 / 标签链接
js
// .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位随机字符永久链接
outlineconfig.ts 中设置的值目录标题的级别
pinnedfalse置顶
category分类
tags标签
prev若在 usePosts 中开启,会自动生成上一页
next若在 usePosts 中开启,会自动生成下一页
yaml
---
title: VitePress Theme Minimalism 使用文档
datetime: '2023/10/01 10:00:00'
permalink: /posts/minimalism
outline: deep
pinned: true
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 数组,则在该数组中随机展示其中一个广告
ts
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}"]
ts
interface IAdsense {
  client?: string;
  sidebarNavBefore?: string;
  sidebarNavAfter?: string;
  asideOutlineBefore?: string;
  asideOutlineAfter?: string;
  docBefore?: string;
  docAfter?: string;
}
ouo.io - 縮短網址也可以賺錢
你认为这篇文章怎么样?
  • 0
  • 0
  • 0
  • 0
  • 0
  • 0

预览:

评论
  • 按正序
  • 按倒序
  • 按热度
Powered by Waline v3.1.3