这个站是怎么搭起来的

这是这个站的第一篇文章，写它有两个目的：一是记一下这个博客到底是怎么组织内容的，二是把 Markdown 渲染管线支持的能力过一遍，确认公式、代码高亮、流程图这些都能正常工作。

目录结构就是分类 #

content/ 下的一级目录名就是分类。这篇文章存在 content/随笔/第一篇.md，所以它属于「随笔」分类，URL 是 /posts/随笔/第一篇。写作时不用在 frontmatter 里手动指定分类，也不用维护一份分类列表——新建一个目录，就相当于新增了一个分类。

具体的组织规则是：

• content/_pages/ 下的文件是独立页面（比如「关于」），不出现在文章列表、分类和标签里
• 其余目录下的 .md 文件都算文章，一级目录名作为它的分类
• 文件名本身不重要，只会被转成 URL 里的 slug

frontmatter 全部可选 #

这篇文章的开头写了 title、date、tags、summary 四个字段，但其实一个都不是必须的：标题缺失会取正文第一个一级标题，日期缺失会用文件的修改时间，摘要缺失会自动从正文截取。真正想偷懒的时候，一个 .md 文件从头到尾不写 frontmatter 也能正常发布。

素材跟着文章走 #

图片这类素材，和文章放在一起最省事——本地怎么组织，原样复制进 content/ 就能用：

content/随笔/
  第一篇.md
  第一篇/                  ← 与文章同名的目录，放这篇文章用到的图
    目录即分类.jpg
    素材跟着文章走.png

正文里用相对路径引用，基准是 md 文件所在的目录，和本地编辑器、GitHub 上看到的一致：

渲染时相对路径会被改写成站内地址 /assets/随笔/第一篇/目录即分类.jpg， 所以整个目录搬到别处、或者从本地整包 scp 上来，正文一个字都不用改。

多种图片格式都支持，PNG 同样可以：

点开任意一张图会进看图器，可以缩放、旋转、拖动，按 Esc 或点灰色背景退出。

渲染管线要过一遍所有能力 #

写这篇文章顺便做个自检：markdown-it 装的插件、shiki 的高亮效果、mermaid 出图、公式渲染，一次性都验证一遍。

数学公式 #

行内公式不会打断阅读，比如质能方程 $E = mc^2$，或者高斯积分里用到的 $\sigma$。

块级公式单独成行，居中展示：

$$\int_{-\infty}^{\infty} e^{-x^2}\,dx = \sqrt{\pi}$$

代码高亮 #

内容监听那部分用了一个简单的防抖，把连续到达的文件变更事件合并成一次重建：

// 合并连续到达的文件变更事件，避免批量上传时反复重建索引
function debounce(fn, wait) {
  let timer = null;
  return (...args) => {
    clearTimeout(timer);
    timer = setTimeout(() => fn(...args), wait);
  };
}

流程图 #

一篇文章从落地到能被访问，大致要经过这几步：

flowchart LR
  A[写 md 文件] --> B[scp 上传到 content/]
  B --> C[chokidar 监听到变更]
  C --> D[解析 frontmatter 与正文]
  D --> E[渲染 HTML 并缓存]
  E --> F[浏览器请求页面]

渲染能力小结 #

用一张表把用到的插件和各自负责的能力对一下：

写作时用得上的小工具 #

日常写文章会碰到的几类语法：

• 无序列表：像这一条一样，用 - 或 * 开头
• 图片：与文章同名的目录里放图，正文用相对路径 ![说明](第一篇/xxx.png)； 全站通用的图仍可放 public/images/，用绝对路径 /images/xxx.png 引用
• 草稿：frontmatter 加 draft: true，不出现在列表里，但加上 ?preview=1 还能单独预览
• 置顶：frontmatter 加 pinned: true，会排到文章列表最前面

脚注也是常用的一种补充说明方式，不打断正文阅读^[1]。

写在最后 #

这些渲染能力平时一篇文章用不到一半，但发布前一次性过一遍，比日后遇到公式不显示、图表不出图再回头排查要踏实得多。

---

1. 这是一条示例脚注，点击上标数字可以跳转到这里，正文里点脚注编号旁的返回箭头能跳回去。 ↩︎