静态站点生成器（SSG）通过构建时自动组装内容、模板和配置生成可直接部署的HTML文件；需正确解析Front Matter、匹配渲染器特性、选对模板引擎、统一路径规则，并确保所有数据在构建前注入。
静态站点生成器不是“把 HTML 写一遍再复制粘贴”，而是构建时自动组装内容、模板和配置，一次性输出可直接部署的 .html 文件——本地双击能打开，扔到 GitHub Pages 或 Netlify 上就能访问。
Front Matter 解析失败导致 title/date 为空
几乎所有 SSG（如 Hugo、Jekyll、Eleventy）都依赖文件顶部的 --- 包裹块提取元数据。常见错误是：用 fs.readFileSync() 直读整个 .md 文件却没做分隔，结果 .Title 始终为 undefined。
-
Hugo默认用---，Jekyll允许配成+++或~~~，但解析逻辑必须同步改 -
date和Date在Hugo中是两个不同字段，大小写敏感 - 若手动写解析逻辑，推荐用现成库如
gray-matter（Node.js）或yaml+ 字符串切分，别自己正则硬拆
Markdown 渲染器不支持数学公式或表格嵌套
不同渲染器对扩展语法的支持差异很大：marked 默认不支持 LaTeX，remark 需配 remark-math 插件，goldmark（Hugo 默认）需显式启用 math 扩展。
- 表格里嵌套列表？
marked不认，remark可以，但需开remark-gfm - 脚注在
Jekyll中默认关闭，得在_config.yml加kramdown: footnote_backlink: false - 如果只是偶尔需要公式，别全量换渲染器——先试用
$$...$$块级语法，再查当前引擎是否原生支持
模板引擎选错导致循环取不到父级数据
Go Template（Hugo）、Liquid（Jekyll）、Nunjucks（11ty）三者语法习惯和作用域规则完全不同。
立即学习“前端免费学习笔记（深入）”；
- 在
Hugo的{{range .Pages}}里想访问站点标题？得先写{{$ := .}}，再用{{$.Site.Title}} -
Jekyll的{{ page.title }}看似简单，但无法定义函数，复杂逻辑只能靠插件或提前处理好数据 -
11ty支持 JS 函数当模板，但注意：构建阶段不执行异步代码，async模板会直接报错
生成路径与部署路径不一致引发 404
Hugo 默认输出到 public/，Jekyll 是 _site/，但这只是起点。真正出问题的是路径引用方式。
- CSS/JS 图片必须用相对路径（
../css/style.css）或根相对路径（/css/style.css），禁用绝对 URL（https://example.com/css/style.css） - 页面内跳转链接（如
<a href="/about/">）必须和实际生成的文件名、目录层级完全一致；Hugo默认把content/about.md渲染成public/about/index.html，不是public/about.html - GitHub Pages 用户常踩坑：用
gh-pages分支部署时，若项目不在根目录（比如在my-blog/下），所有路径要加子路径前缀，否则本地预览正常、上线全 404
最易被忽略的一点：所有数据注入（包括从 API 拉取的内容）必须在构建前完成，不能在模板里实时调用 fetch——构建时网络不可靠，且违背“静态”本质。真要动态内容，得提前用脚本拉下来存成 _data/posts.json 再注入模板。
