GitPages无法识别{% include %}与{% static %}语句的原因排查

1. {% include %}和{% static %}未被识别的原因 #

GitHub Pages默认只支持Jekyll（Liquid模板语法），你用的{% include %}和{% static %}是Jinja2模板语法（常见于Django、Flask），GitPages不会自动解析这类标签，所以会直接把标签原样输出在页面上。

2. 静态文件路径出现奇怪字符的原因 #

因为Jinja2的{% static %}标签没被解析，浏览器把{% static 'circleselfie.png' %}这类字符串当成了完整的文件路径，其中的%、{等属于URL特殊字符，自然会显示成“奇怪字符”。

解决办法 #

方法一：改用Jekyll语法适配GitPages #

• 替换{% include %}：Jekyll的include语法是{% include 文件名.html %}，需要把要引入的文件放到仓库根目录的_includes文件夹里（没有就新建）。
• 替换{% static %}：
  1. 在仓库根目录新建_config.yml文件，添加内容：baseurl: "/JSite"（你的仓库名是JSite，GitPages站点路径会包含仓库名）
  2. 把静态文件（css、图片等）放到assets目录下，比如assets/css/home.css、assets/images/circleselfie.png
  3. 用Jekyll路径写法替换：{{ site.baseurl }}/assets/css/home.css、{{ site.baseurl }}/assets/images/circleselfie.png
• 注意：如果仓库里有.nojekyll文件，删掉它（这个文件会禁用GitPages的Jekyll解析功能）。

方法二：本地渲染成纯HTML再上传 #

如果你的页面是用Django等框架生成的，本地运行项目后，把浏览器里的纯HTML源码复制出来，替换仓库里的index.html，同时把静态文件路径改成相对路径（比如./assets/css/home.css）或者适配GitPages的绝对路径（/JSite/assets/css/home.css），再上传到仓库即可。

内容的提问来源于stack exchange，提问作者champa