Hugo不支持直接使用裸HTML文件，必须通过layouts模板机制渲染；需将HTML拆解为baseof、partials和content结构，静态资源放static或assets，注意baseURL和路径引用。
HTML模板怎么放进Hugo里直接用
Hugo不接受裸HTML文件当页面，必须通过layouts目录下的模板机制参与渲染。把一个现成的index.html直接丢进content/或static/，它不会被Hugo解析变量、不会套主题、也不会生成href链接——只是原样复制过去。
正确做法是把HTML结构拆解进Hugo模板体系：
- 把页面主体（比如
<main>...</main>）挪到layouts/_default/single.html或对应类型的模板中 - 把重复结构（头部、导航、脚部）抽成
layouts/partials/header.html等，用{{ partial "header" . }}调用 - 把想动态填充的内容（标题、日期、描述）换成Hugo语法，比如
{{ .Title }}、{{ .Date | time.Format "2006-01-02" }} - 静态资源（CSS/JS/图片）必须放
assets/（供Hugo管道处理）或static/（原样拷贝），不能混在layouts/里
Hugo构建时HTML没生效，常见卡点在哪
最常踩的坑是路径和上下文错位：Hugo模板里的.Content只读取content/下Markdown文件的渲染后HTML，不是读取你手写的HTML文件；而static/下的HTML压根不走模板流程，连{{ .Site.Title }}都显示为空。
典型错误现象：
立即学习“前端免费学习笔记（深入）”；
- 页面打开空白或只有文字，
<link rel="stylesheet">404 → 检查CSS是否放在static/css/style.css，且href写的是/css/style.css（开头带/） - 模板里写
{{ .Title }}但啥也不显示 → 确认该页面对应content/about.md存在，且含title: "About"front matter - 用
hugo server -D能看到页面，但hugo生成后缺失 → 检查config.toml里有没有publishDir = "docs"之类覆盖默认public/，或buildDrafts = true没关
要不要把现有HTML全重写成Hugo模板
没必要一刀切。Hugo支持「渐进式接入」：保留大部分HTML结构，只用最少模板逻辑接管关键部分。
适用场景与建议：
- 单页站点（如官网首页）→ 直接用
layouts/index.html，里面写满HTML，仅嵌入{{ .Site.Params.heroText }}这类简单变量 - 博客类多页 → 必须用
content/posts/my-post.md+layouts/_default/list.html+single.html组合，否则分页、RSS、分类都失效 - 已有大量纯HTML文档（如文档页）→ 放
static/docs/，然后在菜单里用url = "/docs/guide.html"硬链，绕过Hugo渲染更省事 - 需要SEO优化的页面（如
<meta name="description">）→ 必须走layouts/_default/baseof.html，用{{ with .Description }}<meta name="description" content="{{ . }}">{{ end }}
HTML转Hugo后本地预览正常，但GitHub Pages部署失败
根本原因通常是路径基准（baseURL）和资源引用方式不匹配。GitHub Pages子路径（如https://user.github.io/repo-name/）要求所有资源路径以/repo-name/开头，但本地hugo server默认用http://localhost:1313/。
解决步骤：
- 在
config.toml里设baseURL = "https://user.github.io/repo-name/"（注意结尾/） - 所有静态资源引用改用
{{ "css/main.css" | relURL }}或{{ "img/logo.png" | absURL }}，别写死/css/main.css - 确认
deploy.sh或GitHub Actions里执行的是hugo --destination docs（不是public），且docs/是GitHub Pages源目录 - 检查
config.toml里有没有canonifyURLs = true，开启后会强制把相对URL转绝对，容易在子路径下出错，建议关掉
真正麻烦的不是语法转换，是路径语义从“文件系统相对”变成“站点根相对”那一刻，所有../和/都要重新校准。稍不注意，CSS加载了但字体404，或者菜单跳转到404页——这种问题得开浏览器Network面板逐个看请求地址才能揪出来。
