这个博客如何构建与发布

这里记录「fa1nes 的博客」的维护方式。文章、动态和站点配置都放在 fa1nes/blog，推送到 main 后由 GitHub Actions 检查、构建并部署到 GitHub Pages。

写一篇新文章

在 src/content/posts/ 下新建一个 .md 或 .mdx 文件，文件名就是文章的网址。比如 my-first-post.md 会生成 /posts/my-first-post/。

每篇文章的开头是一段被称为 frontmatter 的元信息：

---
title: 文章标题
description: 一句话摘要，会用在列表、搜索和分享卡片上
pubDate: 2026-07-20
category: 技术
tags: [性能, 前端]
---

只有 title 和 pubDate 是必填的。其余字段都有合理的默认值：

写作时执行 npm run dev，保存文件浏览器会立即刷新。想暂时藏起某篇稿子，把 draft 设成 true 就行，它在本地依然可见，但不会出现在正式构建里。

几乎所有需要改的东西都集中在 src/site.config.ts 一个文件里：站点标题、作者信息、导航菜单、社交链接、每页文章数、评论开关、页脚备案号。

export const site = {
  url: 'https://fa1nes.github.io',
  base: '/blog',
  title: 'fa1nes 的博客',
  subtitle: '技术实践、工具折腾与日常记录',
  // ...
};

改完保存即可，不需要动任何组件代码。

本站的完整地址是 https://fa1nes.github.io/blog/。canonical、RSS、sitemap 和分享图链接沿用同一组部署地址；修改站名或图标后，执行 npm run og 同步默认分享图及 PNG 图标。

网页后台位于内容工作台，使用有仓库写入权限的 GitHub 账号登录。保存会直接提交到 main；勾选「草稿」的内容不进入生产页面。取消草稿后保存，等待 GitHub Actions 的检查、构建和部署成功，再访问文章链接。

本地维护时先执行 npm run check 和 npm run build。构建验收会检查站内资源、canonical、分享图、图标与 sitemap；失败时不会上传部署产物。

本站采用的原则是：能在构建时做完的事，就不要留到浏览器里做。

没有前端框架。页面是纯 HTML 加 CSS，没有 React、Vue 这类运行时。
JavaScript 按需加载。深色模式切换、代码复制、目录高亮各自只有几十行，且只出现在真正需要的页面上。搜索的脚本只在 /search/ 页面加载。
移动端菜单使用原生元素。展开收起由 <details> 负责，点击外部或按 Escape 时由少量脚本收起。
字体由本站托管。英文和数字使用 Nunito 子集，中文回退到系统字体，不依赖第三方字体请求。
搜索索引在构建时生成。Pagefind 会把索引切成小块，搜索时只下载用得上的那几片，而不是把全站内容打包进 JavaScript。

代价是有一些花哨效果做不了，比如页面间的平滑过渡动画。这是刻意的选择：阅读文字的时候，动画通常只会分散注意力。

写得开心。