How to enable pagination for the theme and display pagination data
Usage
- A simple blog post data statistics
-> index.md (or xxx.md)
---
layout: page
---Pages with layout: page will be injected with blog post pagination data. If used only this way, pagination functionality will not be triggered, and all posts will be displayed on a single page.
- A standard pagination
[page] can be replaced with other values
---
layout: page
---import fs from 'fs'
export default {
paths() {
const limit = 12 // Item count of each page
const files = fs
.readdirSync('docs/posts')
.filter((file) => !/^\[[^]*]\]\./.test(file))
const total = Math.ceil(files.length / limit)
return Array.from({ length: total }).map((_, index) => {
const current = index + 1
const page = current === 1 ? 'index' : `page-${current}`
return { params: { page, current, limit } }
})
},
}Based on VitePress's dynamic-routes feature, pagination interfaces can be dynamically generated. By default, it will use index.md and page-[n].md to generate pagination. If you need to modify this, please refer to the formatPage configuration below.
- Configure multiple paginations
The theme supports configuring multiple paginations. Configure pagination data where needed using the above method, then add the pagination property in the configuration.
Example: Currently there are two directories posts and lib that need pagination, and you also want to display filtered articles on the homepage.
First, configure index.md according to method 1 to display filtered articles on the homepage.
Then configure [page].md and [page].paths.ts in the posts and lib directories according to method 2. Note that you need to change readdirSync('docs/posts') to the current directory.
Finally, add the following to the configuration:
-> .vitepress/config.ts
pagination: [
{
match: (path) => /^\/($|index|page-)/.test(path),
filter: (page) => page.display === 'home', // Will match pages containing `display: home` in frontmatter
},
{
dir: 'posts',
prev: 'Previous',
next: 'Next',
},
{
dir: 'lib',
prev: 'Previous',
next: 'Next',
},
],pagination Configuration
For cases with only one pagination, pagination supports passing an object; for cases with multiple paginations, pagination supports passing an array.
group
- Type:
number - Default:
5
The number of pagination buttons displayed in the pagination component.
prev
- Type:
string - Default:
Prev
The text for the previous page button in the pagination component.
next
- Type:
string - Default:
Next
The text for the next page button in the pagination component.
dir
- Type:
string ｜ array - Default: srcDir
The directory for collecting pagination data. When you have multiple directories that need pagination, it's best to set this value to the directory name, otherwise you need to configure match.
match
- Type:
function
When you need pagination for multiple directories, you can use this function to match the directories that need pagination. This function receives a parameter path, representing the current page's path. If it returns true, it means the current pagination path matches the current configuration.
filter
- Type:
function
The filter function for the current pagination.
sort
- Type:
function
The sort function for the current pagination. By default, it will sort by the date field in the frontmatter.
formatPage
- Type:
function
A function to format pagination button links. If you change the page parameter name in [page].paths.ts, you need to add this function to format pagination links.
Type Declaration
export interface PaginationItem {
/**
* Pagination collapses when the total page count exceeds this value
*
* @default 5
*/
group?: number
/**
* The prev button text
*
* @default 'Prev'
*/
prev?: string
/**
* The next button text
*
* @default 'Next'
*/
next?: string
/**
* Directory that requires statistical pagination data. **It is best to have a unique value throughout the pagination config**
*
* default value: [srcDir](https://vitepress.dev/reference/site-config#srcdir)
*
* When your blog requires multiple pagination, you need to set dir to the current directory name
*/
dir?: MaybeArray<string>
/**
* Customize how to match the path of route and current config
*
* If your pagination data is incorrect, you should increase it
*/
match?: (path: string) => boolean
/**
* Customize how to filter the posts data
*/
filter?: (item: PostsItem) => boolean
/**
* Customize how to sort the posts data
*/
sort?: (a: PostsItem, b: PostsItem) => number
/**
* Custom pagination jump link data
*/
formatPage?: (page: number) => DefaultTheme.NavItemWithLink
}
export interface PaginationParams {
/**
* File name for generating [dynamic-routes](https://vitepress.dev/guide/routing#dynamic-routes)
*
* @example n === 1 ? 'index' : `page-${n}`
*
* If you are not using the recommended format, you need to custom `pagination -> formatPage` match
*/
page: string
/**
* Current pagination, starting from 1
*
* @requires
*/
current: number
/**
* Item count of each page
*
* @requires
*/
limit: number
}