跳到主要内容

内容站、知识库、文档、教程要不要拆系统：先统一内容对象，再决定页面形态

· 阅读需 5 分钟
一介布衣
一介布衣
全栈开发者

很多团队一讨论内容系统，第一句就会问“博客、文档、知识库、教程到底要不要拆成四套”。这个问题当然重要，但我现在越来越少把它放在最前面。因为真正会决定后面是不是越来越乱的，通常不是页面长什么样，而是同一份内容进入系统时，到底有没有一个稳定身份。

在 blogV2 这种长期维护的站点里，内容类型一多，最先冒出来的往往不是样式问题，而是这些更底层的冲突：

  • 标题到底从 frontmatter 读，还是从正文第一个 H1 兜底
  • 日期是以文件名为准，还是 frontmatter 为准
  • slug 没写时要不要自动生成
  • 同一篇内容以后想迁移、归档、补写，靠什么保持稳定身份

这几个问题一旦没有统一答案，所谓“多套内容系统”很快就会退化成“多套彼此对不上的输入源”。页面可以先不同，身份不能先糊。

scripts/new-post.js 其实已经说明：内容对象从创建那一刻就开始了​

scripts/new-post.js 里那份默认模板很能说明问题。它不是先让你写正文，最后再顺手补点 metadata，而是一开始就要求这些字段存在：

---
title: 文章标题
date: 2026-01-21
tags: [内容工程, Docusaurus]
description: >
  这里写摘要，它会直接影响列表展示和搜索预览
---

这件事本身就说明，内容对象在创建那一刻就已经不是“只有正文”。元数据不是发布前随手补一补的注释，而是这篇内容被系统识别、组织和重用的主键。

一旦开始迁移，脚本会逼你承认字段契约不能含糊​

我很喜欢看 scripts/migrate-blog-posts.js，因为它比任何概念讨论都诚实。这个脚本里专门有几类函数：

  • resolveTitle(frontmatter, content)
  • resolveDate(frontmatter, filename)
  • toBlogFilename(filename, frontmatter)
  • toSlug(filename)

换句话说，只要你的内容历史足够长，就一定会遇到这些情况：

  • frontmatter 里没 title，只能从正文标题兜底
  • 日期格式不统一，只能从文件名里猜
  • 老文章没有 slug，只能按文件名推导
  • 迁移后的文件需要重新命名，但又不能把历史链接搞乱

这就是为什么我越来越不把“内容模型”当概念题。你只要真正做过一次迁移，就会知道字段契约不清，后面全是人工修复。

如果要共用底层对象，我现在会先锁这份最小契约​

如果今天让我给博客、教程、知识库和文档共用一套底层对象，我会先保证这几个字段稳定：

---
title: 内容标题
description: 给人看也给列表看的一句话摘要
date: 2026-01-21T10:20:00+08:00
slug: /内容-知识库-文档-教程-应该是四套系统还是一套系统
tags:
  - 内容工程
  - 信息架构
content_type: article
audience: developer
status: published
---

其中前五个字段是站点运行的基本盘，后面的 content_type、audience、status 则是我觉得应该逐步补齐的治理字段。

为什么是这套组合？因为它分别承担了不同责任：

  • title 决定页面识别和列表显示
  • description 决定摘要和搜索预期
  • date 决定时间线、归档和排序
  • slug 决定稳定链接
  • tags 决定主题聚合
  • content_type 决定这是一篇博客、教程还是参考文档

如果后面真要做统一检索、统一推荐或者统一归档，这份契约会比你分了几个目录更重要。因为目录只能表达“放在哪”，不能稳定表达“它是什么、适合谁、现在处于什么状态”。

我不再建议只靠目录区分内容类型​

很多项目一开始喜欢用目录名偷懒，比如：

  • blog/ 就代表文章
  • docs/ 就代表文档
  • tutorials/ 就代表教程

这个做法在规模小时没问题，但只要你开始做迁移、归档、检索和跨区域复用，目录名就不够用了。因为读者真正关心的不是文件放在哪个文件夹，而是：

  • 这篇东西适合入门还是查阅
  • 它是不是最新版本
  • 它是观点型文章，还是操作型教程
  • 它应该进入哪类搜索结果和导航路径

这些都不是目录名能单独表达的。

真正该拆系统的时候，通常是边界已经不只是内容形态不同​

我不是反对拆，而是反对在底层对象还没统一前就先拆。真正值得拆成多套系统，通常是这些情况：

  • 权限模型完全不同，比如公开博客和内部知识库
  • 发布节奏完全不同，比如产品文档要求版本冻结，博客允许持续修文
  • 页面交互完全不同，比如教程需要步骤导航，知识库需要强检索

即使真拆，我也还是建议保留共享的元数据底座。因为只要以后还想做统一检索、统一迁移、统一归档或者统一分析，页面可以分，内容对象最好别各说各话。

我的结论其实很朴素​

内容站、知识库、文档、教程到底是一套还是四套，当然重要，但那是第二层决策。第一层决策永远是：一份内容进入系统时，它的身份、时间、链接、摘要和类型是否已经被定义清楚。

这一步做对了，后面你无论是做归档、做搜索、做迁移，还是把它拆成不同页面形态，成本都会低很多。反过来，如果字段契约一开始就是糊的，系统越多，返工只会越多。页面之争往往发生在后面，真正该先统一的，是内容对象这层地基。