本文章没有找到对应的语言版本

1.hugo博客的文章规范

Markdown 写作格式：

---
title: "{{ replace .Name "-" " " | title }}"
description: "{{ .Name }}"
keywords: "{{replace .Name "-" ","}}"

date: {{ .Date }}
lastmod: {{ .Date }}

math: false
mermaid: false

categories:
  -
tags:
  -
  -
---
{{ replace .Name "-" " " | title }}

格式说明：

前置元数据（Front Matter）部分：

  • title - 文章标题（自动从文件名生成）
  • description - 文章描述（自动从文件名生成）
  • keywords - 文章关键词（自动从文件名生成，用逗号分隔）
  • date - 文章发布日期
  • lastmod - 文章最后修改日期
  • math - 是否启用数学公式（boolean）
  • mermaid - 是否启用 Mermaid 图表（boolean）
  • categories - 文章分类（列表）
  • tags - 文章标签（列表）

正文部分：

  • 自动生成的标题
  • <!--more--> - 摘要分割线，这行之前的内容将作为文章摘要显示在列表页

2.创建博客的注意事项

当你需要使用他人的模板，一般都会使用子模板来引入作者的仓库，如果你需要自己定义，需要将子模板取消并入自己的总仓库内。 当前 themes/reimu 已经是主仓库内的普通目录（主题文件完整复制进来），不再是子模块，.gitmodules 也已删除，所以下面的操作属于历史记录，日后无需重做。

1. 删除子模块的 Git 元数据，但保留实际文件 

cd /d/blog

# 1. 把子模块里的 .git 文件夹移动走（或者直接删除，但为了安全先备份）
mv themes/reimu/.git themes/reimu/.git.bak

# 2. 从主仓库的 Git 索引中移除子模块记录（但不删除实际文件）
git rm --cached themes/reimu
执行 git rm --cached 后，themes/reimu 这个路径会变成未跟踪的文件（因为之前是子模块，现在 .git 没了，Git 看到的是普通文件夹）。

2. 把主题文件正式加入主仓库 

# 将 themes/reimu 下的所有文件加入 Git 索引
git add themes/reimu/

# 查看状态，确认 themes/reimu 变成了普通文件
git status
此时你应该看到类似：

text
new file:   themes/reimu/...

3. 清理子模块配置 

# 删除 .gitmodules 文件（如果存在）
rm -f .gitmodules

# 从 .git/config 中删除子模块配置（可选，因为无影响）
git config --remove-section submodule.themes/reimu 2>/dev/null

4. 提交变更 

git commit -m "将主题解除子模块状态，成为仓库直接内容"

5. 推送到你自己的远程仓库 

git push origin main

6. （可选）删除备份的 .git.bak

确认一切正常后：

bash```
rm -rf themes/reimu/.git.bak

日常调试

本地运行需要 Hugo extended（主题强制要求 extended 版本，普通版编译 SCSS 会报错），且版本不低于 0.124.0。

# 在博客根目录执行，默认地址 http://localhost:1313/
hugo server

Hugo 的可执行文件不必装到系统 PATH，放在仓库内随手用也可以：

& .tools\hugo.exe server

仓库结构规范

位置 作用 是否入库
content/ 文章源文件（Markdown） ✅ 必须入库
hugo.toml 站点配置 ✅ 必须入库
config/_default/params.yml 站点级主题参数（覆盖主题默认值，避免改主题内部文件） ✅ 必须入库
static/ 图片等静态素材的源目录 ✅ 必须入库
themes/reimu/ 主题（已并入主仓库） ✅ 必须入库
public/ hugo 生成的输出目录 ❌ 不入库
resources/_gen/ Hugo 资源缓存，哈希名随版本变化 ❌ 不入库
.hugo_build.lock Hugo 运行时锁文件 ❌ 不入库

这些忽略规则写在根目录的 .gitignore 里。

为什么图片必须放在 static/：Hugo 构建时只把 static/ 的内容复制进 public/。如果直接把图片塞进 public/，用 hugo --cleanDestinationDir 构建时 Hugo 会认为「这个文件没有源文件」而把它删掉，图片就丢了。把图放进 static/ 才能躲过清理，也能随时从源文件重新构建出整个站点。

文章里引用图片用站点绝对路径（不带 baseURL），例如 ![](/post-images/uml0.jpg)。

背景图的设置

封面图存储在 static/covers/ 目录中，使用时用相对路径："covers/文件名.后缀"。

例如 front matter：

banner: "covers/窗边未花.webp"
cover: "covers/窗边未花.webp"

banner 控制文章头图（也是全站默认背景，在 config/_default/params.yml 里配置），cover 控制文章列表页的封面。两者都写时头图优先用 banner。

随机封面池：themes/reimu/data/covers.yml 里维护了一个封面路径列表，没有写 cover 的文章会从池中随机取一张。新增图片时：

  1. 把图片转成 webp 放入 static/covers/；
  2. 在 themes/reimu/data/covers.yml 里追加一行 - "covers/文件名.webp"。

文章插图放在 static/post-images/，引用写 /post-images/文件名。