HDU-WIKI 是怎么做出来的

作为参与开发的人，我经常会觉得：大家在网页上看到的是一个个按钮、一篇篇文章、一个搜索框，但它们背后其实连着一整套工程。

HDU-WIKI 不是简单堆几个页面出来的。我们要解决的问题包括：文章怎么存、分类怎么管、搜索怎么跑、投稿怎么审核、页面怎么保持稳定。下面就从开发者的视角，带大家看看这个网站是怎么被搭起来的。

TypeScript 负责结构约束

在开发 HDU-WIKI 的时候，我们大量使用 TypeScript。

如果只写纯 JavaScript，很多错误要等网站跑起来以后才会暴露出来。比如某篇文章少了标题、搜索结果字段写错、投稿表单漏了摘要、侧边栏拿到的数据结构不对，这些问题在小项目里可能还能靠肉眼检查，但在一个持续增长的网站里很容易变成后期维护的坑。

所以我们用 TypeScript 先把数据结构写清楚。文章应该有哪些字段，作者信息是什么样，分类和子分类怎么组织，搜索结果要返回什么，投稿接口需要哪些内容，都可以提前被类型约束住。

从浏览者角度看，这些东西可能是“看不见的”。但它们决定了你打开文章时标题不会乱、分类不会丢、搜索结果能正确跳转。TypeScript 做的就是这种底层秩序。

TypeScript 最后还是会变成 JavaScript，在浏览器里真正跑起来。

比如你点击搜索框、切换夜间模式、打开移动端菜单、提交投稿表单，这些交互最终都要靠 JavaScript 来响应。浏览器不会天然知道“点这个按钮要打开搜索弹窗”，这些逻辑都需要我们写出来。

这也是前端开发有意思的地方：HTML 决定页面有什么，CSS 决定它长什么样，而 JavaScript 决定它能怎么动、怎么响应你。

HDU-WIKI 里很多体验都是这样拼起来的。搜索框输入后延迟请求，夜间模式记住用户偏好，投稿时把表单内容发给后端，文章页面根据参数高亮搜索词，这些都不是静态页面能自己完成的。

我们没有把文章直接塞进数据库，而是用 Markdown 文件来保存内容。

这样做的好处是很明显的：写文章的人可以专注写作，审稿的人可以直接看 diff，开发者也可以用代码统一处理格式。每篇文章开头的 frontmatter 保存标题、日期、作者、摘要和标签，正文则使用标准 Markdown。

当网站读取文章时，会先用 gray-matter 拆出元信息，再用 unified 这一套处理链把 Markdown 转成 HTML。这个过程里还会处理数学公式、代码高亮、标题锚点和安全链接过滤。

所以你看到的一篇文章，背后其实经历了：

Markdown 文件 -> 解析元信息 -> 转换正文 -> 生成页面

这也是为什么我们可以让文章既适合人写，也适合程序读。

HDU-WIKI 使用 Next.js 来组织页面。

首页、分类页、文章页、作者页、搜索接口、投稿接口，都可以放在同一个项目里维护。这样内容、页面和 API 不会散落到很多不同地方，开发时也更容易追踪问题。

举个例子，分类页需要知道当前分类下有哪些文章，文章页需要根据 slug 找到具体 Markdown 文件，搜索接口需要扫完整个 content 目录，投稿接口则需要把用户提交的内容变成新的 Markdown。它们看起来是不同功能，但其实共享同一套内容源。

这也是我们选择这种架构的原因：内容是一份，展示可以有很多种。

站内搜索不是只查标题。

我们会扫描整站 Markdown，读取标题、摘要、标签和正文，然后用 FlexSearch 建索引。搜索时，不同字段会有不同权重：标题最重要，标签其次，摘要再次，正文也会参与匹配。

所以当你搜索 绩点 的时候，只要某篇文章正文里认真讲过它，就有机会被搜出来。这个体验看起来简单，但背后要先把所有文章变成可检索的纯文本，再把它们交给搜索引擎排序。

对浏览者来说，这是一个搜索框；对开发者来说，它是一套“内容扫描、索引构建、权重排序、结果跳转”的流程。

投稿功能是我们很重视的一块，因为 HDU-WIKI 本质上是一个共建项目。

用户在网页里写完标题、作者、摘要、标签和正文后，内容不会直接进入线上网站。后端会先做校验，检查字段是否完整、路径是否合法、正文里有没有危险 HTML 或脚本内容，然后再把投稿整理成 Markdown 文件。

接下来，它会走 GitHub 的审核流程：

这样做会比“直接写入网站”麻烦一点，但它更可靠。每一次投稿都有记录，每一次修改都能回看，管理员也能在合并前检查内容和格式。

GitHub 在这里不只是代码仓库，更像是我们的网站协作后台。

我们想做的，不只是一个能打开的网站，而是一套能长期生长、持续被人使用和补充的内容系统。

我们希望它对浏览者足够简单：打开、搜索、阅读、投稿。也希望它对维护者足够清楚：内容在哪里，结构怎么变，谁提交了什么，为什么这样改。

TS 让结构更稳，JS 让交互更顺，Markdown 让写作更轻，GitHub 让协作更透明，搜索让信息更容易被找到。它们拼在一起，才有了今天这个更像“共同整理出来的百科”的 HDU-WIKI。