根本原因是模板嵌套路径未对齐或ParseFiles未加载子模板；必须显式传入所有模板文件，避免嵌套define，确保template名与define名完全一致，调试用tmpl.Templates()。
用 html/template 渲染文章页时，为什么变量不显示或报 template: …: no such template
根本原因通常是模板嵌套路径没对齐，或者 ParseFiles 没加载到子模板。Go 的模板系统默认不递归解析 {{template "xxx"}} 引用的文件，必须显式把所有用到的模板文件一次性传给 ParseFiles。
实操建议：
- 所有被
{{template}}调用的子模板（比如header.html、footer.html）必须和主模板一起传进tmpl.ParseFiles("layout.html", "header.html", "footer.html")，缺一个就报错 - 避免在
{{define}}里嵌套{{define}}—— Go 模板不支持嵌套定义，会静默忽略内层 - 如果用
{{template "main" .}}，确保有对应{{define "main"}}块，且名字完全一致（区分大小写） - 调试时加一句
log.Println(tmpl.Templates())，能直接看到当前解析了哪些命名模板
ioutil.WriteFile 和 os.WriteFile 在生成静态文件时怎么选
Go 1.16+ 应该无条件用 os.WriteFile —— ioutil 已被弃用，且它底层调用的就是 os.WriteFile，没额外价值。
容易踩的坑：
立即学习“go语言免费学习笔记（深入）”；
-
os.WriteFile("posts/2024-01-01-hello.html", data, 0644)中的权限位是os.FileMode，不是字符串，别写成"0644" - 目标目录（如
posts/）必须已存在，os.WriteFile不会自动创建父目录；要用前先os.MkdirAll("posts", 0755) - 如果并发生成多个文件，注意
os.WriteFile是覆盖写入，别误删旧内容；需要追加请换os.OpenFile+Write
读取 Markdown 文件并渲染成 HTML 时，blackfriday 和 goldmark 该怎么选
goldmark 是当前事实标准，blackfriday 已归档停更。新项目别碰 blackfriday，尤其涉及自定义语法或扩展性需求时。
关键差异点：
-
goldmark默认不解析 HTML 标签（安全），要允许需显式加选项：goldmark.WithExtensions(extension.WithHTML()) -
goldmark的 AST 处理更清晰，比如想提取文章标题或首图，可遍历ast.Node而非正则硬扒 - 如果只做简单转换，
goldmark+extension.GFM（支持表格、任务列表）一行搞定：goldmark.New(goldmark.WithExtensions(extension.GFM)).Convert(src, dst) -
blackfriday.Run返回[]byte，而goldmark.Convert需要传入io.Writer，别直接拿返回值当字符串用
生成器跑起来后，为什么本地预览 HTML 打不开或样式丢失
本质是路径问题：静态资源（CSS/JS/图片）的引用路径，在生成时写死为相对路径，但浏览器双击打开 file:// 协议时，相对路径解析规则和 HTTP Server 完全不同。
解决方向很窄，只有两个靠谱做法：
- 开发阶段强制走本地 HTTP Server，比如用
go run -m ./cmd/serve启一个http.FileServer，访问http://localhost:8080，而不是双击 HTML - 所有资源路径统一用绝对路径（以
/assets/开头），并在生成时确保输出目录结构匹配，例如 CSS 输出到public/assets/style.css，HTML 中写<link href="/assets/style.css"> - 别用
../css/style.css这类向上跳的相对路径 ——file://下它可能指向你家根目录
最常被忽略的是：生成器本身不负责启动服务，但用户总想双击运行，结果卡在路径上折腾半天。得提前在 README 里写清楚“必须用 HTTP Server 预览”。
