南方科技大学飞跃手册

Appearance

飞跃手册 v2.0：轻 · 快 · 美 ​

作者：黄冠超 (hi@sghua.ng)

这篇报告旨在为飞跃手册后续维护者提供全面的技术参考，也可以让感兴趣的同学了解我们的网站是如何运作的。

历史遗留问题 ​

飞跃手册最初基于 Docsify 创建，并基于 Nginx 部署在轻量服务器上。Docsify 的独特之处在其不需构建静态文件，而是在用户访问网站时，基于路径动态，动态地从 Markdown 源文件生成 HTML 文件——这正是旧版本网站 URL 中井号的由来。Docsify 的导航并不通过路径，而是通过井号后的锚点来实现。

Docsify 的优势在于其轻量、易于部署、无需构建。但随着时间推移，劣势也显现出来：

  • Docsify 的最近一次更新是 2023 年六月的 v4.13.1。长期不更新，使得 Docsify 没有引入新的功能、性能优化，也积累了一些安全问题；
  • 路径中的井号使人困惑；
  • 不便于使用自定义布局、拓展组件等，限制了我们能做的改进；
  • 大量操作需要手动完成，如更新某专业帖子数量统计、最近更新列表、各专业的帖子索引等；
  • 本地 dev server 和实际部署时网站的表现可能不一致；
  • 实时生成页面不利于 SEO，也对访问速度有影响。

为了解决这些问题，我们迁移到了 VitePress 框架以更好地拥抱 Vue 生态，希望借此为同学提供更好的浏览体验，也通过更现代、有趣的技术栈吸引更多同学来参与网站建设、维护。

框架：VitePress ​

VitePress 是 Vue 生态里一个常用的静态网站生成框架。我们熟知的 Vue 生态成员，如 Vite、Vitest、Pinia、Slidev，以及 Vue 自身的文档，都是利用 VitePress 构建的。

在这次迁移的构思期间，我们也探索过其他的可能。主要的技术方向有两个：

  • 使用 Nuxt、Next.js，或 Astro 等框架，重新实现整个网站。这样为网站提供了最大的自定义，但是需要手动实现大量细节，迁移耗时长。
  • 使用 Hexo、Jekyll、MkDocs、Docsaurus、VitePress 等面向博客、文档的静态网站生成工具，搭配预置的主题。这样大部分的技术细节都被隐藏在框架和主题内，开发、维护人员的工作量降到最小，迁移速度快。

最终我们选择了第二个技术方向，主要考虑到迁移的快捷方便，以及我们尚没有深入了解飞跃手册读者的具体需求，盲目地重构整个网站恐收益不高。此次迁移，还是以在保留原有功能的前提下，使网站的代码和视觉效果都更现代化为宗旨。

选择 VitePress，主要考虑到其令人满意的预设，与 Vue 组件的无缝集成，以及南科大同学对 Vue 生态的熟悉。

代码质量与持续集成 ​

为了保证代码质量，主要是 Markdown 源文件的可读性，自新版本起，我们引入了 Prettier 和 Markdown Lint 来辅助代码样式检查。例如，Prettier 可将表格源代码自动对齐，而 Markdown Lint 可确保 Markdown 文件符合一定的规范，如无重复的同级别标题，标题和段落之间应留有空行等。

Prettier 不能很好地处理中日韩文字的折行，因此只能在 Markdown 文件中禁用行长度检查。

Prettier 和 Markdown Lint 的配置可在 .prettierrc.yaml、.markdownlint.yaml 文件中找到。

在本地可通过 bun run format 和 bun run lint 指令来检查代码格式和规范。在提交 PR 时，CI 工作流也会自动进行检查。

我们还配置了 Netlify 项目，在 PR 发起时，Netlify 会自动构建预览，并将链接更新在评论中。

持续部署 ​

尽管 Netlify 和 Vercel 等无服务器托管服务方便快捷，开发者体验极好，但为了保证在境内的高效访问，我们还是要将网站部署在境内。飞跃手册过去使用 Nginx 部署在阿里云轻量服务器上。现在考虑到网站是完全静态的，我们可以将其部署在开放了公共读的对象存储上。鉴于 Netlify 和 Vercel 这样的服务的成功，我们希望能复现它们的一些功能，完全拥抱 serverless 范式。如果未来网站需要添加动态功能，我们可以尝试通过边缘函数来解决——总之，尽可能地避免使用服务器。

飞跃手册托管在一个阿里云 OSS 存储桶里。每次有更新被合并到 master 分支时，一个 GitHub Action 会被触发，自动构建并将构建好的网站文件上传到 OSS 中。这样，网站的部署也完全自动化了。

我们的下一步 ​

在完成这次迁移后，我们会立刻着手下一个更棘手的迁移：转换为完全扁平的目录组织形式，即不再按照专业和分享类型将帖子存放在不同文件夹下，而是全部统一存放在文档根目录。这将是 v3.0 的首要目标。

在这之后，我们将把重心转移到基于 Vue 生态开发新功能上，例如更好的搜索、过滤，以及基于大模型的检索功能。敬请大家期待！