文章 Frontmatter 插件设计
@cogita/plugin-posts-frontmatter 是博客内容的基础插件。它扫描文章目录、解析 Markdown frontmatter、计算文章路由,并通过 virtual-posts-data 向主题和其他插件提供文章数据。
数据流
文件系统 → frontmatter 解析 → 文章索引 → 路由生成 → virtual-posts-data
文章列表、标签、RSS、搜索和 SEO 等消费者通过共享 ContentIndex 读取这些数据,不应再次扫描同一目录。
文章数据
export interface PostFrontmatter {
title: string;
description?: string;
filePath: string;
route: string;
url: string;
createDate: string;
updateDate: string;
categories?: string[];
tags?: string[];
[key: string]: unknown;
}
插件支持 .md 和 .mdx,递归处理嵌套目录,并为缺少标题或日期的文章提供合理降级值。绝对 filePath 属于构建期数据;主题运行时应只消费安全的公开字段。
路由规则
给定 posts 目录和 posts 路由前缀:
posts/hello-world.md → /posts/hello-world
posts/2026/notes/index.md → /posts/2026/notes
posts/guides/setup.mdx → /posts/guides/setup
路由计算应由统一工具函数完成,避免 RSS、搜索和图片插件各自产生不同 URL。
使用
主题可以声明该插件,站点作者通常只需要配置主题:
import { defineConfig } from '@cogita/core';
export default defineConfig({
theme: '@cogita/theme-lucid',
posts: {
dir: 'posts',
routePrefix: 'posts',
},
});
自定义消费者应从 virtual-posts-data 读取数据:
import { allPosts } from 'virtual-posts-data';
const recentPosts = allPosts.slice(0, 5);
生命周期与边界
插件在 beforeBuild 阶段准备索引,在 addPages 阶段生成文章页面,在 addRuntimeModules 阶段发布文章数据。Core 在开发服务器重建前使索引失效,保证新增和修改的文章进入下一轮构建。
插件负责文章发现和元数据,不负责标签筛选、分页、归档、RSS 或主题布局。没有文章时也应提供空的运行时数据,保持零配置体验。
兼容性
文章虚拟模块暴露 contentDataVersion。主题或插件消费数据前应检查版本,在不兼容时给出诊断或降级。文章能力和共享索引的版本策略见内容索引设计与插件 API 规范。