post 集合

约 3072 字大约 10 分钟

2025-10-05

概述

post 集合用于管理碎片化的多篇文章集合。这里的"碎片化"指文章间无强关联关系，或仅需扁平化展示的场景，典型应用包括：

博客系统
专题专栏
新闻资讯
随笔记录

该集合提供完整的文章管理功能：

文章列表页 - 支持置顶、封面图、摘要展示
文章分类页 - 基于目录结构自动生成分类
文章标签页 - 根据页面 frontmatter.tags 生成标签
文章归档页 - 基于 frontmatter.createTime 生成时间线归档

各页面均预留个人信息展示区域，支持个人简介或组织信息配置。

主题支持配置多个 post 集合

创建 post 集合

通过三个简单步骤即可完成 post 集合创建：

创建文章目录
docs
blog
post-1.md
post-2.md
…

配置集合参数

.vuepress/config.ts

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

export default defineUserConfig
({
  theme
: plumeTheme
({
    collections
: [ 
      { type
: 'post', dir
: 'blog', title
: '博客' }
    ]
  })
})

.vuepress/plume.config.ts

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

export default defineThemeConfig
({
  collections
: [ 
    { type
: 'post', dir
: 'blog', title
: '博客' }
  ]
})

完成

配置完成后，主题自动扫描 docs/blog 目录并生成以下页面：

文章列表页：/blog/
文章分类页：/blog/categories/
文章标签页：/blog/tags/
文章归档页：/blog/archives/

启用 autoFrontmatter 后，系统自动为 Markdown 文件生成永久链接：

docs/blog/post-1.md
---
title: post-1
createTime: 2025/03/24 20:15:12
permalink: /blog/a1b2c3d4/
---

多语言支持

在主题多语言配置中定义不同语言的 post 集合：

.vuepress/config.ts

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

export default defineUserConfig
({
  theme
: plumeTheme
({
    locales
: {
      '/': { 
        collections
: [
          { type
: 'post', dir
: 'blog', title
: '博客' }
        ]
      },
      '/en/': { 
        collections
: [
          { type
: 'post', dir
: 'blog', title
: 'Blog' }
        ]
      }
    }
  })
})

.vuepress/plume.config.ts

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

export default defineThemeConfig
({
  locales
: {
    '/': { 
      collections
: [
        { type
: 'post', dir
: 'blog', title
: '博客' }
      ]
    },
    '/en/': { 
      collections
: [
        { type
: 'post', dir
: 'blog', title
: 'Blog' }
      ]
    }
  }
})

集合目录配置

dir 参数指定集合的源文件目录，支持绝对路径和相对路径（均相对于源目录）：

dir: 'blog' // 指向 docs/blog
dir: '/blog/' // 等效写法
dir: './blog/' // 等效写法
dir: '/team/blog/' // 指向 docs/team/blog

在多语言下，则相对于多语言目录

文件过滤

通过 include 和 exclude 配置过滤 Markdown 文件，使用 picomatch 模式匹配：

.vuepress/config.ts

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

export default defineUserConfig
({
  theme
: plumeTheme
({
    collections
: [
      {
        type
: 'post',
        dir
: 'blog',
        title
: '博客',
        include
: ['**/*.md'], // 包含所有 .md 文件
        exclude
: ['**/*.snippet.md'] // 排除代码片段文件
      }
    ]
  })
})

.vuepress/plume.config.ts

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

export default defineThemeConfig
({
  collections
: [
    {
      type
: 'post',
      dir
: 'blog',
      title
: '博客',
      include
: ['**/*.md'], // 包含所有 .md 文件
      exclude
: ['**/*.snippet.md'] // 排除代码片段文件
    }
  ]
})

页面生成配置

默认基于 dir 配置生成页面路径，支持完整自定义：

.vuepress/config.ts

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

export default defineUserConfig
({
  theme
: plumeTheme
({
    collections
: [
      {
        type
: 'post',
        dir
: 'blog',
        title
: '博客',
        postList
: true, // 启用文章列表页
        link
: '/blog/', // 列表页链接
        linkPrefix
: '/blog/', // 文章链接前缀
        tags
: true, // 启用标签页
        tagsLink
: '/blog/tags/', // 标签页链接
        tagsTheme
: 'colored', // 标签主题 colored|gray|brand
        tagsText
: '标签', // 标签页标题
        archives
: true, // 启用归档页
        archivesLink
: '/blog/archives/', // 归档页链接
        archivesText
: '归档', // 归档页标题
        categories
: true, // 启用分类页
        categoriesLink
: '/blog/categories/', // 分类页链接
        categoriesText
: '分类', // 分类页标题
        categoriesExpand
: 'deep', // 分类展开层级 number|'deep'
        categoriesTransform
: categories
 => categories
, // 分类转换函数
      }
    ]
  })
})

.vuepress/plume.config.ts

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

export default defineThemeConfig
({
  collections
: [
    {
      type
: 'post',
      dir
: 'blog',
      title
: '博客',
      postList
: true, // 启用文章列表页
      link
: '/blog/', // 列表页链接
      linkPrefix
: '/blog/', // 文章链接前缀
      tags
: true, // 启用标签页
      tagsLink
: '/blog/tags/', // 标签页链接
      tagsTheme
: 'colored', // 标签主题 colored|gray|brand
      tagsText
: '标签', // 标签页标题
      archives
: true, // 启用归档页
      archivesLink
: '/blog/archives/', // 归档页链接
      archivesText
: '归档', // 归档页标题
      categories
: true, // 启用分类页
      categoriesLink
: '/blog/categories/', // 分类页链接
      categoriesText
: '分类', // 分类页标题
      categoriesExpand
: 'deep', // 分类展开层级 number|'deep'
      categoriesTransform
: categories
 => categories
, // 分类转换函数
    }
  ]
})

自动 Frontmatter 生成

仅在执行 vuepress dev 或 vuepress build 后生效

支持集合级别的 frontmatter 自动生成，可自定义转换逻辑：

.vuepress/config.ts

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

export default defineUserConfig({
  theme: plumeTheme({
    collections: [
      {
        type: 'post',
        dir: 'blog',
        title: '博客',
        autoFrontmatter: {
          title: true, // 自动生成标题
          createTime: true, // 自动生成创建时间
          permalink: true, // 自动生成永久链接
          transform: (data, context, locale) => { // 自定义转换
            data.foo ??= 'foo'
            return data
          }
        }
      }
    ]
  })
})

.vuepress/plume.config.ts

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

export default defineThemeConfig({
  collections: [
    {
      type: 'post',
      dir: 'blog',
      title: '博客',
      autoFrontmatter: {
        title: true, // 自动生成标题
        createTime: true, // 自动生成创建时间
        permalink: true, // 自动生成永久链接
        transform: (data, context, locale) => { // 自定义转换
          data.foo ??= 'foo'
          return data
        }
      }
    }
  ]
})

生成示例：

docs/blog/post-1.md
---
title: post-1
createTime: 2025/03/24 20:15:12
permalink: /blog/a1b2c3d4/
---

个人信息配置

每个 post 集合支持独立配置个人信息展示区域。未配置时继承主题默认 profile 设置。

.vuepress/config.ts

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

export default defineUserConfig({
  theme: plumeTheme({
    collections: [
      {
        type: 'post',
        dir: 'blog',
        title: '博客',
        profile: {
          avatar: '/avatar.jpg', // 头像路径
          name: '张三', // 显示名称
          description: '个人简介', // 简介文本
          circle: true, // 圆形头像
          location: '广州', // 所在地
          organization: '组织名称', // 所属组织
          layout: 'right', // 布局位置 left|right
        }
      }
    ]
  })
})

.vuepress/plume.config.ts

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

export default defineThemeConfig({
  collections: [
    {
      type: 'post',
      dir: 'blog',
      title: '博客',
      profile: {
        avatar: '/avatar.jpg', // 头像路径
        name: '张三', // 显示名称
        description: '个人简介', // 简介文本
        circle: true, // 圆形头像
        location: '广州', // 所在地
        organization: '组织名称', // 所属组织
        layout: 'right', // 布局位置 left|right
      }
    }
  ]
})

社交链接

个人信息区域支持社交链接配置，未配置时继承主题默认 social 设置。

.vuepress/config.ts

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

export default defineUserConfig({
  theme: plumeTheme({
    collections: [
      {
        type: 'post',
        dir: 'blog',
        title: '博客',
        social: [
          { icon: 'github', link: 'https://github.com/pengzhanbo' },
        ],
      }
    ]
  })
})

.vuepress/plume.config.ts

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

export default defineThemeConfig({
  collections: [
    {
      type: 'post',
      dir: 'blog',
      title: '博客',
      social: [
        { icon: 'github', link: 'https://github.com/pengzhanbo' },
      ],
    }
  ]
})

内置图标库

discord
telegram
facebook
github
instagram
linkedin
mastodon
npm
slack
twitter
x
youtube

qq
weibo
bilibili
gitlab
docker
juejin
zhihu
douban
steam
stackoverflow
xbox

文章封面配置

文章列表页支持封面图展示，提供多种布局和尺寸选项。

基础配置

在 frontmatter 中定义封面图路径：

---
title: 文章标题
cover: /images/cover.jpg
---

路径规范：仅支持绝对路径或远程 URL。本地图片需放置在 .vuepress/public 目录：

docs

.vuepress

public

images

cover.jpg

config.ts

article.md

默认展示效果：

文章标题

2024-09-18

高级布局

调整封面图位置和尺寸：

---
title: 文章标题
cover: /images/cover.jpg
coverStyle:
  layout: left
  ratio: 16:9
  width: 300
---

效果展示:

文章标题

2024-09-18

紧凑模式

无摘要时启用紧凑布局：

---
title: 文章标题
cover: /images/cover.jpg
coverStyle:
  layout: left
  ratio: 16:9
  width: 300
  compact: true
---

效果展示:

文章标题

2024-09-18

compact: true 仅在无摘要时生效

顶部大图布局

---
title: 文章标题
cover: /images/cover.jpg
coverStyle:
  layout: top
  ratio: 16:9
  width: 300
---

效果展示:

文章标题

2024-09-18

预设配置

为保持视觉统一，支持集合级封面图预设：

.vuepress/config.ts
import { defineUserConfig
 } from 'vuepress'
import { plumeTheme
 } from 'vuepress-theme-plume'

export default defineUserConfig
({
  theme
: plumeTheme
({
    collections
: [
      {
        type
: 'post',
        dir
: 'blog',
        title
: '博客',
        postCover
: {
          layout
: 'left',
          ratio
: '16:9',
          width
: 300,
          compact
: true
        }
      }
    ],
  })
})

布局模式说明：

type PostCoverLayout = 'left' | 'right' | 'odd-left' | 'odd-right' | 'top'

interface PostCoverStyle {
  layout?: PostCoverLayout // 布局位置
  ratio?: number | `${number}:${number}` // 宽高比，默认 '4:3'
  width?: number // 宽度（左右布局生效），默认 240
  compact?: boolean // 紧凑模式，默认 false
}

特殊布局模式：

odd-left - 奇数项居左，偶数项居右
odd-right - 奇数项居右，偶数项居左

odd-left 布局效果：

文章标题

2024-09-18

文章标题

2024-09-18

文章标题

2024-09-18

移动端适配

窄屏设备上自动切换为 top 布局以确保显示效果

文章元数据

通过 frontmatter 配置文章元数据：

---
title: 文章标题
createTime: 2024/01/01 00:00:00
tags:
  - tag1
  - tag2
---

title 和 createTime 在文件创建时自动生成，支持手动修改。

可用属性

属性	类型	默认值	说明
title	`string`	文件名	文章标题
createTime	`string`	当前时间	创建时间
tags	`string[]`	`[]`	文章标签
sticky	`boolean \| number`	false	置顶标识，数字越大排序越前
draft	`boolean`	false	草稿模式，构建后隐藏
cover	`string`	`''`	封面图路径
coverStyle	`PostCoverStyle`	`null`	封面样式配置
excerpt	`boolean \| string`	''	摘要内容，支持自动提取

同时支持通用 frontmatter 配置中的所有字段。

文章摘要配置

自动提取

使用  标记摘要截断点：

---
title: 标题
---

摘要内容区域

<!-- more -->

正文剩余部分

手动定义

通过 excerpt 字段自定义摘要：

---
title: 标题
excerpt: 自定义摘要内容
---

配置说明：

excerpt: false - 禁用摘要（忽略 ）
excerpt: string - 自定义内容（忽略 ）

推荐使用  注释定义摘要

配置到站点首页

主题提供了两种方式来设置 post 集合的文章列表页到站点主页，满足不同的需求场景：

方式一：配置主页的 pageLayout 属性为 posts

docs/README.md
---
pageLayout: posts
---

还可以通过 collection 配置项来指定读取哪个集合的文章列表页，默认读取第一个集合的文章列表页。

collection 需要与集合配置的 dir 的值相同。

docs/README.md
---
pageLayout: posts
collection: blog
---

此配置会直接将页面应用 posts 布局，显示博客文章列表。

这是将主页修改为博客页的最简单的方式，但缺点是缺少灵活性。

方式二：配置主页的 pageLayout 属性为 home, 添加 type: posts 的首页区域类型

docs/README.md
---
pageLayout: home
config:
  - type: posts
    collection: blog
---

使用这种方式，你不仅可以在首页中添加文章列表，还可以灵活的在页面的其他区域添加不同的内容。

比如，配置首屏为 banner，然后紧跟着博客文章列表：

docs/README.md
---
pageLayout: home
config:
  - type: banner
  - type: posts
---

更多自定义配置，请参考自定义首页。

当使用以上两种方式将首页配置为文章列表页后，由于主题默认依然会生成文章列表页，这导致存在了重复功能的页面。为此，你可能需要在集合配置中， 关闭自动生成博客文章列表页：

（还可以重新修改分类页/标签页/归档页的链接地址）

.vuepress/config.ts
import { defineUserConfig
 } from 'vuepress'
import { plumeTheme
 } from 'vuepress-theme-plume'

export default defineUserConfig
({
  theme
: plumeTheme
({
    collections
: [
      { type
: 'post', dir
: 'blog', title
: '博客', postList
: false }
    ],
  })
})

贡献者

pengzhanbo

更新日志

2025/10/7 15:13

查看所有更新日志

4d236-feat(theme)!: add collections support (#704)于 2025/10/7

集合

markdown

代码块

代码演示

图表

资源嵌入

自定义首页

post 集合

概述

创建 post 集合

多语言支持

集合目录配置

文件过滤

页面生成配置

自动 Frontmatter 生成

个人信息配置

社交链接

内置图标库

文章封面配置

基础配置

文章标题

高级布局

文章标题

紧凑模式

文章标题

顶部大图布局

文章标题

预设配置

文章标题

文章标题

文章标题

文章元数据

可用属性

文章摘要配置

自动提取

手动定义

配置到站点首页

贡献者

更新日志