vuepress-theme-plume/docs/en/config/collections.md

title, createTime, permalink

title	createTime	permalink
Collections Configuration	2025/10/09 14:00:06	/en/config/collections/

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:

• post type: Suitable for fragmented content with weak inter-article relationships, such as blogs, columns, etc.
• doc type: Suitable for structured documentation with closely related content, such as user manuals, product documentation, knowledge bases, etc.

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

::: file-tree title="Project Structure"

• docs
  • blog
    • post-1.md
    • post-2.md
  • typescript
    • basic
      • intro.md
      • variable.md
    • types.md :::

The corresponding collection configuration example is as follows:

::: code-tabs#configs

@tab .vuepress/config.ts

import { defineUserConfig } from 'vuepress'
import { plumeTheme } from 'vuepress-theme-plume'

export default defineUserConfig({
  theme: plumeTheme({
    // Collection Configuration // [!code focus:7]
    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' }
    ],
  })
})

@tab .vuepress/plume.config.ts

import { defineThemeConfig } from 'vuepress-theme-plume'

export default defineThemeConfig({
  // Collection configuration in standalone config file // [!code focus:7]
  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:

::: file-tree title="Multi-language Project Structure"

• docs
  • blog/
    • post-1.md
    • post-2.md
  • typescript/
    • basic
      • intro.md
      • variable.md
    • types.md
  • en
    • blog/
      • post-1.md
      • post-2.md
    • typescript/
      • basic
        • intro.md
        • variable.md
      • types.md :::

::: code-tabs#configs

@tab .vuepress/config.ts

import { defineUserConfig } from 'vuepress'
import { plumeTheme } from 'vuepress-theme-plume'

export default defineUserConfig({
  theme: plumeTheme({
    locales: {
      '/': {
        // Chinese collection configuration // [!code focus:4]
        collections: [
          { type: 'post', dir: 'blog', title: '博客' },
          { type: 'doc', dir: 'typescript', title: 'TypeScript笔记', sidebar: 'auto' }
        ],
      },
      '/en/': {
        // English collection configuration // [!code focus:4]
        collections: [
          { type: 'post', dir: 'blog', title: 'Blog' },
          { type: 'doc', dir: 'typescript', title: 'TypeScript Note', sidebar: 'auto' }
        ],
      }
    }
  })
})

@tab .vuepress/plume.config.ts

import { defineThemeConfig } from 'vuepress-theme-plume'

export default defineThemeConfig({
  locales: {
    '/': {
      // Chinese collection configuration // [!code focus:4]
      collections: [
        { type: 'post', dir: 'blog', title: '博客' },
        { type: 'doc', dir: 'typescript', title: 'TypeScript笔记', sidebar: 'auto' }
      ],
    },
    '/en/': {
      // English collection configuration // [!code focus:4]
      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.