Skip to content

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
    : '博客' }
    ] }) })
  • 完成

配置完成后,主题自动扫描 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' }
] } } }) })

集合目录配置

dir 参数指定集合的源文件目录,支持绝对路径和相对路径(均相对于源目录):

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

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

文件过滤

通过 includeexclude 配置过滤 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'] // 排除代码片段文件
} ] }) })

页面生成配置

默认基于 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
, // 分类转换函数
} ] }) })

自动 Frontmatter 生成

仅在执行 vuepress devvuepress 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
          }
        }
      }
    ]
  })
})

生成示例:

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
        }
      }
    ]
  })
})

社交链接

个人信息区域支持社交链接配置,未配置时继承主题默认 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' },
        ],
      }
    ]
  })
})

内置图标库

  • 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

默认展示效果:

高级布局

调整封面图位置和尺寸:

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

效果展示:

紧凑模式

无摘要时启用紧凑布局:

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

效果展示:

compact: true 仅在无摘要时生效

顶部大图布局

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

效果展示:

预设配置

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

.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 布局效果:

移动端适配

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

文章元数据

通过 frontmatter 配置文章元数据:

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

titlecreateTime 在文件创建时自动生成,支持手动修改。

可用属性

属性类型默认值说明
titlestring文件名文章标题
createTimestring当前时间创建时间
tagsstring[][]文章标签
stickyboolean | numberfalse置顶标识,数字越大排序越前
draftbooleanfalse草稿模式,构建后隐藏
coverstring''封面图路径
coverStylePostCoverStylenull封面样式配置
excerptboolean | string''摘要内容,支持自动提取

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

文章摘要配置

自动提取

使用 <!-- more --> 标记摘要截断点:

---
title: 标题
---

摘要内容区域

<!-- more -->

正文剩余部分

手动定义

通过 excerpt 字段自定义摘要:

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

配置说明

  • excerpt: false - 禁用摘要(忽略 <!-- more -->
  • excerpt: string - 自定义内容(忽略 <!-- more -->

推荐使用 <!-- more --> 注释定义摘要

配置到站点首页

主题提供了两种方式来设置 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 }
], }) })

贡献者

更新日志

2025/10/7 15:13
查看所有更新日志
  • 4d236-feat(theme)!: add collections support (#704)