VitePress Theme Minimalism Documentation

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

TIP

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

1. Install dependencies：pnpm add fast-glob gray-matter less medium-zoom remove-markdown @waline/client -D
2. Copy file: Copy the src folder to your VitePress root directory; copy the vitepress/theme/index.ts to your VitePress
3. Import theme type: Import defineConfigWithTheme and ThemeConfig
4. 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

5. 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

WARNING

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

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

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

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

4. 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

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

"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[])[];
}

Adsense

• 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;
}