静态站点生成器本质是构建时内容组装工具：将Markdown、配置文件和模板本地运行一次，输出纯HTML文件，可直接部署或双击运行；其核心流程包括Front Matter解析、Markdown渲染与模板填充。
静态站点生成器不是“编译器”，也不是“服务器”，它本质是一个构建时内容组装工具：把 Markdown 文件、_config.yml 配置、_layouts 模板三者在本地运行一次，输出一堆纯 .html 文件——这些文件扔到任何 HTTP 服务（甚至双击打开）都能直接运行。
Markdown 解析 + Front Matter 提取是所有 SSG 的起点
每个内容文件顶部的 --- 包裹块（YAML 格式）就是 Front Matter。SSG 必须先分离它和正文，否则无法知道标题、日期、是否发布等元信息。
- 常见错误：用
fs.readFileSync()直读整个.md文件却没做分隔解析，导致title字段始终为undefined - Hugo 默认用
---，Jekyll 允许改用+++或~~~，但解析逻辑必须同步适配 - 正文部分交给 Markdown 解析器（如
marked、remark、goldmark），注意：不同解析器对表格、脚注、数学公式支持程度差异大，hugo默认不支持 LaTeX，需插件；11ty需手动配置remark-math - Front Matter 中的字段名大小写敏感，
date和Date在hugo中会被视为两个不同变量
模板引擎决定页面结构灵活性与学习成本
没有模板引擎，SSG 只能生成千篇一律的 HTML；选错引擎，会导致条件渲染写不出来、数据嵌套层级错乱、甚至构建失败。
-
hugo用Go Template：语法紧凑（{{ .Title }}），但括号嵌套易出错，range循环中访问父级变量需显式用$（如{{$ := .}} {{range .Pages}} {{$.Site.Title}}{{end}}） -
jekyll用liquid：语法宽松（{{ page.title }}），支持过滤器（| date: "%Y"），但不支持原生函数定义，复杂逻辑得靠插件 -
11ty支持多种引擎，默认liquid，也可切nunjucks或javascript函数：后者适合已有 JS 工具链团队，但模板里写async会报错——SSG 构建阶段不支持异步渲染 - 避免在模板里调用外部 API：构建时网络不可靠，且违背“静态”本质；想动态内容，应提前用脚本拉取并存为
data.json再注入模板
输出目录结构必须与部署路径对齐，否则链接全挂
hugo build 默认输出到 public/，jekyll build 输出到 _site/，但这只是起点。真实问题出在路径引用上。
生成可在 deepbi 沙箱 iframe 内运行或作为独立文件运行的交互式 HTML 页面，使用 `window.deepbi` JS SDK 实现数据查询、空间管理、文件浏览及用户操作。当用户提出以下需求时启用该能力： - 创建 KPI 仪表盘、数据表格、文件浏览器、成员列表、管理页面； - 明确要求“转成 dhtml”、“转译成 HTML”、“把 XX 页面转成……”、“控制台页面”、“管理后台”、“DeepBI 页面迁移”； - 提及位于 `apps/console/src/featur
立即学习“前端免费学习笔记（深入）”；
- 所有 CSS/JS 图片路径必须用相对路径或根相对路径（
/css/style.css），禁用绝对 URL（https://example.com/css/style.css），否则本地预览正常、GitHub Pages 上 404 - 页面内跳转链接（如
<a href="about.html"></a>）要和实际生成的文件名、目录层级完全一致；hugo默认把content/about.md渲染成public/about/index.html，所以链接应写<a href="about/"></a>，而非<a href="about.html"></a> -
baseURL配置项只影响<link>、<script></script>等资源路径拼接，不影响页面内<a></a>链接逻辑——这点很多人误以为设了baseURL就万事大吉 - Netlify/Vercel 自动识别
public/或dist/目录，但 GitHub Pages 要求是docs/或根目录，需在 CI 脚本里mv public docs或改hugo -d docs
为什么不用 Next.js/Gatsby 做纯静态站？它们不是更现代吗？
Next.js 的 next export 和 Gatsby 的 gatsby build 确实能输出静态文件，但它们的底层模型和传统 SSG 不同：它们默认按“路由优先”组织，而不是“文件优先”。这带来几个隐性代价。
- 每个页面必须有对应
pages/about.js或src/pages/about.jsx，无法像hugo那样直接往content/丢一个about.md就自动生成——内容作者得懂 React 组件结构 - 即使你只导出静态 HTML，构建过程仍依赖 Webpack/Babel，
node_modules动辄百 MB，CI 构建时间比hugo（单二进制，无依赖）慢 3–5 倍 - Gatsby 强制要求 GraphQL 数据层，哪怕你只有 5 个 Markdown 文件，也得写
gatsby-node.js去创建节点；而hugo或11ty直接读文件、渲染、完事 - SEO 友好性不等于“用了 Next.js 就 SEO 好”：如果页面内容由
useEffect+fetch加载，next export输出的 HTML 里仍是空容器——静态生成的前提是数据必须在构建时可获取
最常被忽略的一点：SSG 的“静态”指的是输出物，不是开发体验。你可以用 TypeScript 写 11ty 配置、用 Tailwind 编译 CSS、用 prettier 格式化 Markdown——只要最终产物是无需运行时环境的 HTML 文件，它就符合静态站定义。别被“工具链越重越先进”的惯性带偏，先问清楚：你的内容更新频率、协作角色、部署平台，是否真的需要 React 组件抽象层。
