edsfod

关于本博客

发布于 · 最后编辑

本页由 LLM 根据笔者与其关于博客设计的讨论整理撰写，经笔者审阅。使用模型：Claude Opus 5.5。

本文会不定时更新与修改，不保证描述的时效性。

这里是 edsfod 的博客。本页记录这个博客的设计：它怎么组织内容、用什么许可、怎么搭建、按什么原则排版，以及写作时遵守的约定。

内容怎么组织

文章用三种方式组织，每种只回答一个问题：

方式 回答的问题 一篇文章可以有
标签 讲的是什么主题 多个
专栏 属于哪个系列、排第几篇 至多一个
AI 声明 有没有 LLM 参与撰写 有或没有

博客里的文章大致有两类：

  1. 笔者就某个问题与 LLM 讨论，形成自己的想法后，由 LLM 以 Blog 或 Essay 的形式整理成文。
  2. 已经基本成型的想法，由笔者以合适的体例写成。

这两类的区别在于谁执笔、想法成熟到什么程度，与主题无关，所以没有拿它来分区，而是在第一类文章顶部放一条醒目的 AI 声明，写明参与的模型。文章列表里也会用 AI 小标记区分。读者可以据此决定以什么态度读一篇文章。

一个成型的想法，往往来自前面若干次讨论。成型的文章会注明“本文源于”哪几篇对谈；被引用的对谈页面会自动出现“已整理为”的反向链接。顺着这些链接，可以看到一个想法是怎么一步步形成的。

博客不设分区：分区与标签的职责容易重叠，一篇文章也很难只属于一个分区。需要按主题浏览时，请用标签；需要按顺序读一组文章时，请用专栏；按时间浏览请看归档。

时间

每篇文章有两个时间，都精确到秒（东八区）：

  • 发布于：首次发布的时间，写好后不再改。
  • 最后编辑：自动取自该文件最后一次提交到 git 的时间；只改错字、调格式这类不影响内容的提交，会在提交信息里标 [minor]，不计入最后编辑时间。文件从发布后没有再修改过时不显示。

列表页为了紧凑只显示日期，鼠标悬停可看到完整时间。

标有“不定时更新”提示的文章（比如本页）会持续修改，请以最后编辑时间为准。

许可

  • 文章采用 CC BY-NC-ND 4.0：转载请署名并注明出处；禁止商业使用；禁止演绎，即不得修改、删节、翻译或改编。正常的引用不受此限。
  • 站点代码采用 MIT，欢迎借用。

文章与代码分开授权，是因为 Creative Commons 协议不适合软件：它不处理专利，也不区分源码与编译产物，与主流开源协议也不兼容。

由 LLM 参与撰写的文章，其著作权归属目前在法律上尚无定论，上述许可仅在笔者享有权利的范围内适用。

技术架构

  • 静态生成：用 Astro 在构建时把 Markdown 生成为纯 HTML，没有服务器和数据库。页面默认不加载 JavaScript，只有搜索、目录高亮、评论等少数交互才用。
  • 内容与代码分离：文章是放在 src/content/ 里的普通 Markdown 文件，不依赖框架专有语法，将来换框架也能整体搬走。
  • 元数据校验：每篇文章开头的 YAML 字段都有类型定义，写错字段、引用了不存在的专栏或来源文章，构建都会直接失败，不会把错误发布出去。
  • 稳定网址：文章网址固定为 /posts/<slug>/，与标题、标签、专栏无关；改标题、调整专栏都不会让旧链接失效。评论也按网址对应文章。
  • 数学公式：$...$ 与 $$...$$ 在构建时由 KaTeX 渲染为 HTML，浏览器端不运行脚本，只在需要时下载字体；公式有误会让构建失败。复杂的交换图用 quiver 绘制后以 SVG 插入。
  • 搜索：Pagefind 在构建后为全站生成静态索引，支持中文分词，无需后端。按 / 打开。
  • 评论：giscus，评论存放在本仓库的 GitHub Discussions 中，需要登录 GitHub。
  • 订阅：RSS 输出全文。
  • 部署：推送到 GitHub 后由 GitHub Actions 自动检查、构建并发布到 GitHub Pages。依赖每月由 Dependabot 合并成一个更新请求。
  • 双语预留：目前只写中文；界面文字集中在一处，网址结构为英文版（/en/...）留了位置，将来加入英文不影响现有链接。

源码见 GitHub。

排版与交互

设计的优先级是：可读性第一，操作便捷第二，设计感第三。 以电脑阅读为主要场景，手机上保证正常可读。

可读性

  • 正文 16px、行高 1.75，中文两端对齐；排版紧凑，一屏能容纳更多内容。正文最宽约 52 个汉字，侧栏折叠后向两侧扩展到这个宽度。
  • 使用系统自带的中文字体，不额外下载数 MB 的网页字体。
  • 文章头与正文之间有一道分隔线；二级标题下有一条通栏线，三级标题下有一条半栏线，层级一眼可辨。
  • 中西文之间自动留出间隙、标点自动挤压（取决于浏览器支持）。
  • 浅色与深色两套配色，默认跟随系统，可手动切换；文字与背景对比度满足 WCAG AA。

操作便捷

  • 按 / 搜索，↑↓ 选择，Enter 打开。
  • 电脑上是三栏布局，页头始终固定在顶部：
    • 左侧栏是站点导航：当前文章所属专栏的章节、按年份折叠的全部文章、专栏列表，当前位置高亮。
    • 右侧栏是目录：可在“简略 / 标准 / 详细”三档之间切换（分别显示到 ## / ### / #### 级标题），末尾有“评论”入口，高亮当前阅读的章节，底部显示阅读进度和“回到顶部”。
    • 两侧栏都可折叠（栏顶按钮，或按 [ / ]），折叠后正文随之变宽；折叠状态和目录详细程度会被记住。默认左侧栏折叠、右侧栏展开。
  • 每个小标题悬停可得到锚点链接，便于分享到具体段落；代码块可一键复制。
  • 链接在鼠标悬停时预加载，点击后几乎立即打开。
  • 专栏文章底部可在专栏内翻页，其他文章按时间翻页；归档页一行一篇，信息紧凑。

设计感

  • 克制：一种强调色，不做动画特效。

写作约定

新建文章：

npm run new <slug> "标题"

会自动填好精确到秒的发布时间，并生成一份正文骨架（开头段落、## 小节、结语）。生成的 src/content/posts/<slug>/index.md 默认是草稿（draft: true），删掉这一行即发布。文章开头的字段：

---
title: 标题                       # 必填
description: 一句话摘要            # 用于列表、搜索结果与分享卡片
published: 2026-11-07T20:00:00+08:00 # 必填，发布时间，精确到秒
updated: 2026-11-08T09:30:00+08:00   # 可选；不填则自动取 git 时间
tags: [范畴论, LLM]
series: category-theory           # 可选，专栏 ID（src/content/series/ 下的文件名）
order: 3                          # 在专栏中的序号
ai:                               # 有 LLM 参与撰写时必须填写
  model: Claude Opus 5.5
  note: 自定义声明（可省略）
from: [some-dialogue]             # 本文源于哪些文章（填 slug）
living: true                      # 会持续修改的文章
pinned: true                      # 置顶到首页
draft: true                       # 草稿：本地可见，线上不发布
---

几条约定：

  • slug 一经发布不再修改，只用小写字母、数字和连字符。确需修改时，在 astro.config.mjs 的 redirects 里加一条旧网址到新网址的跳转。
  • 正文从二级标题 ## 开始，标题由 title 字段生成。文章头（标题、时间、标签、声明）与正文之间的分隔线由布局自动加上，正文开头不必再写 ---。
  • 小标题用简短的名词短语，一般不超过十来个字：不写成完整的句子，不加“路径一：”“第一部分：”这类编号前缀，结语就叫“结语”。
  • 由 LLM 执笔的文章必须写 ai 字段。
  • 图片与文章放在同一目录，用相对路径引用；pptx、pdf 等大文件不放进仓库，放到 Releases 或网盘后给链接。
  • --- 分隔线的上一行要留空行，否则上一行会被当成标题。
  • 只改错字或格式的提交，在提交信息里加 [minor]。

本地预览：

npm run dev

示例文章（草稿，仅本地可见）演示了以上所有功能，可作为写作模板：src/content/posts/example-dialogue/ 与 src/content/posts/example-essay/。

评论