⚠️ 1.0.0-rc.165 破坏性更新说明：博客与笔记功能迁移至“集合”
‼️ 本次更新为破坏性更新！博客与笔记功能已整体迁移至全新的“集合”架构。‼️
设计动机：为什么引入“集合”？
背景与问题分析
主题最初仅支持博客功能，将 docs 源目录下的所有 Markdown 文件识别为博客文章。随着版本迭代，我们新增了笔记/知识库功能，默认将 notes 目录作为笔记根目录，并将其内容从博客列表中排除。
这种分阶段实现导致了架构上的不平衡：博客成为“一等公民”，而笔记功能则显得边缘化。这给用户带来了以下困扰：
- 路径冗余：笔记文件必须存放在
notes/目录下，增加了不必要的目录层级 - 链接复杂：未开启
autoFrontmatter时，URL 会强制包含/notes/前缀 - 概念混淆：用户常困惑于“笔记”与“文档”的功能区别
- 配置繁琐：需要额外调整
notes.dir配置才能实现标准文档站结构
这些设计缺陷源于历史迭代的遗留问题，我们对此深表歉意。
解决方案：统一的内容抽象
经过对主流静态站点生成器（如 Hugo、VitePress）和全栈框架（如 Nuxt）的调研，我们从 @nuxt/content 的 collection 概念中获得灵感。
我们决定引入集合作为统一的内容组织单元。无论是博客、笔记、文档还是知识库，本质上都是 Markdown 文件的特定集合，只是在呈现方式上有所差异。
核心洞察：通过“集合”抽象，统一各类内容的组织形式，同时保留各自的展示特性。
基于内容特征，我们定义了两种集合类型：
post类型：适用于碎片化、关联性弱的内容（如博客、专栏），提供文章列表作为导航入口doc类型：适用于结构化、关联性强的内容（如文档、手册），提供侧边栏进行快速导航
这一设计既解决了历史架构问题，又为未来扩展更多内容类型奠定了基础。
迁移指南
核心概念
- 集合：通过
collection.dir指定目录，该目录下所有 Markdown 文件均归属该集合 - 集合类型：
post：碎片化内容，支持文章列表导航doc：结构化内容，支持侧边栏导航
配置迁移
替换原有的 blog 和 notes 配置：
import { defineUserConfig } from 'vuepress'
import { plumeTheme } from 'vuepress-theme-plume'
export default defineUserConfig({
theme: plumeTheme({
// 移除旧的 blog 和 notes 配置
blog: { /* 博客配置 */ },
notes: {
link: '/',
dir: '/notes/',
notes: [
{ dir: 'typescript', link: '/typescript/', sidebar: 'auto' }
]
},
// 使用 collections 配置
collections: [
{
type: 'post', // 替代原博客功能
dir: 'blog', // 指向 docs/blog 目录
title: '博客' // 集合显示名称
// 原博客配置继续保留
// ...
},
{
type: 'doc', // 替代原笔记功能
dir: 'typescript', // 指向 docs/typescript 目录
title: 'TypeScript笔记',
sidebar: 'auto', // 自动生成侧边栏
},
]
})
})目录结构调整
按照以下步骤迁移文件：
操作步骤：
- 将
notes目录下的子目录直接移至docs根目录 - 创建
blog目录，将原博客文章移入其中 - 移除空的
notes目录
迁移前结构
basic.md
advanced.md
post-1.md
post-2.md
blog-post.md
README.md
迁移后结构
basic.md
advanced.md
post-1.md
post-2.md
blog-post.md
README.md
帮助函数
defineCollection：用于定义单个 collection 配置的帮助函数defineCollections：用于定义多个 collection 配置的帮助函数
import { defineCollection, defineCollections } from 'vuepress-theme-plume'
export const blog = defineCollection({
type: 'post',
dir: 'blog',
title: '博客'
})
export const typescript = defineCollection({
type: 'doc',
dir: 'typescript',
title: 'TypeScript笔记',
sidebar: 'auto'
})
export const collections = defineCollections([
blog,
typescript
])详细文档
贡献者
更新日志
2025/10/7 15:13
查看所有更新日志
4d236-于