这是一篇"活模板":每次写新文章时,把本文复制一份、用英文命名,替换标题与日期,正文换成自己的内容即可。

快速上手(三步)

  1. 连上 VPN 打开 /files 后台,进入 content/posts/ 目录;
  2. 复制本文或新建 .md 文件——文件名用英文,它决定 URL(my-note.md → /posts/my-note/),中文文件名会变成一长串百分号编码;
  3. 改好标题和日期,保存后约 3 秒自动构建发布,5 分钟内自动推送到 Gitea 备份。

front matter 模板

文件必须以单独成行的三个短横线开始和结束,围栏线上下都不能有任何多余字符(哪怕是空格或反斜杠——这是最常见的翻车点):

---
title: "文章标题(可中文)"
date: 2026-10-08T19:10:00+08:00
draft: false
tags: ["标签1", "标签2"]
categories: ["分类"]
summary: "摘要,显示在列表页"
---

三条硬规则:

  • date 不能晚于当前时间,否则 Hugo 视为定时文章不予发布(想定时就到点后随便改一下文件触发重建);
  • draft: true 是草稿,不发布,写完记得改回 false;
  • 正文不要再写一行 # 大标题——页面会自动渲染 front matter 里的标题,写了会重复。

格式速查

粗体、斜体、行内代码,emoji 直接写 👋(站点已开启 emoji 渲染)。

引用块:适合放背景说明、注意事项。

三级标题

  • 无序列表项一
  • 无序列表项二
  1. 有序列表项一
  2. 有序列表项二

链接文字 的写法如左。

表头一表头二
单元格单元格

代码块(指定语言可有高亮):

# 在后台改完文件后查看构建状态
sudo docker logs -f blog-builder

图片的两种方式

方式一:图床外链——直接贴完整 HTTPS 地址(防盗链图床会裂图):

![图片描述](https://你的图床地址/图片.png)

方式二:本地图片——先上传到 static/images/ 目录,再用站内绝对路径引用:

![图片描述](/images/文件名.png)

发布流水线(背后发生的事)

保存文件 → builder 容器 3 秒内自动 hugo 构建 → 成功则替换线上页面并自动 git 提交(blog-bot)→ 宿主机定时任务 5 分钟内推送到自建 Gitea。

构建失败时线上保留上一版,不会白屏;排错命令:

sudo docker logs --tail 20 blog-builder