Collections Configuration
Overview
Collections are the core concept in the theme for organizing and managing documents. Each collection points to a specific folder under the source directory, managing all Markdown files within it as a logical unit.
Through flexible collection configuration, you can easily build various content systems:
- Blog - Personal essays and technical shares
- Column - Thematic series articles
- User Manual - Product usage documentation
- Notes - Study notes and knowledge organization
- Product Documentation - Complete project documentation
- Knowledge Base - Team knowledge management system
Collections are primarily divided into two types to accommodate different content organization needs:
posttype: Suitable for fragmented content with weak inter-article relationships, such as blogs, columns, etc.doctype: Suitable for structured documentation with closely related content, such as user manuals, product documentation, knowledge bases, etc.
Configuration Location
Collection configuration can be done in either .vuepress/config.ts or the standalone plume.config.ts file.
Basic Configuration
Assume your project uses the following directory structure:
Project Structure
post-1.md
post-2.md
intro.md
variable.md
types.md
The corresponding collection configuration example is as follows:
.vuepress/config.ts
import { defineUserConfig } from 'vuepress'
import { plumeTheme } from 'vuepress-theme-plume'
export default defineUserConfig({
theme: plumeTheme({
// Collection Configuration
collections: [
// Register post-type collection for blog functionality
{ type: 'post', dir: 'blog', title: 'Blog' },
// Register doc-type collection for TypeScript documentation functionality
{ type: 'doc', dir: 'typescript', title: 'TypeScript Notes', sidebar: 'auto' }
],
})
}).vuepress/plume.config.ts
import { defineThemeConfig } from 'vuepress-theme-plume'
export default defineThemeConfig({
// Collection configuration in standalone config file
collections: [
{ type: 'post', dir: 'blog', title: 'Blog' },
{ type: 'doc', dir: 'typescript', title: 'TypeScript Notes', sidebar: 'auto' }
],
})Multi-language Configuration
For multi-language projects, you can configure collections separately for each language within the locales field:
Multi-language Project Structure
blog
typescript
blog
typescript
.vuepress/config.ts
import { defineUserConfig } from 'vuepress'
import { plumeTheme } from 'vuepress-theme-plume'
export default defineUserConfig({
theme: plumeTheme({
locales: {
'/': {
// Chinese collection configuration
collections: [
{ type: 'post', dir: 'blog', title: 'Blog' },
{ type: 'doc', dir: 'typescript', title: 'TypeScript Notes', sidebar: 'auto' }
],
},
'/en/': {
// English collection configuration
collections: [
{ type: 'post', dir: 'blog', title: 'Blog' },
{ type: 'doc', dir: 'typescript', title: 'TypeScript Note', sidebar: 'auto' }
],
}
}
})
}).vuepress/plume.config.ts
import { defineThemeConfig } from 'vuepress-theme-plume'
export default defineThemeConfig({
locales: {
'/': {
// Chinese collection configuration
collections: [
{ type: 'post', dir: 'blog', title: 'Blog' },
{ type: 'doc', dir: 'typescript', title: 'TypeScript Notes', sidebar: 'auto' }
],
},
'/en/': {
// English collection configuration
collections: [
{ type: 'post', dir: 'blog', title: 'Blog' },
{ type: 'doc', dir: 'typescript', title: 'TypeScript Note', sidebar: 'auto' }
],
}
}
})Post Collection Details
Post collections are designed specifically for fragmented content like blogs and columns, providing a complete article management system:
Core Features
- Article List Page - Supports article pinning, cover images, excerpt display, personal information, etc.
- Article Categories Page - Automatically generates categories based on directory structure
- Article Tags Page - Flexible tag management
- Article Archives Page - Organizes content by time dimension
Configuration Example
import { defineThemeConfig } from 'vuepress-theme-plume'
export default defineThemeConfig({
collections: [
// Blog collection configuration
{
type: 'post',
dir: 'blog',
title: 'Blog',
link: '/blog/', // List page link
linkPrefix: '/article/', // Article link prefix
postCover: 'top', // Cover image position
autoFrontmatter: { permalink: true }, // Auto frontmatter
},
// Interview column configuration
{
type: 'post',
dir: 'interview',
title: 'Interview Column',
link: '/interview/', // List page link
}
]
})Doc Collection Details
Doc collections are suitable for structured documentation, emphasizing logical relationships between content:
Core Features
- Sidebar Navigation - Provides clear document structure navigation
- Auto-generated Table of Contents - Intelligently generates sidebar based on file structure
- Multi-level Nesting Support - Supports complex document hierarchy structures
Configuration Example
import { defineThemeConfig } from 'vuepress-theme-plume'
export default defineThemeConfig({
collections: [
// TypeScript Notes - Auto-generated sidebar
{
type: 'doc',
dir: 'typescript',
title: 'TypeScript Notes',
sidebar: 'auto'
},
// Python Notes - Manually configured sidebar
{
type: 'doc',
dir: 'python',
title: 'Python Notes',
sidebar: [
{ text: 'Basic Syntax', link: 'basic' },
{
text: 'API Documentation',
items: [
{ text: 'asyncio', link: 'asyncio' }
]
},
'advanced' // Shorthand form
]
}
]
})Configuration Type Declarations
Base Collection Configuration
/* Collection configuration array */
type ThemeCollections = ThemeCollectionItem[]
/* Single collection item */
type ThemeCollectionItem = ThemePostCollection | ThemeDocCollection
/* Collection common configuration */
interface ThemeBaseCollection {
/**
* Collection type
* - `post`: Article list (blog, column)
* - `doc`: Structured documentation (notes, knowledge base)
*/
type: 'post' | 'doc'
/**
* Document directory (relative to source directory)
*/
dir: string
/**
* Article link prefix
*/
linkPrefix?: string
/**
* Collection title (used for breadcrumb navigation)
*/
title: string
/**
* Tag color theme
* @default 'colored'
*/
tagsTheme?: 'colored' | 'gray' | 'brand'
/**
* Auto-generate frontmatter
*/
autoFrontmatter?: AutoFrontmatterOptions | false
}Post Collection Specific Configuration
interface ThemePostCollection extends ThemeBaseCollection {
type: 'post'
/**
* Include file patterns (glob pattern)
* @default ['**\/*.md']
*/
include?: string[]
/**
* Exclude file patterns (glob pattern)
* @default []
*/
exclude?: string[]
/**
* Pagination configuration
*/
pagination?: false | number | {
/**
* Number of articles per page
* @default 15
*/
perPage?: number
}
/**
* Article list page link
* @default '/{dir}/'
*/
link?: string
/**
* Whether to enable article list page
* @default true
*/
postList?: boolean
/**
* Whether to enable tags page
* @default true
*/
tags?: boolean
/**
* Tags page link
* @default '/{link}/tags/'
*/
tagsLink?: string
/**
* Tags page text
*/
tagsText?: string
/**
* Whether to enable archives page
* @default true
*/
archives?: boolean
/**
* Archives page link
* @default '/{link}/archives/'
*/
archivesLink?: string
/**
* Archives page text
*/
archivesText?: string
/**
* Whether to enable categories feature
* @default true
*/
categories?: boolean
/**
* Categories page link
* @default '/{link}/categories/'
*/
categoriesLink?: string
/**
* Categories page text
*/
categoriesText?: string
/**
* Categories expand depth
* @default 'deep'
*/
categoriesExpand?: number | 'deep'
/**
* Categories list transformation function
*/
categoriesTransform?: (categories: PostsCategoryItem[]) => PostsCategoryItem[]
/**
* Article cover image configuration
* @default 'right'
*/
postCover?: PostsCoverLayout | PostsCoverStyle
/**
* Profile configuration
*/
profile?: ProfileOptions | false
/**
* Social account configuration
*/
social?: SocialLink[] | false
}
/* Article category item */
interface PostsCategoryItem {
id: string
sort: number
name: string
}
/* Cover image layout */
type PostsCoverLayout = 'left' | 'right' | 'odd-left' | 'odd-right' | 'top'
/* Cover image style */
interface PostsCoverStyle {
layout?: PostsCoverLayout
ratio?: number | `${number}:${number}` | `${number}/${number}`
width?: number
compact?: boolean
}
/* Social link icon */
type SocialLinkIcon = SocialLinkIconUnion | { svg: string, name?: string }
/* Social link */
interface SocialLink {
icon: SocialLinkIcon
link: string
ariaLabel?: string
}
/**
* Profile
*/
export interface ProfileOptions {
/**
* Avatar image URL
*/
avatar?: string
/**
* Name
*/
name?: string
/**
* Description / Bio / Motto / Signature
*/
description?: string
/**
* Whether to display as circular avatar
*/
circle?: boolean
/**
* Location
*/
location?: string
/**
* Organization, Company
*/
organization?: string
/**
* Layout position, left or right
* @default 'right'
*/
layout?: 'left' | 'right'
}Doc Collection Specific Configuration
interface ThemeDocCollection extends ThemeBaseCollection {
type: 'doc'
/**
* Sidebar configuration
*/
sidebar?: 'auto' | (string | ThemeSidebarItem)[]
/**
* Whether to show sidebar scrollbar
* @default true
*/
sidebarScrollbar?: boolean
/**
* Sidebar default collapsed state
* @default false
*/
sidebarCollapsed?: boolean
}
/* Sidebar item configuration */
interface ThemeSidebarItem {
text?: string
link?: string
icon?: ThemeIcon
badge?: string | ThemeBadge
items?: 'auto' | (string | ThemeSidebarItem)[]
collapsed?: boolean
prefix?: string
rel?: string
target?: string
}
/* Icon type */
type ThemeIcon = string | { svg: string }
/* Badge configuration */
export interface ThemeBadge {
text?: string
type?: string
color?: string
bgColor?: string
borderColor?: string
}Auto Sidebar Generation
When the Doc collection's sidebar is set to 'auto', the system automatically generates sidebar navigation based on the directory structure. The sorting rules follow the Folder Naming Conventions.
Sidebar Icon Configuration
The theme supports two methods for configuring sidebar icons:
Define directly in sidebar configuration:
sidebar: [ { text: 'Introduction', link: 'intro', icon: 'mdi:tooltip-text-outline' } ]Define in document frontmatter:
--- title: Theme Introduction icon: mdi:tooltip-text-outline ---
Both methods have the same effect, and you can choose which to use based on specific scenarios.
For complete sidebar configuration options and usage tips, please refer to the Sidebar Configuration Guide.
