这是一篇"活模板":每次写新文章时,把本文复制一份、用英文命名,替换标题与日期,正文换成自己的内容即可。
快速上手(三步)
- 连上 VPN 打开
/files后台,进入content/posts/目录; - 复制本文或新建
.md文件——文件名用英文,它决定 URL(my-note.md→/posts/my-note/),中文文件名会变成一长串百分号编码; - 改好标题和日期,保存后约 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 渲染)。
引用块:适合放背景说明、注意事项。
三级标题
- 无序列表项一
- 无序列表项二
- 有序列表项一
- 有序列表项二
链接文字 的写法如左。
| 表头一 | 表头二 |
|---|---|
| 单元格 | 单元格 |
代码块(指定语言可有高亮):
# 在后台改完文件后查看构建状态
sudo docker logs -f blog-builder
图片的两种方式
方式一:图床外链——直接贴完整 HTTPS 地址(防盗链图床会裂图):

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

发布流水线(背后发生的事)
保存文件 → builder 容器 3 秒内自动 hugo 构建 → 成功则替换线上页面并自动 git 提交(blog-bot)→ 宿主机定时任务 5 分钟内推送到自建 Gitea。
构建失败时线上保留上一版,不会白屏;排错命令:
sudo docker logs --tail 20 blog-builder