Jekyll 配置指南
通过 GitHub API 将文章发布到 Jekyll 静态博客仓库。
一、准备
- 一个可作为 Jekyll 博客仓库的 GitHub 仓库（如
terwer.github.io的gh-pages分支）。 - 一个对该仓库有 push 权限 的 GitHub Token（PAT）（GitHub Settings → Developer settings → Personal access tokens，勾选
repo权限）。 - 该仓库是一个标准 Jekyll 项目（含
_config.yml、_posts/、assets/目录）。
二、配置
| 字段 | 填什么 |
|---|---|
| 首页地址 | GitHub 首页地址，默认 https://github.com |
| API 地址 | GitHub API 地址，默认 https://api.github.com，通常无需修改 |
| 用户名 | GitHub 用户名（owner），用于拼出仓库地址 |
| 鉴权 Token | GitHub 个人访问令牌（PAT），需对目标仓库有 push 权限 |
| git 仓库名 | Jekyll 博客仓库名，与用户名组成 <user>/<repo>，如 terwer.github.io |
| 默认分支 | 发布到的分支，默认 main，需与仓库实际分支一致；Jekyll 站点常发布到 gh-pages |
| 存储目录 | Jekyll 文章存储目录，默认 _posts。发布后的 .md 写入该目录 |
| 文件规则 | 文章文件名规则，Jekyll 需带日期前缀，默认 [yyyy]-[mm]-[dd]-[slug].md |
| 文章预览规则 | 站点文章预览规则，默认 /post/[postid].html |
| 预览规则 | GitHub blob 预览规则，默认 /[user]/[repo]/blob/[branch]/[docpath] |
| 图床 | Jekyll 支持内置图床，选「当前平台」：图片上传到仓库 assets/images（默认），文章中引用为绝对路径 /assets/images/<图片名> |
三、图片与目录约定（Jekyll 官方规范）
- Jekyll 的
assets/目录构建时会被原样复制到站点根目录。放在assets/images/下的图片，站点根 URL 就是/assets/images/<图片名>（baseurl为空时）。 - 因此在 Markdown 中引用文章图片使用 绝对路径
/assets/images/<图片名>即可——构建产物（_site/）中该路径能正确解析到图片，这也是社区与官方文档推荐的引用方式。 - 文章的最终 URL（permalink）由 front matter 的
permalink决定：插件始终会写入该字段，「YAML 永久链接」开关只决定取值——开启时按「文章预览规则」生成（仅[postid]占位符生效），关闭时固定为/post/<slug>.html。因此不会回落到 Jekyll 默认规则。 - Jekyll front matter 中写
published: true时文章为发布状态（published默认true），构建时会被正常渲染。插件在「YAML 预设配置」留空时会自动写入layout: post与published: true；一旦填写该项，文章头改由你给的键决定，需自行包含这两项。
四、验证与发布
- 点「验证」→ Token、仓库、分支校验通过（会向仓库发布并清理测试文件）→ 保持「配置已保存并验证通过」。
- 快速发布 → 选 Jekyll → 发布。文章
.md会提交到存储目录/[yyyy]-[mm]-[dd]-[slug].md。 - 点「查看文章」能打开站点文章页；带图发布时图片会一并上传到仓库
assets/images并在文章中引用/assets/images/<图片名>。
图片存储路径
图床选「当前平台」时，可以指定图片存到仓库哪里：
| 字段 | 默认值 |
|---|---|
| 图片存储目录 | assets/images |
| 图片访问链接 | assets/images |
Jekyll 的图片放在 assets 下，引用时用相对站点根的路径。一般不需要改，改了请保证两个值对应。
常见问题
- 验证通过但发布失败：确认 Token 对目标仓库有 push 权限，仓库名与分支正确，存储目录已存在。权限不足会收到 401/403。
- 图片要怎么发布：选「当前平台」图床，图片上传到仓库
assets/images，文章中引用绝对路径/assets/images/<图片名>。因 Jekyll 构建时把assets/原样复制到站点根，构建产物能正常显示。 - 查看链接打不开：插件总会写入
permalink，所以线上地址由它决定：开启「YAML 永久链接」时取「文章预览规则」，关闭时固定/post/<slug>.html。若与预览规则不一致，改「文章预览规则」并保持开关开启即可（无需改主题 permalink）。另外请确认博客使用的主题/发布脚本会对仓库变更执行 Jekyll 构建（如 GitHub Pages 自动构建），否则新文章不会出现在线上站点。 - 发布后线上没有新文章：Jekyll 是通过构建（
jekyll build）从仓库内容生成站点的。GitHub Pages 会对仓库自动执行 Jekyll 构建；确认仓库配置了自动构建（GitHub Pages / Actions / Vercel / Netlify 等）；仅推送.md不会直接改变已部署站点，需触发一次构建。 - 更新与删除：点「更新」会重新提交并产生一次新提交；「删除」会从仓库移除对应
.md，需重新构建才能从站点移除。