Jekyll 默认不渲染\_posts目录下的.html文件，需添加front matter并指定layout才能触发Liquid解析和布局应用。
HTML 页面直接扔进 _posts 里为啥不渲染？
因为 Jekyll 默认只处理 .md 和 .markdown 后缀的文件，.html 文件放进 _posts/ 目录下会被原样拷贝，不走 Liquid 渲染流程，也不加布局（layout），更不会解析 front matter。
常见错误现象：_posts/2024-01-01-about.html 在站点里能访问，但标题没显示、侧边栏没加载、CSS 不生效——它根本没被当“文章”处理。
- 必须把文件后缀改成
.html且显式声明layout，否则 Jekyll 当静态资源处理 - front matter 必须顶格写，且用
---包裹，哪怕只写一行layout: post - 如果页面含
{{ content }}或其他 Liquid 标签，不加layout就完全不解析
怎么让纯 HTML 页面走 Jekyll 渲染流程？
核心就一条：给 HTML 文件加上合法 front matter，并指定 layout。Jekyll 看到带 front matter 的 .html 文件，就会按模板流程处理，而不是当静态文件复制。
实操建议：
- 在 HTML 文件最开头插入：
--- layout: post title: "我的旧页面" ---
-
layout值必须对应_layouts/下真实存在的文件名（不含后缀），比如post.html→ 写layout: post - 如果只是想套个基础壳，用
layout: default最稳妥，前提是_layouts/default.html存在 - 路径别放错：HTML 文件放在
_posts/下才参与日期归档；放/根目录或about/子目录下，则需手动配permalink才能控制 URL
import 大量传统 HTML 页面时要注意什么？
批量迁移不是改后缀+加 front matter 就完事。Jekyll 会按日期排序、生成分页、注入变量，这些行为和原始 HTML 的结构预期可能冲突。
容易踩的坑：
- 原始 HTML 里的相对路径（如
./css/style.css）在 Jekyll 里大概率 404——Jekyll 输出后路径层级变了，得统一用{% raw %}{{ '/css/style.css' | relative_url }}{% endraw %}生成正确链接 - 如果原页面含内联 JavaScript，注意
{{和}}会被误解析为 Liquid 语法，要么用{% raw %}{% raw %}...{% endraw %}{% endraw %}包裹，要么改用[if lt IE 9]风格注释绕过 - Jekyll 默认把所有
_posts下文件按文件名日期排序，如果你的 HTML 没按YYYY-MM-DD-title.html命名，就得加date:字段，否则排序乱、归档错
为什么有时候加了 layout 还是白屏或报错？
最常见的原因是 layout 文件本身出问题，或者 layout 引用了不存在的 include / data 文件，导致整个页面渲染中断。
排查方向：
- 检查
_layouts/post.html是否真存在，且没有语法错误（比如漏了{% raw %}{% endraw %}闭合） - 运行
jekyll build --trace，看报错具体卡在哪个{% raw %}{% include %}{% endraw %}或{% raw %}{% for %}{% endraw %}上 - 临时把 layout 简化成纯 HTML +
{{ content }}，确认是否 layout 层的问题 - 注意
include路径：Jekyll 的{% raw %}{% include header.html %}{% endraw %}只认_includes/header.html，不支持子目录嵌套写法（除非用{% raw %}{% include snippets/header.html %}{% endraw %}）
Jekyll 对 HTML 文件的“接纳”是有条件的：它不拒绝你写 HTML，但要求你明确表态——这页要走哪条渲染链路。漏掉 front matter、写错 layout 名、忽略路径重写，都会让页面卡在“半解析”状态。真正麻烦的不是转换动作本身，而是旧 HTML 里那些隐式依赖：硬编码路径、全局变量、手写的导航逻辑——它们在 Jekyll 里全得重新锚定。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
