跳到主要内容
← 返回把你的认知做成网站:用 AI 搭建个人知识库与订阅站

AI 与技术通识 · 个人知识站

第 7 课:搭建个人知识库:文章、专题与系统课程

把 MDX 文件变成可查找、可继续阅读的内容结构:从文章和观点出发,整理专题,再判断何时值得沉淀成系统课程。

MDX · 内容架构 · 知识库 · Next.js

你现在真正要解决的问题

首页有了栏目卡,访客点击以后却发现没文章;或者你已经写了十几篇笔记,每篇各说各话,读者读完一篇不知道下一篇在哪里。另一种常见情况是把每个念头都建成一个栏目,几个月后内容分散到二十多个栏目,作者自己也记不住应该放哪里。

知识站的核心工作不是不停生产文章,而是让真实内容有稳定的存放格式、可解释的关系和继续深入的路径。本课把你在前四课规划的栏目落实为 MDX 文件和链接,第一批只要求一篇内容、一组专题关系和一个系统入口,不用等到“内容足够多”才公开。

这一课完成后,你会得到什么

  • 至少一篇真实文章或观点记录,按仓库识别的 frontmatter 格式保存。
  • 一个能指出内容关系的专题集合,不把它误当成必须先建的数据库功能。
  • 一份自己以后能复制的 MDX frontmatter 模板。
  • 一套标题、slug、分类和标签规则,以及入口内容到系统课程的跳转图。
  • 一次从保存文件到构建看到页面的完整检查记录。

先看全局:内容从草稿走到可继续阅读

MDX 是可在 Markdown 中嵌入组件语法的文本文件;它是人工维护的内容源文件,不是在线编辑器,也不会自动决定专题关系。Frontmatter 是两道 --- 之间的元数据,站点用它生成标题、分类、列表和路由,再编译正文。

本项目从 MDX 源文件和 frontmatter 开始,经过元数据校验、正文编译、列表路由,再进入专题和系统课程MDX 文件元数据 + 正文读取与校验gray-matter + schema静态路由列表 + 详情页专题集合相关内容关系系统课程按顺序组织的学习下一步入口产品 / 订阅说明

文件保存内容,路由让它可访问;专题组织关联内容,系统课程按目标和顺序编排学习。末端只有真实存在的产品或订阅说明页才放行动入口;未完成时链接到已有内容。

内容形态主要任务常见长度与稳定度在当前 LUPY 项目中的体现读者下一步
文章 / 观点回答一个具体问题,留下一个有边界的判断一次可以读完;允许继续修正src/content/judgments/*.mdx 是观点集合;guides 也承载课程正文阅读相关观点,或进入主题内容集合
专题 / 内容集合把围绕一个问题的多篇内容聚到同一个入口内容之间有关联,但不必是固定教学顺序本项目没有独立 topics collection;通过分类、站点栏目、专题入口和互链构成选择深入阅读的分支
系统课程按目标、先后依赖和练习组织完整学习过程每课有产出、顺序和验收src/content/guides/*.mdx 保存课文,src/data/systems.ts 决定课程成员与顺序完成任务或转向真实行动入口
产品 / 订阅说明解释真实提供什么、谁适合、下一步如何发生必须随实际交付和承接能力更新本课只建立内容链接关系;具体页面在第 8 课规划点击明确的第三方、表单或联系入口

栏目是长期导航分类;专题是内容之间的编辑关系,可以跨栏目,也可以只包括几篇相互照应的文章。系统课程必须有顺序和任务,不能因为文章主题相似就贴上“课程”标签。

贯穿案例推进:用一个真实主题连接三层内容

贯穿案例仍是个人知识库与订阅站。假设定位卡写的是“帮助刚开始用 AI 编程整理个人内容的人,把零散笔记做成可持续更新的网站”。这不是 LUPY 的用户成果,也不暗示作者已有课程销售。案例的素材来自一条可核实的工作观察:初学者常把“页面做出来”与“网站内容能持续维护”混为一谈。先写一篇解释这两者差别的文章,再把“从想法到个人知识站”的相关文章聚成专题;当主题已有连续目标、练习和验收,再把它编排成系统课程。产品页只在确实有内容和承接能力时连接。

阶段本课前的状态本课完成的变化读者如何换成自己的材料
文章只有一句观察,散落在笔记里一篇正文只回答一个具体问题,写清依据和边界从真实项目、反复回答的问题或学习笔记选一个可公开主题
专题多篇内容各自存在,互相找不到为同一读者任务编一个专题入口并列出文章顺序按内容地图找 3—5 篇回答相邻问题的内容;不足时先列待写题目,不冒充已发布
系统课程主题可能值得继续讲,但尚未形成步骤只有出现先后依赖、练习和验收时才升级成课程用前置知识、逐课产出和验收证据判断是否成熟
承接还没想清楚读者读完怎么办文章内放真实相关链接;产品入口留给第 8 课落实若当前无服务或产品,下一步可以只是读另一篇内容

案例路径可以是:文章《为什么页面上线不等于内容系统完成》→专题《个人知识站从内容到发布》→系统课程《把你的认知做成网站》→未来可选的产品说明页。LUPY 当前的课程本身也能观察到“观点与判断—专题/系统课程—承接说明”的结构关系,但这只是信息架构示例,不是收益或用户结果证据。

跟着做:从文件到页面

第一步:识别一条内容应该放在哪里

**做什么:**先写一句“读者读完能回答的具体问题”,再判断是单篇文章、观点、专题成员还是系统课。**为什么现在做:**按格式创建文件之前先确定它的职责,后面就不用为了导航补救。**输入:**打开 content-map.md,找一个栏目,抄下读者问题、准备发布的内容和未来沉淀方向;避免新增栏目。**正常结果:**一句话只对应一个主问题,比如“为什么页面能打开仍不代表内容站可维护?”而不是“AI、成长、人生”。**出错先检查:**若同一个标题想同时回答多个主题,拆成一篇主文与后续链接;若内容只是课程步骤清单,且没有读者问题,先补足问题而不是先建页面。

第二步:按仓库约定新增 MDX 文件

MDX 文件名便于编辑者辨认,slug 决定公开 URL,两者用途不同。当前代码从 src/content/{collection} 读取 .mdx,用 gray-matter 拆分元数据与正文,再由 parseMeta 校验字段;系统内容的详情页由 contentHref 生成类似 /learn/{slug}/ 的路径。比如课程正文保存为 src/content/guides/personal-site-07-library.mdx,frontmatter 中 slug 与系统目录配置里的 slug 必须一致。

**做什么:**在适合的 collection 下新建一个文件。**为什么现在做:**仓库从固定目录读取内容,不会扫描你电脑上的任意 Markdown。**输入:**复制下方模板,将标题、slug、日期、分类、标签和正文改成真实内容;slug 只用小写英文、数字、连字符。**正常结果:**文件首行是 ---,frontmatter 至少具有必填字段,正文与第二个 --- 之间留空行。**出错先检查:**日期为实际日历日期 YYYY-MM-DD;YAML 数组括号、引号配对;slug 不与已有文件重复。

第三步:把正文写成可验证的单篇内容

**做什么:**先写读者遇到的具体场景,再给判断、过程、例子和边界。**为什么现在做:**空泛主张无法组成可继续链接的知识节点。**输入:**列出你亲历或实际研究过的材料,区分“我观察到”“这是我的解释”“这里仍不知道”。**正常结果:**文章不用依赖其他链接也能完成一个主要解释,结尾知道接下来去哪看。**出错先检查:**若内容只包含标题、口号或外链,补上过程与例子;若涉及经历和数据,找原始记录,不能让 AI 补齐。

第四步:用系统约定的关系组出专题

当前仓库没有专属的专题数据表或专题 frontmatter 字段。不要在文件里自行添加 topicId 后期待网站自动生成专题页。第一版可以在已有栏目入口中写一段专题说明,列出已发布内容链接,并在文章末尾互相推荐。未来真的需要可筛选专题索引,再将需求写进 site-brief.md,明确集合数据从哪里来、谁维护、页面如何验收。

**做什么:**选 3—5 篇围绕同一读者任务的内容,写一个专题标题、说明和建议顺序。**为什么现在做:**读者需要知道关联关系,不只是看到“相关内容”四个字。**输入:**先列实际已存在的路径,缺项标为“计划中”且不要做成链接;每篇说明它解决的子问题。**正常结果:**从第一篇开始读能逐渐深入,跳读时仍知道专题讨论什么。**出错先检查:**若每篇都能属于十个专题,说明主题粒度太宽;若专题只为容纳一篇内容,暂时把它当栏目或单篇入口。

第五步:按系统课程的真源注册课程成员

当前仓库将课程正文放在 guides collection,将课程名称、章节组和顺序放在 src/data/systems.ts。加入系统课程时,检查课程 chapters 与课程目录中的每个 slug 都实际有对应发布文件;课程前后课导航依赖 chapters 顺序,不依赖文件名排序。不要把完整课程名误以为 frontmatter 的 category 会自动产生课程关系。

**做什么:**如果当前主题确有课程结构,编辑系统数据清单,将已有 slug 放入指定系统和顺序。**为什么现在做:**静态构建需要先知道要生成哪些详情页和章节导航。**输入:**复制既有系统的数据结构,不改其他课程;检查 status 是 published,而 draft 不会出现在公开 collection。**正常结果:**课程目录、系统详情、上一课/下一课一致,直接打开每篇详情链接能看到正文。**出错先检查:**拼写、重复 slug、文件缺失、状态与 draft 是否矛盾;运行 npm run build 查出内容解析或静态参数错误。

第六步:本地确认页面与跳转

**做什么:**保存文件后运行 npm run dev,打开终端给出的本地地址和对应 /learn/{slug}/ 路径;再检查文章列表、专题入口和相关链接。**为什么现在做:**文件存在不代表它通过元数据检查或已进入公开索引。**输入:**用浏览器地址栏直接访问详情 URL,并从列表再点入一次。**正常结果:**页面标题、摘要、正文、代码/表格和上一课下一课符合预期;直接刷新详情仍能加载。**出错先检查:**终端错误行、控制台 404、collection 文件夹、frontmatter 必填项、slug 是否唯一;不需要先删除 .next 或盲目重装依赖。

一份与仓库格式一致的 MDX 内容样例

下例是一篇“拟发布的文章”,其中示例身份、读者情境和数字均不假装是 LUPY 的真实用户数据。请把示例问题换成自己的真实材料后再发布。

---
title: "为什么首页上线后还需要内容结构"
slug: "homepage-needs-content-structure"
summary: "首页只提供入口。把栏目、文章和后续阅读连起来,读者才知道从哪开始、怎样继续。"
date: "2026-10-12"
category: "个人知识站"
tags: ["网站", "内容"]
status: "published"
featured: false
draft: false
cover: null
paths: []
topics: ["网站", "产品"]
---

刚完成首页时,页面看起来已经完整:导航、标题、几张栏目卡都在。但如果点进栏目没有内容,或者读完一篇文章后没有任何相关入口,访客仍需要自己猜从哪里继续。

先给每篇内容一个明确任务。比如一篇文章回答“为什么首页不能代替知识库”,专题把几篇围绕内容组织的问题连起来,系统课程则在需要练习和顺序时提供逐步任务。

这些形式不必同时完成。第一步可以先发布一篇能独立回答问题的文章,再给它加上通往真实相关内容的链接。没有的内容不要伪装成已经存在。

## 这篇文章的边界

这里讨论的是信息组织,不代表增加栏目就一定带来流量或商业结果。读者是否需要这条路径,要通过真实阅读反馈和实际使用继续检验。

示例说明:title 面向读者;slug 是公开地址的一部分;summary 用于列表预览;date 填发布日期;category 选长期栏目;tags 用于有限检索;status 必须是 collection 可识别值;draft 控制公开;cover 无图填 null;paths 与 topics 受 schema 约束。自己的简化项目没有这些字段时,以 src/lib/content-schema.ts 为准,不照抄代码不存在的字段。

读者从单篇继续深入的路径

访客从一篇入口文章出发,按兴趣进入专题中的延伸内容,之后选择系统课程或真实产品说明页入口文章回答眼前问题专题入口展示关联和顺序延伸文章不同子问题系统课程需要顺序与练习时承接说明仅链接真实入口

箭头表示一种可选阅读路径,不是所有人都必须走到产品页。入口文章要能独立结束;专题提供“同一问题还有什么”;课程提供有顺序的学习;承接页只回答“如果我想继续获得某种帮助,真实下一步是什么”。相关内容链接文字写出目标,例如“继续了解如何整理栏目”,不要只写“点击这里”。

内容盘点模板

标题 / 拟写问题当前状态读者问题栏目内容角色相关内容链接下一次处理
为什么首页之后仍要维护内容索引已发布 / 草稿 / 想法首页入口和正文关系不清网站结构入口文章专题:个人知识站信息组织检查链接是否真实
如何判断一组文章已经能组成专题拟写内容数量多但没有深入路径内容系统延伸文章前一篇 / 后一篇先完成独立正文
系统课程与专题有什么区别拟写不知道何时要做顺序课程学习设计课程导读系统课程入口补充任务与验收
自己的真实题目想法读者遇到的具体问题已有栏目入口/延伸/课程已存在的相关页下一项小动作

先盘点十条自己确实能写或已有的内容,允许“想法”状态;不要把计划中的文章混进已发布索引。稳定的栏目建议先控制在三至五个。标签只在能帮助读者跨栏目筛选时使用,并优先复用词表。某个词只出现一次且没有检索作用时,把它留在正文,不创建新标签。

用 AI 辅助新增内容,但不让它代造事实

把现有文章、栏目规则和 content-map.md 以 TRAE 的明确文件引用加入上下文。先要求 AI 只规划和质疑,不让它一轮批量改文件。

你是我的 MDX 编辑协作者。本轮目标只新增一篇内容,不调整站点代码。

请先读取并引用:
- docs/content-map.md(栏目、目标读者和优先级)
- docs/project-rules.md(事实边界和内容规范)
- src/content/{相关集合}/ 中最相关的 2 篇已发布文件(格式和已有观点)

拟写问题:{一个读者真实遇到的问题}
可用事实材料:{我提供的笔记、链接摘录或亲历记录}
不能推断的内容:{收入、客户数、经历、用户反馈等}

第一步只输出:
1. 这条内容适合的角色、栏目和原因;
2. 与已发布内容的重合点及可形成的新信息;
3. 正文结构和还缺的事实材料;
4. 一个符合仓库命名规则的文件名与不重复 slug 候选。

等我确认大纲后再写正文。保留不确定性,不添加我未提供的经历、数据、用户故事或承诺;不要自动修改文件。正文完成后只报告建议路径、frontmatter 字段和需要人工核验的事实。

逐段作用:目标限定一篇内容并禁止结构重构;上下文路径让 AI 按真源工作;拟写问题和材料区分题目与证据;第一步输出让你检查是否重复;等确认后再写,避免一次生成整组文章;禁止推断提醒事实边界;最后的报告帮助你逐项核验。AI 写出的文字仍然需要你核实,不因提示词写了“不要编造”就自动成为事实。

你现在应该看到什么

浏览器中有一篇完整详情,不只是首页增加了一张空卡;文章列表能看到标题和摘要;专题说明列出真实存在的内容,并能从入口文章继续跳到延伸内容;课程入口只指向目录中已经发布的课。若你正在本仓库核验,课程目录加入本课后,直接访问 /learn/personal-site-07-library/ 应生成这一课详情,系统课程里的第 6 课“先做出首页”下一节应是本课。

本课任务与提交物

  1. 依据自己的定位卡与内容地图,从真实笔记、观察或作品中选一条内容,完成并发布一篇独立可读的 MDX 文章。
  2. 用表格盘点至少十条已有或拟写题目,分配到不超过五个长期栏目;清楚标出状态。
  3. 选择至少三篇已存在或正在写的相关内容组成专题,说明阅读顺序;没有三篇时,先以专题草案提交,不把未写内容显示为已发布链接。
  4. 保存 docs/content-frontmatter-template.mdx、docs/content-naming-rules.md 和内容关系图;确认是否需要正式系统课程入口。
  5. 运行 npm run dev 浏览文章和跳转;再运行 npm run build 检查静态页面与重复 slug。

可验收提交物是:一篇真实正文、一个内容集合说明、可复制模板、命名归类规则、关系图和一次构建记录。若网站尚无文章列表组件,记录这一缺口,并把需要的新页面任务写入后续 brief;不要把单篇详情能打开说成索引已经完成。

自检清单

  • Frontmatter 字段和本项目 schema 对得上,日期、状态、slug 均有效。
  • 文章回答一个明确问题,标出证据、个人判断和未知边界。
  • 专题只列真实存在的链接,主题范围具体,成员内容互相补充。
  • 系统课程的章节关系在 systems.ts 中按学习顺序登记,不靠文件名排序。
  • 每条内容有真实的下一步链接;没有产品入口时提供相关阅读即可。
  • 本地浏览器可直接打开详情、列表,页面刷新后仍正常。

常见翻车点

  1. **Frontmatter 看起来像 YAML 却没有被识别。**检查文件最开头有没有 BOM 或多余字符、两行 --- 是否独占一行、键名是否拼错;再看终端提示的源文件路径。
  2. **slug 冲突或直接链接 404。**检查其他文件的 frontmatter slug,而不是只看文件名;大小写、数字和连字符保持一致,并从构建日志找 duplicate slug。
  3. **文章文件存在却不显示。**确认放在正确 collection 目录、draft 是 false、当前列表确实读取该 collection、状态符合允许值;观察列表是否受类别/日期筛选。
  4. **专题连到了未来内容。**路径点击后 404;把未完成题目标成计划项,不做可点击链接,或先写正文再加入专题。
  5. **把每个名词都做成标签。**筛选菜单里只有一个条目的词没有导航价值;合并近义词,先复用小型词表。
  6. **MDX 构建失败后直接改一大段。**先定位第一条报错,核对 frontmatter 解析还是正文语法,再只修改报错附近;表格分隔行、代码围栏和 JSX 标签常见出错。
  7. **把几篇同主题文章叫作系统课程。**先补齐学习目标、前后依赖、每课任务和验收;若只是并列观点,保持专题而不伪装课程。

下一课会怎么用到今天的成果

第 8 课会从真实文章和专题入口出发,决定读者有需要时可以采取的下一步,并把那条承接路径写成页面。没有可以负责交付的订阅或产品时,会把“继续阅读”保留为主要动作,不会虚构一项服务。

本课技术依据

  • Next.js Static Exports:支持本课用构建输出为每个路由生成静态 HTML 的说明;它也列出需要运行时服务器的能力限制。
  • 本仓库的 src/lib/content-schema.ts 与 src/lib/content.ts:核对允许字段、路由前缀、草稿过滤、文件读取目录和重复 slug 校验。
  • 本仓库的 src/data/systems.ts:核对系统章节的成员与顺序来源。