Jekyll仅复制.md文件未转换为.html文件，求排查原因

AI 小北

2026-5-20

解决Jekyll不渲染Markdown文件仅复制的问题

我之前也踩过一模一样的坑！Jekyll生成_site目录后直接把.md文件原封不动复制进去，完全不转成HTML，通常是这几个原因导致的，你可以逐一排查：

Markdown文件缺少YAML Front Matter
Jekyll默认只会识别带有Front Matter的文件并进行渲染。你只需要在每个.md文件的最顶部加上至少空的Front Matter块：
```
---
---
```
要是嫌一个个加太麻烦，也可以在_config.yml里配置默认值，给所有符合条件的文件自动绑定布局（前提是你的_layouts目录里有对应的布局文件，比如基础的default.html）：
```
defaults:
  - scope:
      path: ""
      type: "pages"
    values:
      layout: "default"
```
文件存放位置不符合Jekyll规则
- 如果你的.md文件放在自定义目录（比如docs/、notes/）里，Jekyll默认会把整个目录当作静态资源复制，不会处理里面的文件。你需要在_config.yml里把这个目录加入include列表：
```
include: ["docs"]
```
- 要是放在_posts目录里，文件名必须严格遵循YYYY-MM-DD-自定义名称.md的格式，否则Jekyll不会把它当作博客文章处理，只会直接复制。
配置或布局文件有问题
- 检查_config.yml里有没有开启safe: true，安全模式下Jekyll会限制很多功能，包括自定义目录的文件处理，改成safe: false试试。
- 如果你的.md文件里指定了layout: xxx，但_layouts目录里没有对应的xxx.html布局文件，Jekyll可能会跳过渲染。可以先去掉布局指定，或者创建一个基础的default.html布局文件。
Jekyll版本兼容问题
如果你用的是较新的Jekyll版本，一些旧的配置可能失效。可以尝试更新Jekyll到最新稳定版，或者检查_config.yml里的markdown配置（默认是kramdown，不要改成错误的渲染器）。